Usage Guide

This guide covers the main features and usage patterns of QueryMate.

• Filtering
  • Basic Filtering
  • Available Operators
  • Examples
  • Relationship Filtering
• Sorting
  • Basic Sorting
  • Sorting Direction
  • Examples
  • Relationship Sorting
  • Default Behavior
• Pagination
  • Basic Pagination
  • Parameters
  • Examples
  • Combining with Other Parameters
  • Best Practices
• Field Selection
  • Basic Field Selection
  • Examples
  • Related Fields
  • Serialization Behavior
  • Default Behavior
  • Best Practices
• Relationships
  • Defining Relationships
  • Querying Related Fields
  • Filtering by Related Fields
  • Sorting by Related Fields
  • Nested Relationships
  • Best Practices
• Serialization
  • Overview
  • Features
  • Usage Examples
  • Query Parameters
  • Best Practices
• Predicates
  • Built-in Predicates
  • Usage Examples
  • Extending Predicates
  • Contributing Predicates
  • Best Practices

Basic Usage

The basic usage of QueryMate involves three main steps:

1. Define your SQLModel

2. Set up the FastAPI dependency

3. Use QueryMate in your route

Here’s a complete example:

from fastapi import FastAPI, Depends
from sqlmodel import Session, SQLModel, Field, Relationship
from querymate import QueryMate

class User(SQLModel, table=True):
    id: int = Field(primary_key=True)
    name: str
    email: str
    age: int
    posts: list["Post"] = Relationship(back_populates="author")

class Post(SQLModel, table=True):
    id: int = Field(primary_key=True)
    title: str
    content: str
    author_id: int = Field(foreign_key="user.id")
    author: User = Relationship(back_populates="posts")

app = FastAPI()

@app.get("/users")
async 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")
async 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 Parameters

QueryMate accepts query parameters in JSON format through the q parameter. The structure is:

{
    "filter": {
        "field": {"operator": "value"}
    },
    "sort": ["-field1", "field2"],
    "limit": 10,
    "offset": 0,
    "select": ["field1", "field2", {"relationship": ["field1", "field2"]}]
}

For example:

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

Serialization

QueryMate includes built-in serialization capabilities that transform query results into dictionaries containing only the requested fields. This helps reduce payload size and improve performance.

Features: - Direct field selection - Nested relationships - Both list and non-list relationships - Automatic handling of null values

Example: .. code-block:: python

# Returns serialized results with only the requested fields results = query.run(db, User) # [ # { # “id”: 1, # “name”: “John”, # “posts”: [ # {“id”: 1, “title”: “Post 1”}, # {“id”: 2, “title”: “Post 2”} # ] # } # ]

# Returns raw model instances raw_results = query.run_raw(db, User) # [User(id=1, name=”John”, posts=[Post(id=1, title=”Post 1”), Post(id=2, title=”Post 2”)])]

Default Parameters

• limit: 10 (max: 200)

• offset: 0

• fields: All fields if not specified

• sort: No sorting if not specified

• q: No filtering if not specified