Query API#

fastapi_restly.query implements list-endpoint filtering, sorting, and pagination: derive_schema_list_params() derives the list params, a model of the URL parameters, from the view’s response class and its model, and apply_list_params() applies validated list params to a SQLAlchemy select.

fastapi_restly.query.apply_list_params(query: Select, list_params: BaseModel | QueryParams, model: type[DeclarativeBase], schema_response: type[BaseModel], *, pagination: NumberedPagination | NoPagination | None = ...) → Select#

Apply pagination, sorting, and filtering to query using validated list params.

list_params is normally an instance of the model returned by derive_schema_list_params(). The default list endpoints always pass a validated instance, so pagination/filter bounds have already been checked. schema_response decides the fields a client can filter and sort on. A view passes its response class.

The arguments match the view method apply_list_params(), which calls this function with the view’s model, response class and pagination.

A raw QueryParams is also accepted for callers that build the query parameters programmatically. Raw inputs bypass schema validation — the caller is responsible for verifying page/page_size ranges and any per-view bounds (max_page_size); this function only performs the minimum coercion needed to apply the SQL clauses.

pagination names the page and page-size parameters to read. By default it is the pagination that derive_schema_list_params() created the list params model with, and page and page_size for raw QueryParams or a hand-written model. A NoPagination or None applies no LIMIT/OFFSET, and so does a missing page-size key.

Examples:

# Pagination
page=2&page_size=50

# Sorting
sort=name,-created_at

# Filtering
name=Bob&status=active&created_at__gte=2024-01-01

# Contains (string fields)
name__contains=John&email__icontains=example

fastapi_restly.query.derive_schema_list_params(schema_response: type[BaseModel], model: type[DeclarativeBase], *, pagination: NumberedPagination | NoPagination | None = NumberedPagination(default_page_size=50, max_page_size=1000, max_page=None, page_query_param='page', page_size_query_param='page_size', envelope=PaginatedEnvelope)) → type[BaseModel]#

Build the list params: a Pydantic model that describes and validates the URL query parameters of a list endpoint. A view keeps it in schema_list_params.

The generated model accepts pagination (page, page_size), sorting (sort), and one filter parameter per field of schema_response that maps to a filterable column on model – with optional __in/__ne/__gte/ __lte/__gt/__lt/__isnull/__contains/__icontains suffixes. Fields that do not resolve to a column (relationship/collection fields, or reference traversals the request path would reject) get no filter params, so the generated schema – and the OpenAPI it produces – no longer advertises filters for fields that are not filterable at all. WriteOnly fields get none either, since a filter on one would leak its value. Fields whose type is a collection (dict/list, e.g. JSON or ARRAY columns) generate only __isnull: a query-string value cannot coerce into them, so every other operator would fail at request time.

With a pagination (the default is page and page_size), its two query parameters are added under its names and validated by Pydantic with bounds: the page at least 1 and at most max_page when set, the page size from 1 to max_page_size. The resulting SQL offset must also fit in a signed 64-bit integer. Out-of-range values produce a standard 422 response from FastAPI. With a NoPagination or None, no pagination parameters are emitted at all – the endpoint returns every matching row – while sorting and filtering stay available.

Parameters:

schema_response – The response class whose fields decide the available filter parameters. A view passes its schema_response, so a client can filter only on what it can see.
model – The SQLAlchemy model the list endpoint queries. Used to verify each field resolves to a filterable column; non-column fields are omitted from the generated params.
pagination – The view’s pagination settings. A NoPagination or None is an unpaginated view, which returns the full result set.