API Reference

Core

class querymate.core.querymate.Querymate(**data)[source]

Bases: BaseModel

A powerful query builder for FastAPI and SQLModel.

This class provides a flexible interface for building and executing database queries with support for filtering, sorting, pagination, and field selection. It includes built-in serialization capabilities to transform query results into dictionaries with only the requested fields.

Parameters:

  • select (list[str | dict[str, list[str]]] | None)

  • filter (dict[str, Any] | None)

  • sort (list[str] | None)

  • limit (int | None)

  • offset (int | None)

select

Fields to include in the response. Default is all fields.

Type:

list[FieldSelection] | None

filter

Filter conditions for the query. Default is {}.

Type:

FilterCondition | None

sort

List of fields to sort by. Prefix with “-” for descending order. Default is [].

Type:

list[str] | None

limit

Maximum number of records to return. Default is 10, max is 200.

Type:

int | None

offset

Number of records to skip. Default is 0.

Type:

int | None

Serialization:

The Querymate class includes built-in serialization capabilities through the run and run_async methods. These methods automatically serialize the results into dictionaries containing only the requested fields. For raw model instances, use run_raw or run_raw_async instead.

Example

```python @app.get(“/users”) def get_users(

query: QueryMate = Depends(QueryMate.fastapi_dependency), db: Session = Depends(get_db)

):

# Returns serialized results (dictionaries) return query.run(db, User)

@app.get(“/users/raw”) def get_users_raw(

query: QueryMate = Depends(QueryMate.fastapi_dependency), db: Session = Depends(get_db)

):

# Returns raw model instances return query.run_raw(db, User)

```

Query example: ` /users?q={"filter":{"age":{"gt":18}},"sort":["-name"],"limit":10,"offset":0,"select":["id","name"]} `

classmethod fastapi_dependency(request)[source]

FastAPI dependency for creating a QueryMate instance from a request.

Parameters:

request (Request) – The FastAPI request object.

Returns:

A new QueryMate instance.

Return type:

Querymate

filter: dict[str, Any] | None
classmethod from_qs(query_params)[source]

Convert native FastAPI QueryParams to a QueryMate instance.

Parameters:

query_params (QueryParams) – The FastAPI query parameters.

Returns:

A new QueryMate instance.

Return type:

Querymate

Raises:

ValueError – If the query parameter contains invalid JSON.

