Support multiple Query() in a single endpoint

[bonastreyair]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()

# new expected way of using of Query() with pydantic models since 0.115.0
class PaginationNew(BaseModel):
    limit: int = Field(100, gt=0, lt=1000, description="Limit the number of items.")
    offset: int = Field(0, ge=0, description="Start showing items from this index.")

class OrderingNew(BaseModel):
    order_by: str | None = Field(None, description="Order the results by this field.")
    descending: bool = Field(False, description="If true, return the results in descending order, ascending otherwise.")


@app.get(path="/new_logs")
def paginate_new_logs(
    pagination: Annotated[PaginationNew, Query()],
    ordering: Annotated[OrderingNew, Query()],
) -> dict:
    return {"pagination": []}


# previous way of using Query() with pydantic models before 0.115.0
class PaginationOld(BaseModel):
    limit: int = Field(Query(100, gt=0, lt=1000, description="Limit the number of items."))
    offset: int = Field(Query(0, ge=0, description="Start showing items from this index."))

class OrderingOld(BaseModel):
    order_by: str | None = Field(Query(None, description="Order the results by this field."))
    descending: bool = Field(Query(False, description="If true, return the results in descending order, ascending otherwise."))


@app.get(path="/old_logs")
def paginate_old_logs(
    pagination: Annotated[PaginationOld, Depends()],
    ordering: Annotated[OrderingOld, Depends()],
) -> dict:
    return {"pagination": []}

Description

When I define multiple Query() in a single endpoint using the new way of using pydantic models, the generated final query parameters from the endpoint do not work as I expected or it is not yet fully supported.

Using Query() in the two parameters this is what I get (new expected way of doing since 0.115.0):

• When using Field() in each attribute in the pydantic model
  • ❌ fields appear to be nested (how is this expected to be sent via http?)
  • ❌ fields appear to be mandatory
  • ✅ fields maintain the limits and defaults and the descriptions

• When also using Field(Query()) in each attribute in the pydantic model
  • ❌ fields appear to be nested (how is this expected to be sent via http?)
  • ❌ fields appear to be mandatory (they should not)
  • ❌ fields do not maintain the limits and defaults and description

Using Depends() for both query parameters, as I was using it, before the recommended way since the 0.115.0 update:

• When using Field() in each attribute in the pydantic model
  • ✅ fields are not nested
  • ✅ fields are optional
  • ❌ fields do not maintain the descriptions

• When also using Field(Query()) in each attribute in the pydantic model
  • ✅ fields are not nested
  • ✅ fields are optional
  • ✅ fields maintain the limits and defaults and descriptions

Note that obviously I have been using the last proposal since it did what I needed, but today I tried the "new way of doing it" and it did not behave as expected so I still need to use the query parameters with Depends() and having Field(Query()) for each pydantic model field

The question basically is:

• How it is expected to define multiple Query() parameters if it is not using Depends() with pydantic models defined as Field(Query())?

Operating System

Linux

Operating System Details

Ubuntu 22.04

FastAPI Version

0.115.0

Pydantic Version

2.9.2

Python Version

Python 3.11.8

[minhduc0711]

Seems like you can only use Query() only once in the signature of the path operation function if you are using Pydantic models for query parameters. A workaround would be to create a child model:

from typing import Annotated

from fastapi import Depends, FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


# new expected way of using of Query() with pydantic models since 0.115.0
class PaginationNew(BaseModel):
    limit: int = Field(100, gt=0, lt=1000, description="Limit the number of items.")
    offset: int = Field(0, ge=0, description="Start showing items from this index.")


class OrderingNew(BaseModel):
    order_by: str | None = Field(None, description="Order the results by this field.")
    descending: bool = Field(
        False,
        description="If true, return the results in descending order, ascending otherwise.",
    )


class AllParams(PaginationNew, OrderingNew):
    pass


@app.get(path="/new_logs")
def paginate_new_logs(
    query_params: Annotated[AllParams, Query()],
) -> dict:
    return {"pagination": []}

And the docs now look correct:

[bonastreyair]

Thanks for the example!

Indeed I knew that could work, but this feels like I am obfuscating a bit my code. It feels like creating a class "just for that" doesn't feel like FastAPI clean standards.

In addition to that, for my specific use case, it is not enough because in the endpoint I am using the pydantic model ordering, and pagination for different things inside different functions, and I still want to use that concept separation (as I can currently do with Depends() and Field(Query()))

I will keep the discussion open since I still think the support for multiple "Query()" definition in a single endpoint should be supported cleanly without having to create an intermediate class that inherits from every other needed class.

[c0dearm]

The default behavior when having more than one Query model in the function signature is a bit odd, looks like a bug that should be fixed. I would expect to have all the query params flattened like in the previous screenshot without having to use the workaround.

[minhduc0711]

You're probably right that this is a bug. It looks even worse with Swagger UI

[ollz272]

In addition, it seems like once you use a pydantic model you can't combine it with other query params

from typing import Annotated, Literal

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field

app = FastAPI()


class FilterParams(BaseModel):
    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()], x: str):
    return filter_query

When making the request we get this error:

{
  "detail": [
    {
      "loc": [
        "query",
        "filter_query"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

[flxdot]

It seems like this should be an issue.

[flxdot]

Seems like there is an issue now and this discussion was referenced: #12402

[jd-solanki]

/cc @tiangolo

[ollz272]

This really needs looking at, the feature is pretty much unusable in its current state for us. Can someone with privileges make this an issue so it can be looked into, please?

[daniel-k]

Same here. I was actually pretty excited when I read about it in the release notes so that we can finally generalize our pagination query parameters across all our endpoints. But it's of no use if you cannot have any other parameters.

[callamd]

Use object inheritence to drop these params into your others? Will probably work?

[leverage-analytics]

I also like the idea of supporting multiple Query().

On a (potentially) related note, I'm having trouble getting the list to work in the documentation example for this new feature. In the example, tags is a list of strings, so I expected (and hoped for) the same usage as described here where the parameter can be passed multiple times in order to build the list (e.g. http://localhost:8000/items/?tags=foo&tags=bar would result in tags=['foo', 'bar']).

Is that not the case?

[uriyyo]

This issue should be resolved in scope of #12944 PR

[uriyyo]

For those still waiting for the official FastAPI fix - you can use fastapi-backports until the official release.

pip install fastapi-backports

Brings multiple Query models and PEP 695 type alias support to FastAPI until it is officially supported:

https://github.com/uriyyo/fastapi-backports

Usage example:

import fastapi_backports.apply  # noqa: F401

from typing import Annotated, Any

from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI()


class UserFilters(BaseModel):
    min_age: int | None = None
    max_age: int | None = None


class GroupFilters(BaseModel):
    min_size: int | None = None
    max_size: int | None = None


type UserFiltersDependency = Annotated[
    UserFilters,
    Query(),
]

type GroupFiltersDependency = Annotated[
    GroupFilters,
    Query(),
]


@app.get("/filters")
async def get_filters(
    user_filters: UserFiltersDependency,
    group_filters: GroupFiltersDependency,
) -> dict[str, Any]:
    return {
        "user_filters": user_filters,
        "group_filters": group_filters,
    }

GET /filters?min_age=10&max_size=20

{
  "user_filters": {
    "min_age": 10,
    "max_age": null
  },
  "group_filters": {
    "min_size": null,
    "max_size": 20
  }
}