Home >Backend Development >Python Tutorial >FastAPI: How to use Pydantic to declare Query Parameters
It came out about three weeks ago one of the most expected features of FastAPI. At least when we're talking about Pydantic Models FastAPI.
Yes, I'm talking about the ability to use Pydantic Models to map your query parameters.
So in this post, I'll try to show you all you ? can and ? can't do about this subject ?:
The first thing you need to do to start mapping your query parameters with Pydantic is making sure you are using FastAPI version 0.115.0.
After this, you can always go to FastAPI docs to check what is already available. Sebastián and the team members make a really, really good work on keeping do docs updated and informative ✨.
Let's start with some examples on how we used to map Query Parameters in FastAPI. ?
The simplest way to do it would be:
from fastapi import FastAPI app = FastAPI() @app.get("/") async def search( limit: int | None = 10, skip: int | None = 1, filter: str | None = None ): return { "limit": limit, "skip": skip, "filter": filter }
And now you can simply call:
GET http://localhost:8000/?limit=42&skip=12&filter=banana
But if we identified that this Query Parameters would be used in other routes, we would isolate it with something like:
from typing import Any from fastapi import Depends, FastAPI, Query app = FastAPI() async def pagination_query_string( limit: int | None = Query(10, ge=5, le=100), skip: int | None = Query(1, ge=1), filter: str | None = Query(None) ) -> dict[str, Any]: return { "limit": limit, "skip": skip, "filter": filter } @app.get("/") async def search(q: dict[str, Any] = Depends(pagination_query_string)): return q
Or since we're using Pydantic to map our models, with just a little refactoring we would get:
from fastapi import Depends, FastAPI, Query from pydantic import BaseModel app = FastAPI() class PaginationQueryString(BaseModel): limit: int | None = 10 skip: int | None = 1 filter: str | None = None async def pagination_query_string( limit: int | None = Query(10, ge=5, le=100), skip: int | None = Query(1, ge=1), filter: str | None = Query(None) ) -> PaginationQueryString: return PaginationQueryString( limit=limit, skip=skip, filter=filter ) @app.get("/") async def search(q: PaginationQueryString = Depends(pagination_query_string)): return q
Now, if we want to get our query string, we don't need to create a function and then add it as a dependency. We can simply tell FastAPI that we want an object of type PaginationQueryString and that it's a query string:
from typing import Annotated from fastapi import FastAPI, Query from pydantic import BaseModel app = FastAPI() class PaginationQueryString(BaseModel): limit: int | None = 10 skip: int | None = 1 filter: str | None = None @app.get("/") async def search(q: Annotated[PaginationQueryString, Query()]): return q
Easy, right? ?
At least at version 0.115.0, it don't work very well with nested models.
Let's try something like:
from typing import Annotated from fastapi import FastAPI, Query from pydantic import BaseModel app = FastAPI() class Filter(BaseModel): name: str | None = None age: int | None = None nickname: str | None = None class PaginationQueryString(BaseModel): limit: int | None = 10 skip: int | None = 1 filter: Filter | None = None @app.get("/") async def search(q: Annotated[PaginationQueryString, Query()]): return q
If we call it like before:
GET http://localhost:8000/?limit=42&skip=12&filter=chocolate
We'll get an error telling us that filter is an object:
{ "detail": [ { "type": "model_attributes_type", "loc": [ "query", "filter" ], "msg": "Input should be a valid dictionary or object to extract fields from", "input": "chocolate" } ] }
At least right now, it's absolutely right! We changed our filter to be a Pydantic model, not a string. But if we try to convert it to a dictionary:
http://localhost:8000/?limit=42&skip=12&filter={%22name%22:%20%22Rafael%22,%20%22age%22:%2038,%20%22nickname%22:%20%22ceb10n%22}
FastAPI will tell us that filter needs to be a valid dictionary ?:
{ "detail": [ { "type": "model_attributes_type", "loc": [ "query", "filter" ], "msg": "Input should be a valid dictionary or object to extract fields from", "input": "{\"name\": \"Rafael\", \"age\": 38, \"nickname\": \"ceb10n\"}" } ] }
It's happening this because FastAPI will rely on Starlette's QueryParams, that will give a string to FastAPI, not a dict. And at least in version 0.115.0, this will give you an error.
It's quite simple:
✅ You have simple query strings that don't need any elaborate fancy nested objects? Use it! ?
❌ You created a complex nested query string? Don't use it yet ?. (And maybe you should try to rethink your query strings. ? The simpler, the better ?)
The above is the detailed content of FastAPI: How to use Pydantic to declare Query Parameters. For more information, please follow other related articles on the PHP Chinese website!