limit: int | None
model_config: ClassVar[ConfigDict] = {'extra': 'ignore'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

offset: int | None
run(db, model)[source]

Build and execute the query based on the parameters.

This method combines filtering, sorting, pagination, and field selection to build and execute a database query. The results are automatically serialized into dictionaries containing only the requested fields.

Parameters:

  • db (Session) – The SQLModel database session.

  • model (type[SQLModel]) – The SQLModel model class to query.

Returns:

A list of serialized model instances matching the query parameters.

Return type:

list[dict[str, Any]]

Example

`python querymate = Querymate(select=["id", "name"]) # Returns serialized results results = querymate.run(db, User) `

async run_async(db, model)[source]

Build and execute the query asynchronously based on the parameters.

This method combines filtering, sorting, pagination, and field selection to build and execute a database query asynchronously. The results are automatically serialized into dictionaries containing only the requested fields.

Parameters:

  • db (AsyncSession) – The SQLModel async database session.

  • model (type[SQLModel]) – The SQLModel model class to query.

Returns:

A list of serialized model instances matching the query parameters.

Return type:

list[dict[str, Any]]

Example

`python querymate = Querymate(select=["id", "name"]) # Returns serialized results results = await querymate.run_async(db, User) `

run_raw(db, model)[source]

Build and execute the query based on the parameters.

This method combines filtering, sorting, pagination, and field selection to build and execute a database query.

Parameters:

  • db (Session) – The SQLModel database session.

  • model (type[SQLModel]) – The SQLModel model class to query.

Returns:

A list of model instances matching the query parameters.

Return type:

list[SQLModel]

async run_raw_async(db, model)[source]

Build and execute the query asynchronously based on the parameters.

This method combines filtering, sorting, pagination, and field selection to build and execute a database query asynchronously.

Parameters:

  • db (AsyncSession) – The SQLModel async database session.

  • model (type[SQLModel]) – The SQLModel model class to query.

Returns:

A list of model instances matching the query parameters.

Return type:

list[SQLModel]

select: list[str | dict[str, list[str]]] | None
sort: list[str] | None
to_qs()[source]

Convert the QueryMate instance to a query string.

Returns:

The URL-encoded query string.

Return type:

str

class querymate.core.filter.BlankPredicate[source]

Bases: Predicate

Checks if the value is null or empty.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'blank'
class querymate.core.filter.ContainsPredicate[source]

Bases: Predicate

Contains predicate for string fields.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'cont'
class querymate.core.filter.DefaultFieldResolver[source]

Bases: object

Resolves field paths to SQLAlchemy column objects.

This class handles the resolution of field paths (including nested relationships) to their corresponding SQLAlchemy column objects.

Example

`python resolver = DefaultFieldResolver() column = resolver.resolve(User, "posts.title")  # Resolves to Post.title `

resolve(model, field_path)[source]

Resolve a field path to a SQLAlchemy column.

Parameters:

  • model (type[SQLModel]) – The SQLModel class to start resolution from.

  • field_path (str) – The dot-separated path to the field.

Returns:

The resolved SQLAlchemy column.

Return type:

InstrumentedAttribute

Raises:

AttributeError – If the field path cannot be resolved.

class querymate.core.filter.DoesNotMatchAllPredicate[source]

Bases: Predicate

Does not match all of the given values using NOT LIKE operator.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'does_not_match_all'
class querymate.core.filter.DoesNotMatchAnyPredicate[source]

Bases: Predicate

Does not match any of the given values using NOT LIKE operator.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'does_not_match_any'
class querymate.core.filter.DoesNotMatchPredicate[source]

Bases: Predicate

Does not match predicate using NOT LIKE operator.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'does_not_match'
class querymate.core.filter.EndAllPredicate[source]

Bases: Predicate

Ends with all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'end_all'
class querymate.core.filter.EndAnyPredicate[source]

Bases: Predicate

Ends with any of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'end_any'
class querymate.core.filter.EndPredicate[source]

Bases: Predicate

Ends with the given value.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'end'
class querymate.core.filter.EndsWithPredicate[source]

Bases: Predicate

Ends with predicate for string fields.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'ends_with'
class querymate.core.filter.EqualPredicate[source]

Bases: Predicate

Equal to predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'eq'
class querymate.core.filter.FalsePredicate[source]

Bases: Predicate

Checks if the value is false.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'false'
class querymate.core.filter.FilterBuilder(model, resolver=None)[source]

Bases: object

Builds SQLAlchemy filter expressions from filter dictionaries.

This class converts filter dictionaries into SQLAlchemy filter expressions, supporting complex queries with AND/OR operators and nested conditions.

Example

```python builder = FilterBuilder(User) filters = builder.build({

“and”: [

{“age”: {“gt”: 18}}, {“name”: {“cont”: “John”}}

]

})

__init__(model, resolver=None)[source]

Initialize the filter builder.

Parameters:

  • model (type[SQLModel]) – The SQLModel class to build filters for.

  • resolver (DefaultFieldResolver | None) – Optional field resolver. Defaults to DefaultFieldResolver.

Return type:

None

build(filters_dict)[source]

Build SQLAlchemy filter expressions from a filter dictionary.

Parameters:

filters_dict (dict) – The filter dictionary to convert.

Returns:

List of SQLAlchemy filter expressions.

Return type:

list[Any]

Raises:

ValueError – If an unsupported operator is used.

Parameters:
class querymate.core.filter.GreaterThanOrEqualPredicate[source]

Bases: Predicate

Greater than or equal to predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'gte'
class querymate.core.filter.GreaterThanPredicate[source]

Bases: Predicate

Greater than predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'gt'
class querymate.core.filter.GtAllPredicate[source]

Bases: Predicate

Greater than all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'gt_all'
class querymate.core.filter.GtAnyPredicate[source]

Bases: Predicate

Greater than any of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'gt_any'
class querymate.core.filter.GteqAllPredicate[source]

Bases: Predicate

Greater than or equal to all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'gteq_all'
class querymate.core.filter.GteqAnyPredicate[source]

Bases: Predicate

Greater than or equal to any of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'gteq_any'
class querymate.core.filter.IContAllPredicate[source]

Bases: Predicate

Case-insensitive contains all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'i_cont_all'
class querymate.core.filter.IContAnyPredicate[source]

Bases: Predicate

Case-insensitive contains any of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'i_cont_any'
class querymate.core.filter.IContPredicate[source]

Bases: Predicate

Case-insensitive contains predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'i_cont'
class querymate.core.filter.InPredicate[source]

Bases: Predicate

In list predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'in'
class querymate.core.filter.IsNotNullPredicate[source]

Bases: Predicate

Is not null predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'is_not_null'
class querymate.core.filter.IsNullPredicate[source]

Bases: Predicate

Is null predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'is_null'
class querymate.core.filter.LessThanOrEqualPredicate[source]

Bases: Predicate

Less than or equal to predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'lte'
class querymate.core.filter.LessThanPredicate[source]

Bases: Predicate

Less than predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'lt'
class querymate.core.filter.LtAllPredicate[source]

Bases: Predicate

Less than all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'lt_all'
class querymate.core.filter.LtAnyPredicate[source]

Bases: Predicate

Less than any of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'lt_any'
class querymate.core.filter.LteqAllPredicate[source]

Bases: Predicate

Less than or equal to all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'lteq_all'
class querymate.core.filter.LteqAnyPredicate[source]

Bases: Predicate

Less than or equal to any of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'lteq_any'
class querymate.core.filter.MatchesAllPredicate[source]

Bases: Predicate

Matches all of the given values using LIKE operator.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'matches_all'
class querymate.core.filter.MatchesAnyPredicate[source]

Bases: Predicate

Matches any of the given values using LIKE operator.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'matches_any'
class querymate.core.filter.MatchesPredicate[source]

Bases: Predicate

Matches predicate using LIKE operator.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'matches'
class querymate.core.filter.NotEndAllPredicate[source]

Bases: Predicate

Does not end with all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'not_end_all'
class querymate.core.filter.NotEndAnyPredicate[source]

Bases: Predicate

Does not end with any of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'not_end_any'
class querymate.core.filter.NotEndPredicate[source]

Bases: Predicate

Does not end with the given value.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'not_end'
class querymate.core.filter.NotEqAllPredicate[source]

Bases: Predicate

Not equal to all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'not_eq_all'
class querymate.core.filter.NotEqualPredicate[source]

Bases: Predicate

Not equal to predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'ne'
class querymate.core.filter.NotIContAllPredicate[source]

Bases: Predicate

Case-insensitive does not contain all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'not_i_cont_all'
class querymate.core.filter.NotIContAnyPredicate[source]

Bases: Predicate

Case-insensitive does not contain any of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'not_i_cont_any'
class querymate.core.filter.NotIContPredicate[source]

Bases: Predicate

Case-insensitive does not contain predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'not_i_cont'
class querymate.core.filter.NotInPredicate[source]

Bases: Predicate

Not in list predicate.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'nin'
class querymate.core.filter.NotStartAllPredicate[source]

Bases: Predicate

Does not start with all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'not_start_all'
class querymate.core.filter.NotStartAnyPredicate[source]

Bases: Predicate

Does not start with any of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'not_start_any'
class querymate.core.filter.NotStartPredicate[source]

Bases: Predicate

Does not start with the given value.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'not_start'
class querymate.core.filter.Predicate[source]

Bases: ABC

Base class for filter predicates.

This abstract base class defines the interface for filter predicates and maintains a registry of all available predicate types.

name

The name of the predicate operator.

Type:

ClassVar[str]

registry

Registry of all available predicates.

Type:

ClassVar[dict[str, type[“Predicate”]]]

classmethod __init_subclass__()[source]

Register new predicate classes automatically.

Return type:

None

abstractmethod apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str]
registry: ClassVar[dict[str, type[Predicate]]] = {'blank': <class 'querymate.core.filter.BlankPredicate'>, 'cont': <class 'querymate.core.filter.ContainsPredicate'>, 'does_not_match': <class 'querymate.core.filter.DoesNotMatchPredicate'>, 'does_not_match_all': <class 'querymate.core.filter.DoesNotMatchAllPredicate'>, 'does_not_match_any': <class 'querymate.core.filter.DoesNotMatchAnyPredicate'>, 'end': <class 'querymate.core.filter.EndPredicate'>, 'end_all': <class 'querymate.core.filter.EndAllPredicate'>, 'end_any': <class 'querymate.core.filter.EndAnyPredicate'>, 'ends_with': <class 'querymate.core.filter.EndsWithPredicate'>, 'eq': <class 'querymate.core.filter.EqualPredicate'>, 'false': <class 'querymate.core.filter.FalsePredicate'>, 'gt': <class 'querymate.core.filter.GreaterThanPredicate'>, 'gt_all': <class 'querymate.core.filter.GtAllPredicate'>, 'gt_any': <class 'querymate.core.filter.GtAnyPredicate'>, 'gte': <class 'querymate.core.filter.GreaterThanOrEqualPredicate'>, 'gteq_all': <class 'querymate.core.filter.GteqAllPredicate'>, 'gteq_any': <class 'querymate.core.filter.GteqAnyPredicate'>, 'i_cont': <class 'querymate.core.filter.IContPredicate'>, 'i_cont_all': <class 'querymate.core.filter.IContAllPredicate'>, 'i_cont_any': <class 'querymate.core.filter.IContAnyPredicate'>, 'in': <class 'querymate.core.filter.InPredicate'>, 'is_not_null': <class 'querymate.core.filter.IsNotNullPredicate'>, 'is_null': <class 'querymate.core.filter.IsNullPredicate'>, 'lt': <class 'querymate.core.filter.LessThanPredicate'>, 'lt_all': <class 'querymate.core.filter.LtAllPredicate'>, 'lt_any': <class 'querymate.core.filter.LtAnyPredicate'>, 'lte': <class 'querymate.core.filter.LessThanOrEqualPredicate'>, 'lteq_all': <class 'querymate.core.filter.LteqAllPredicate'>, 'lteq_any': <class 'querymate.core.filter.LteqAnyPredicate'>, 'matches': <class 'querymate.core.filter.MatchesPredicate'>, 'matches_all': <class 'querymate.core.filter.MatchesAllPredicate'>, 'matches_any': <class 'querymate.core.filter.MatchesAnyPredicate'>, 'ne': <class 'querymate.core.filter.NotEqualPredicate'>, 'nin': <class 'querymate.core.filter.NotInPredicate'>, 'not_end': <class 'querymate.core.filter.NotEndPredicate'>, 'not_end_all': <class 'querymate.core.filter.NotEndAllPredicate'>, 'not_end_any': <class 'querymate.core.filter.NotEndAnyPredicate'>, 'not_eq_all': <class 'querymate.core.filter.NotEqAllPredicate'>, 'not_i_cont': <class 'querymate.core.filter.NotIContPredicate'>, 'not_i_cont_all': <class 'querymate.core.filter.NotIContAllPredicate'>, 'not_i_cont_any': <class 'querymate.core.filter.NotIContAnyPredicate'>, 'not_start': <class 'querymate.core.filter.NotStartPredicate'>, 'not_start_all': <class 'querymate.core.filter.NotStartAllPredicate'>, 'not_start_any': <class 'querymate.core.filter.NotStartAnyPredicate'>, 'present': <class 'querymate.core.filter.PresentPredicate'>, 'start': <class 'querymate.core.filter.StartPredicate'>, 'start_all': <class 'querymate.core.filter.StartAllPredicate'>, 'start_any': <class 'querymate.core.filter.StartAnyPredicate'>, 'starts_with': <class 'querymate.core.filter.StartsWithPredicate'>, 'true': <class 'querymate.core.filter.TruePredicate'>}
class querymate.core.filter.PresentPredicate[source]

Bases: Predicate

Checks if the value is not null and not empty.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'present'
class querymate.core.filter.StartAllPredicate[source]

Bases: Predicate

Starts with all of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'start_all'
class querymate.core.filter.StartAnyPredicate[source]

Bases: Predicate

Starts with any of the given values.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'start_any'
class querymate.core.filter.StartPredicate[source]

Bases: Predicate

Starts with the given value.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'start'
class querymate.core.filter.StartsWithPredicate[source]

Bases: Predicate

Starts with predicate for string fields.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'starts_with'
class querymate.core.filter.TruePredicate[source]

Bases: Predicate

Checks if the value is true.

apply(column, value)[source]

Apply the predicate to a column with the given value.

Parameters:

  • column (InstrumentedAttribute) – The SQLAlchemy column to apply the predicate to.

  • value (Any) – The value to compare against.

Returns:

The SQLAlchemy expression representing the predicate.

Return type:

Any

name: ClassVar[str] = 'true'
class querymate.core.query_builder.QueryBuilder(model)[source]

Bases: object

A flexible query builder for SQLModel with support for complex queries.

This class provides methods for building SQL queries with support for field selection, filtering, sorting, and pagination. It handles relationships and nested queries. It also includes built-in serialization capabilities to transform query results into dictionaries with only the requested fields.

Parameters:

model (type[SQLModel])

model

The SQLModel model class to query.

Type:

type[T]

query

The current SQL query being built.

Type:

SelectOfScalar

select

Fields to include in the response.

Type:

list[FieldSelection]

filter

Filter conditions for the query.

Type:

dict[str, Any]

sort

List of fields to sort by.

Type:

list[str]

limit

Maximum number of records to return.

Type:

int | None

offset

Number of records to skip.

Type:

int | None

Serialization:

The QueryBuilder includes built-in serialization capabilities through the serialize method. This allows you to transform query results into dictionaries containing only the requested fields. Serialization supports: - Direct field selection - Nested relationships - Both list and non-list relationships - Automatic handling of null values

Example

```python # Basic usage query_builder = QueryBuilder(model=User) query_builder.apply_select([“id”, “name”]) results = query_builder.fetch(db, User) serialized = query_builder.serialize(results)

# With relationships query_builder = QueryBuilder(model=User) query_builder.apply_select([“id”, “name”, {“posts”: [“id”, “title”]}]) results = query_builder.fetch(db, User) serialized = query_builder.serialize(results) ```

__init__(model)[source]

Initialize the QueryBuilder.

Parameters:

model (type[T]) – The SQLModel model class to query.

Return type:

None

apply_filter(filter_dict=None)[source]

Apply filter conditions to the query.

Parameters:

filter_dict (dict[str, Any] | None) – Filter conditions to apply.

Returns:

The query builder instance for method chaining.

Return type:

QueryBuilder

Example

`python builder.filter({"age": {"gt": 18}, "name": {"cont": "John"}}) `

apply_limit(limit=None)[source]

Apply limit and offset to the query.

Parameters:

limit (int | None) – Maximum number of records to return.

Returns:

The query builder instance for method chaining.

Return type:

QueryBuilder

Example

`python builder.limit(10) `

apply_offset(offset=None)[source]

Apply offset to the query.

Parameters:

offset (int | None) – Number of records to skip.

Returns:

The query builder instance for method chaining.

Return type:

QueryBuilder

Example

`python builder.offset(10)  # Skip the first 10 records `

apply_select(fields=None)[source]

Select fields to be returned in the query.

This method supports both direct field selection and relationship field selection through nested dictionaries.

Parameters:

fields (list[str | dict[str, list[str]]] | None) – List of fields to select. Can include nested dictionaries for relationship fields. If None, all fields are selected.

Returns:

The query builder instance for method chaining.

Return type:

QueryBuilder

Example

`python builder.select(["name", "email", {"posts": ["title", "content"]}]) `

apply_sort(sort=None)[source]

Apply sorting to the query.

Parameters:

sort (list[str] | None) – List of fields to sort by.

Returns:

The query builder instance for method chaining.

Return type:

QueryBuilder

Example

`python builder.sort(["-name", "age", "posts.title"])  # Sort by name descending, then age ascending, then posts.title ascending `

build(select=None, filter=None, sort=None, limit=None, offset=None)[source]

Build a complete query with all parameters.

This method combines field selection, filtering, sorting, and pagination into a single method call.

Parameters:

  • fields (list[str | dict[str, list[str]]] | None) – Fields to select.

  • filter (dict[str, Any] | None) – Filter conditions.

  • sort (list[str] | None) – Sort parameters.

  • limit (int | None) – Maximum number of records.

  • offset (int | None) – Number of records to skip.

  • select (list[str | dict[str, list[str]]] | None)

Returns:

The query builder instance for method chaining.

Return type:

QueryBuilder

Example

```python builder.build(

fields=[“name”, {“posts”: [“title”]}], filter={“age”: {“gt”: 18}}, sort=[“-name”], limit=10, offset=0

)

exec(db)[source]

Execute the query and return raw results.

Parameters:

db (Session) – The SQLModel database session.

Returns:

Raw query results.

Return type:

list[tuple[Any, …]]

async exec_async(db)[source]

Execute the query asynchronously and return raw results.

Parameters:

db (AsyncSession) – The SQLModel async database session.

Returns:

Raw query results.

Return type:

list[tuple[Any, …]]

fetch(db, model)[source]

Execute the query and return the results.

This method executes the query and returns the raw model instances. For serialized results (dictionaries with only the requested fields), use the serialize method after fetching.

Parameters:

  • db (Session) – The SQLModel database session.

  • model (type[T]) – The SQLModel model class to query.

Returns:

A list of model instances matching the query parameters.

Return type:

list[T]

Example

`python query_builder = QueryBuilder(model=User) query_builder.apply_select(["id", "name"]) results = query_builder.fetch(db, User) # For serialized results: serialized = query_builder.serialize(results) `

async fetch_async(db, model)[source]

Execute the query asynchronously and return the results.

This method executes the query asynchronously and returns the raw model instances. For serialized results (dictionaries with only the requested fields), use the serialize method after fetching.

Parameters:

  • db (AsyncSession) – The SQLModel async database session.

  • model (type[T]) – The SQLModel model class to query.

Returns:

A list of model instances matching the query parameters.

Return type:

list[T]

Example

`python query_builder = QueryBuilder(model=User) query_builder.apply_select(["id", "name"]) results = await query_builder.fetch_async(db, User) # For serialized results: serialized = query_builder.serialize(results) `

filter: dict[str, Any]
limit: int | None = 10
model: type[SQLModel]
offset: int | None = 0
query: SelectOfScalar
reconstruct_object(model, fields, row, field_idx)[source]

Reconstruct a model instance from a query result row.

This method handles both direct fields and relationship fields.

Parameters:

  • model (type[T]) – The SQLModel model class.

  • fields (list[FieldSelection]) – Fields to include.

  • row (tuple[Any, ...]) – The query result row.

  • field_idx (list[int]) – Current field index for tracking position in row.

Returns:

The reconstructed model instance and updated field index.

Return type:

tuple[T, list[int]]

reconstruct_objects(results, model)[source]

Reconstruct model instances from query results.

Parameters:

  • results (list[tuple[Any, ...]]) – List of query result rows.

  • model (type[T]) – The SQLModel model class.

Returns:

List of reconstructed model instances.

Return type:

list[T]

select: list[str | dict[str, list[str]]]
serialize(objects)[source]

Serialize objects with only the requested fields.

Parameters:

  • objects (list[T] | T) – The object(s) to serialize.

  • fields (list[FieldSelection] | list[str] | None) – The fields to include in the serialization. If None, uses the fields from the current select parameter.

Returns:

The serialized object(s) with only the requested fields.

Return type:

list[dict[str, Any]] | dict[str, Any]

sort: list[str]