How to Use Query Class in FastAPI for Query Parameters

In FastAPI, use the Query class to declare query parameters with extra validation, default values, and metadata. Import Query from fastapi and use it as a default value in your endpoint function parameters to customize query behavior.

Syntax

The Query class is used to declare query parameters with additional options like default values, descriptions, and validation constraints.

Basic syntax:

from fastapi import Query

def endpoint(param: str = Query(..., *, title=None, description=None, min_length=None, max_length=None, regex=None)):

Explanation:

• param: The query parameter name.
• default: Default value or ... to make it required.
• title, description: Metadata for docs.
• min_length, max_length: String length limits.
• regex: Pattern the value must match.

python

from fastapi import Query

def read_items(q: str = Query(..., min_length=3, max_length=50, description="Query string for searching items")):
    return {"query": q}

Example

This example shows a FastAPI app with a GET endpoint that uses Query to require a query parameter q with a minimum length of 3 characters and a description. The endpoint returns the query value.

python

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(q: str = Query(..., min_length=3, description="Search query string")):
    return {"query": q}

Output

When you visit /items/?q=foo, the response is {"query": "foo"}. If q is missing or shorter than 3 chars, FastAPI returns a validation error.

Common Pitfalls

• Forgetting to import Query from fastapi.
• Not using Query(...) to make a parameter required; using Query(None) makes it optional.
• Setting conflicting validation constraints (e.g., min_length greater than max_length).
• Using Query with non-query parameters like path parameters.

Wrong example (parameter is optional but intended required):

def read_items(q: str = Query(None)):

Right example (required parameter):

def read_items(q: str = Query(...)):

python

from fastapi import FastAPI, Query

app = FastAPI()

# Wrong: q is optional but should be required
@app.get("/wrong/")
async def wrong_read(q: str = Query(None)):
    return {"query": q}

# Right: q is required
@app.get("/right/")
async def right_read(q: str = Query(...)):
    return {"query": q}

Quick Reference

Parameter	Description	Example
default	Default value or ... to require parameter	Query(...)
title	Title for API docs	Query(..., title="Search Query")
description	Description for API docs	Query(..., description="Search term")
min_length	Minimum string length	Query(..., min_length=3)
max_length	Maximum string length	Query(..., max_length=50)
regex	Regex pattern to validate	Query(..., regex="^fixed.*")

Key Takeaways

Use Query(...) to declare required query parameters with validation in FastAPI.

Add metadata like description and title to improve API documentation automatically.

Set constraints like min_length, max_length, and regex to validate query inputs.

Remember to import Query from fastapi and use it only for query parameters.

Avoid common mistakes like making required parameters optional by using Query(None).