QueryMate Class¶

The QueryMate class provides a powerful interface for building and executing database queries with support for filtering, sorting, pagination, and field selection.

Basic Usage¶

from querymate import Querymate
from sqlmodel import Session, SQLModel

# Create a QueryMate instance
querymate = Querymate(
    select=["id", "name"],
    filter={"age": {"gt": 25}},
    sort=["-age"],
    limit=10,
    offset=0
)

# Execute the query
results = querymate.run(db, User)

Class Methods¶

from_qs¶

Convert native FastAPI QueryParams to a QueryMate instance.

from fastapi import Request
from querymate import Querymate

@app.get("/users")
def get_users(request: Request):
    querymate = Querymate.from_qs(request.query_params)
    return querymate.run(db, User)

# Example query:
# /users?q={"filter":{"age":{"gt":25}},"sort":["-name"],"limit":10}

from_query_param¶

Convert a query parameter string to a QueryMate instance.

query_param = '{"filter":{"age":{"gt":25}},"sort":["-name"]}'
querymate = Querymate.from_query_param(query_param)

fastapi_dependency¶

FastAPI dependency for creating a QueryMate instance from a request.

from fastapi import Depends
from querymate import Querymate

@app.get("/users")
def get_users(query: Querymate = Depends(Querymate.fastapi_dependency)):
    return query.run(db, User)

Instance Methods¶

to_qs¶

Convert the QueryMate instance to a query string.

querymate = Querymate(
    select=["id", "name"],
    filter={"age": {"gt": 25}}
)
query_string = querymate.to_qs()
# Returns: q={"select":["id","name"],"filter":{"age":{"gt":25}}}

to_query_param¶

Convert the QueryMate instance to a query parameter string.

querymate = Querymate(
    select=["id", "name"],
    filter={"age": {"gt": 25}}
)
query_param = querymate.to_query_param()
# Returns: {"select":["id","name"],"filter":{"age":{"gt":25}}}

run¶

Build and execute the query, returning serialized results.

# Basic usage
results = querymate.run(db, User)
# Returns: [{"id": 1, "name": "John"}, ...]

# With relationships
querymate = Querymate(
    select=["id", "name", {"posts": ["id", "title"]}]
)
results = querymate.run(db, User)
# Returns: [{"id": 1, "name": "John", "posts": [{"id": 1, "title": "Post 1"}]}, ...]

run_raw¶

Build and execute the query, returning raw model instances.

results = querymate.run_raw(db, User)
# Returns: [<User object>, ...]

run_async¶

Build and execute the query asynchronously, returning serialized results.

async def get_users():
    results = await querymate.run_async(db, User)
    # Returns: [{"id": 1, "name": "John"}, ...]

run_raw_async¶

Build and execute the query asynchronously, returning raw model instances.

async def get_users():
    results = await querymate.run_raw_async(db, User)
    # Returns: [<User object>, ...]

Advanced Examples¶

Nested Filters¶

# Filter by related field
querymate = Querymate(
    filter={"posts.title": {"cont": "Python"}, "age": {"gt": 18}}
)
results = querymate.run(db, User)

Complex Sorting¶

# Sort by multiple fields
querymate = Querymate(
    sort=["-age", "name"]
)
results = querymate.run(db, User)

Field Selection with Relationships¶

# Select specific fields from related models
querymate = Querymate(
    select=["id", "name", {"posts": ["id", "title"]}]
)
results = querymate.run(db, User)

Pagination¶

# Get second page of results
querymate = Querymate(
    limit=10,
    offset=10
)
results = querymate.run(db, User)