Struct Query 

pub struct Query<T>(pub T);

Available on crate feature query only.

Extractor that deserializes query strings into some type.

T is expected to implement serde::Deserialize.

Differences from axum::extract::Query

This extractor uses serde_html_form under-the-hood which supports multi-value items. These are sent by multiple <input> attributes of the same name (e.g. checkboxes) and <select>s with the multiple attribute. Those values can be collected into a Vec or other sequential container.

Example

use axum::{routing::get, Router};
use axum_extra::extract::Query;
use serde::Deserialize;

#[derive(Deserialize)]
struct Pagination {
    page: usize,
    per_page: usize,
}

// This will parse query strings like `?page=2&per_page=30` into `Pagination`
// structs.
async fn list_things(pagination: Query<Pagination>) {
    let pagination: Pagination = pagination.0;

    // ...
}

let app = Router::new().route("/list_things", get(list_things));

If the query string cannot be parsed it will reject the request with a 400 Bad Request response.

For handling values being empty vs missing see the query-params-with-empty-strings example.

While Option<T> will handle empty parameters (e.g. param=), beware when using this with a Vec<T>. If your list is optional, use Vec<T> in combination with #[serde(default)] instead of Option<Vec<T>>. Option<Vec<T>> will handle 0, 2, or more arguments, but not one argument.

Example

use axum::{routing::get, Router};
use axum_extra::extract::Query;
use serde::Deserialize;

#[derive(Deserialize)]
struct Params {
    #[serde(default)]
    items: Vec<usize>,
}

// This will parse 0 occurrences of `items` as an empty `Vec`.
async fn process_items(Query(params): Query<Params>) {
    // ...
}

let app = Router::new().route("/process_items", get(process_items));

Tuple Fields

0: T

Implementations

impl<T> Query<T>

where T: DeserializeOwned,

pub fn try_from_uri(value: &Uri) -> Result<Self, QueryRejection>

Attempts to construct a Query from a reference to a Uri.

Example

use axum_extra::extract::Query;
use http::Uri;
use serde::Deserialize;

#[derive(Deserialize)]
struct ExampleParams {
    foo: String,
    bar: u32,
}

let uri: Uri = "http://example.com/path?foo=hello&bar=42".parse().unwrap();
let result: Query<ExampleParams> = Query::try_from_uri(&uri).unwrap();
assert_eq!(result.foo, String::from("hello"));
assert_eq!(result.bar, 42);

Trait Implementations

impl<T: Clone> Clone for Query<T>

fn clone(&self) -> Query<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Query<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default> Default for Query<T>

fn default() -> Query<T>

Returns the “default value” for a type.

impl<T> Deref for Query<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for Query<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T, S> FromRequestParts<S> for Query<T>

where T: DeserializeOwned, S: Send + Sync,

type Rejection = QueryRejection

If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response.

async fn from_request_parts( parts: &mut Parts, _state: &S, ) -> Result<Self, Self::Rejection>

Perform the extraction.

impl<T: Copy> Copy for Query<T>