Validate string query input
An endpoint accepts a search term or filter value that should not exceed a defined size.
FastAPI · Function
Query
Query declares a FastAPI query parameter and adds validation, documentation metadata, and OpenAPI schema information. Use it with Annotated to express constraints such as length limits or numeric bounds.
How it works
Query creates request metadata for a query parameter and lets FastAPI apply validation and OpenAPI metadata. Place it inside Annotated alongside the parameter's type; defaults such as None still control whether the parameter is optional.
Syntax
Query(
default=Undefined,
*,
default_factory=_Unset,
alias=None,
alias_priority=_Unset,
validation_alias=None,
serialization_alias=None,
title=None,
description=None,
gt=None,
ge=None,
lt=None,
le=None,
min_length=None,
max_length=None,
pattern=None,
regex=None,
discriminator=None,
strict=_Unset,
multiple_of=_Unset,
allow_inf_nan=_Unset,
max_digits=None,
decimal_places=None,
examples=None,
example=_Unset,
openapi_examples=None,
deprecated=None,
include_in_schema=True,
json_schema_extra=None,
**extra
)Parameters
| Name | Type | Description |
|---|---|---|
default | Any | Default value for the query parameter; Undefined makes the parameter required unless another default is supplied. |
alias | str | None | Alternative query name exposed to clients. |
title | str | None | Human-readable parameter title. |
description | str | None | Human-readable parameter description. |
gt | float | None | Numeric lower bound; the value must be greater than this. |
ge | float | None | Numeric lower bound; the value must be greater than or equal to this. |
lt | float | None | Numeric upper bound; the value must be less than this. |
le | float | None | Numeric upper bound; the value must be less than or equal to this. |
min_length | int | None | Minimum string length. |
max_length | int | None | Maximum string length. |
pattern | str | None | Regular-expression pattern for validation. |
include_in_schema | bool | Whether to include the parameter in the generated schema. |
Returns
A parameter metadata object used by FastAPI to extract, validate, and document a query parameter.
Key points
- Use
Queryto attach validation rules and descriptive metadata to query parameters. - The modern form places
Query(...)insidetyping.Annotatedwith the parameter's type. - A
max_lengthconstraint checks the number of characters in an incoming string. - Invalid query values are rejected with a client-facing validation error.
- Import
Querydirectly from thefastapipackage.
Common mistakes
- Putting validation in
Querydoes not make an optional parameter required; its Python default still determines that. - Use
Queryin a path-operation or dependency parameter, typically throughAnnotated, rather than as an unrelated standalone value.
Example: Limit a query string length
from typing import Annotated
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[str | None, Query(max_length=50)] = None,
):
return {"q": q}The optional q query parameter is accepted when present and validated to a maximum of 50 characters.
When to use it
Constrain numeric query values
An endpoint requires pagination, price, or rating values within numeric limits.
Document query parameters
An API needs parameter descriptions, titles, aliases, or examples in its generated schema.
Interview questions
QWhat does FastAPI's Query function provide?
Query declares that a parameter comes from the URL query string and supplies validation or documentation metadata. For example, Query(max_length=50) limits an incoming string and contributes that constraint to the generated API description.
Follow-up: How would you keep the parameter optional while adding validation? Use a nullable type and assign None as the default, such as Annotated[str | None, Query(max_length=50)] = None.
QWhat kinds of options can be passed to Query?
The function accepts constraints such as gt, ge, lt, le, min_length, max_length, and pattern. It also accepts descriptive metadata including title, description, and examples.
Follow-up: Which constraints are appropriate for a numeric query value? Use numeric checks such as gt, ge, lt, le, or multiple_of; string-length and pattern checks target string values.
QWhat happens when a query value fails a Query constraint?
FastAPI validates the received value against the declared type and Query constraints. If the value violates a constraint, FastAPI returns a clear validation error to the client and documents the parameter constraint.
Follow-up: What happens when a supplied string exceeds max_length? The request fails validation rather than reaching the endpoint body, and the client receives a validation error.
Related
PathBodyHeaderCookieFormFileAnnotatedDepends