Query API

class fastapi_restly.query.QueryModifierInterface(*args, **kwargs)

Bases: Protocol

Protocol for query modifier implementations.

apply_query_modifiers(query_params: QueryParams, select_query: Select, model: type[DeclarativeBase], schema_cls: type[BaseModel]) → Select

Apply query modifiers to a select query.

class fastapi_restly.query.QueryModifierVersion(*values)

Bases: Enum

Available query modifier versions.

V1 = 'v1'

V2 = 'v2'

fastapi_restly.query.apply_filtering(query_params: QueryParams, select_query: Select, model: type[DeclarativeBase], schema_cls: type[BaseModel]) → Select

Apply filtering through URL query parameters on a SQL query.

fastapi_restly.query.apply_filtering_v2(query_params: QueryParams, select_query: Select, model: type[DeclarativeBase], schema_cls: type[BaseModel]) → Select

Apply filtering using direct field names and __suffixes for range/null filtering.

fastapi_restly.query.apply_pagination(query_params: QueryParams, select_query: Select) → Select

fastapi_restly.query.apply_pagination_v2(query_params: QueryParams, select_query: Select) → Select

Apply pagination using page and page_size parameters.

fastapi_restly.query.apply_query_modifiers(query_params: QueryParams, select_query: Select, model: type[DeclarativeBase], schema_cls: type[BaseModel]) → Select

Apply query modifiers using the configured version.

This is a convenience function that delegates to the appropriate implementation based on the global configuration.

fastapi_restly.query.apply_query_modifiers_v1(query_params: QueryParams, select_query: Select, model: type[DeclarativeBase], schema_cls: type[BaseModel]) → Select

Apply pagination, sorting, and filtering through URL query parameters on a SQL query.

Roughly follows JSONAPI query parameter families: https://jsonapi.org/format/#query-parameters-families

Common examples:

# Pagination
limit=100&offset=200

# Sorting
sort=field1,-field2

# Equality filter
filter[foo_id]=1&filter[name]=Bob

# OR-values
filter[id]=1,2,3

# Range filters
filter[created_at]=>=2024-01-01&filter[created_at]=<2025-01-01

# NULL checks
filter[foo_id]=!null

# Case-insensitive contains
contains[name]=john&contains[email]=example

fastapi_restly.query.apply_query_modifiers_v2(query_params: QueryParams, select_query: Select, model: type[DeclarativeBase], schema_cls: type[BaseModel]) → Select

Apply pagination, sorting, and filtering through URL query parameters on a SQL query.

Uses a more standard interface:

# Pagination
page=2&page_size=50

# Sorting
order_by=name,-created_at

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

# Contains (string fields)
name__contains=john&email__contains=example

fastapi_restly.query.apply_sorting(query_params: QueryParams, select_query: Select, model: type[DeclarativeBase]) → Select

fastapi_restly.query.apply_sorting_v2(query_params: QueryParams, select_query: Select, model: type[DeclarativeBase], schema_cls: type[BaseModel] | None = None) → Select

Apply sorting using the order_by parameter (comma-separated, - for descending).

fastapi_restly.query.create_query_param_schema(schema_cls: type[BaseModel]) → type[BaseModel]

Create a query param schema using the configured version.

This is a convenience function that delegates to the appropriate implementation based on the global configuration.

fastapi_restly.query.create_query_param_schema_v1(schema_cls: type[BaseModel]) → type[BaseModel]

Create a pydantic model class that describes and validates all possible query parameters.

fastapi_restly.query.create_query_param_schema_v2(schema_cls: type[BaseModel]) → type[BaseModel]

Create a pydantic model class that describes and validates all possible query parameters for the v2 interface (direct field names, __gte, __lte, etc.).

fastapi_restly.query.get_query_modifier_interface() → QueryModifierInterface

Get the current query modifier interface based on the configured version.

Returns:

The query modifier interface to use

fastapi_restly.query.get_query_modifier_version() → QueryModifierVersion

Get the current global query modifier version.

Returns:

The current query modifier version

fastapi_restly.query.get_query_param_schema_creator() → Callable[[type[BaseModel]], type[BaseModel]]

Get the appropriate query param schema creator based on the configured version.

Returns:

A function that creates query param schemas

fastapi_restly.query.set_query_modifier_version(version: QueryModifierVersion) → None

Set the global query modifier version to use.

Args:

version: The query modifier version to use (V1 or V2)

fastapi_restly.query.use_query_modifier_version(version: QueryModifierVersion)