Query System Overview

ChameleonDB queries are built using a chainable API. Every query targets an entity defined in your schema and is validated against it before execution.

Key Features

Type-Safe

All queries are validated against your schema before execution

Chainable API

Build complex queries by chaining methods together

Field Projection

Select only the fields you need with Select()

Eager Loading

Avoid N+1 queries with Include() for relations

Basic Query Structure

All queries follow this pattern:

result, err := db.Query("EntityName").
    Filter("field", "operator", value).
    Include("relation").
    OrderBy("field", "direction").
    Limit(10).
    Execute(ctx)

Example Schema

All examples in this section use the following schema:

entity User {
    id: uuid primary,
    email: string unique,
    name: string,
    age: int nullable,
    created_at: timestamp default now(),
    orders: [Order] via user_id,
}

entity Order {
    id: uuid primary,
    total: decimal,
    status: string,
    created_at: timestamp default now(),
    user_id: uuid,
    user: User,
    items: [OrderItem] via order_id,
}

entity OrderItem {
    id: uuid primary,
    quantity: int,
    price: decimal,
    order_id: uuid,
    order: Order,
}

Fetch All Records

Retrieve all instances from an entity:

users, err := db.Users().Execute()

SELECT id, email, name, age, created_at
FROM users;

Field Projection

Select only the fields you need:

users := db.Query("User").
    Select("id", "name", "email").
    Execute(ctx)

SELECT id, name, email
FROM users;

Performance: Field projection reduces memory usage and network transfer by only loading the data you need.

Query Validation

All queries are validated before execution. ChameleonDB will catch these errors at compile time:

Error	Example
Unknown entity	`db.Products()` when `Product` is not in schema
Unknown field	`.Filter("phone", ...)` when `phone` is not a field
Invalid relation path	`.Include("orders.address")` when `address` doesn’t exist
Type mismatch	`.Filter("age", "eq", "not a number")`
Missing order with pagination	`.Limit(10)` without `.OrderBy()` warns

Debug Mode

See the generated SQL for any query:

users := db.Query("User").
    Select("id", "name").
    Filter("email", "like", "ana").
    Debug().
    Execute(ctx)

[SQL] Query User
SELECT id, name FROM users WHERE email LIKE '%ana%'

[TRACE] Query on User: 2.3ms, 3 rows

Debug mode is useful during development to understand how your queries translate to SQL.

What’s Next?

Filtering

Learn about filter operators (eq, gt, like, in, etc.)

Relations

Master eager loading with Include()

Advanced Queries

OrderBy, Limit, Offset, and complex queries

Get Started

Core Concepts

Schema Language

Query System

Mutations

Guides

Security

Query System Overview

Key Features

Type-Safe

Chainable API

Field Projection

Eager Loading

Basic Query Structure

Example Schema

Fetch All Records

Field Projection

Query Validation

Debug Mode

What’s Next?

Filtering

Relations

Advanced Queries

​Key Features

Type-Safe

Chainable API

Field Projection

Eager Loading

​Basic Query Structure

​Example Schema

​Fetch All Records

​Field Projection

​Query Validation

​Debug Mode

​What’s Next?

Filtering

Relations

Advanced Queries

Key Features

Basic Query Structure

Example Schema

Fetch All Records

Field Projection

Query Validation

Debug Mode

What’s Next?