Skip to main content
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()

​
Field Projection

Select only the fields you need: 
users := db.Query("User").
    Select("id", "name", "email").
    Execute(ctx)
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:
ErrorExample
Unknown entitydb.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)
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