Query API

fastapi_restly.query.apply_list_params(params: BaseModel | QueryParams, select_query: Select, model: type[DeclarativeBase], schema_cls: type[BaseModel]) → Select

Apply pagination, sorting, and filtering on a SQL query using validated list-endpoint query parameters.

params is normally an instance of the schema returned by create_list_params_schema(). The generated FastAPI endpoints always pass a validated instance, so pagination/filter bounds have already been checked.

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.

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.create_list_params_schema(schema_cls: type[BaseModel], *, default_page_size: int | None = None, max_page_size: int = 1000) → type[BaseModel]

Create a Pydantic model that describes and validates URL query parameters for list endpoints.

The generated model accepts pagination (page, page_size), sorting (sort), and one filter parameter per response-schema field with optional __in/__ne/__gte/__lte/__gt/__lt/__isnull/ __contains/__icontains suffixes.

page and page_size are validated by Pydantic with bounds (page >= 1, 1 <= page_size <= max_page_size); out-of-range values produce a standard 422 response from FastAPI.

Args:

schema_cls: The response schema whose fields drive the available

filter parameters.

default_page_size: Default value for the page_size parameter.

None (the default) means “no implicit page size” — omitting page_size returns every matching row and page is ignored.

max_page_size: Upper bound (inclusive) for the page_size

parameter. Defaults to MAX_PAGE_SIZE.