API Reference

• QueryMate Class
  • Basic Usage
  • Class Methods
  • Instance Methods
  • Advanced Examples

QueryMate Class

The QueryMate class provides a powerful 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 containing only the requested fields.

For detailed documentation and examples, see QueryMate Class.

QueryBuilder Class

class querymate.core.query_builder.QueryBuilder(model)

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)

Initialize the QueryBuilder.

Parameters:

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

Return type:

None

apply_filter(filter_dict=None)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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]

Predicates

Available Predicates

The following predicates are available for filtering:

• eq - Equal to

• ne - Not equal to

• gt - Greater than

• lt - Less than

• gte - Greater than or equal to

• lte - Less than or equal to

• cont - Contains

• starts_with - Starts with

• ends_with - Ends with

• in - In list

• nin - Not in list

• is_null - Is null

• is_not_null - Is not null

• matches - Matches pattern

• matches_any - Matches any of the patterns

• present - Value is not null and not empty

• true - Value is true

• false - Value is false