Query Builder

The query builder provides a fluent interface for constructing database queries. It's generated for each model and provides compile-time type safety.

Getting a Query Builder

Access through the repository:

query := client.UserRepo().Query()

Builder Methods (Chainable)

All builder methods return the builder for chaining.

Filter

Add WHERE conditions. Multiple filters are ANDed together:

Query().Where(conditions...)

query.Where(
    filter.User.IsActive.IsTrue(),
    filter.User.Age.GreaterThan(18),
)

Search

Add full-text search conditions. Multiple conditions are ORed (any match):

Query().Search(searches...)

query.Search(filter.Article.Content.Matches("golang tutorial"))

SearchAll

Add full-text search conditions with AND semantics (all must match):

Query().SearchAll(searches...)

query.SearchAll(
    filter.Article.Content.Matches("golang"),
    filter.Article.Content.Matches("tutorial"),
)

Order

Sort results by one or more fields:

Query().Order(sorts...)

query.Order(by.User.Name.Asc())
query.Order(by.User.CreatedAt.Desc(), by.User.Name.Asc())

OrderRandom

Sort results randomly:

Query().OrderRandom()

Limit

Restrict maximum number of results:

Query().Limit(n int)

Start

Skip first n results (for pagination):

Query().Start(n int)

Fetch

Eager load related records:

Query().Fetch(relations...)

query.Fetch(with.User.Groups...)

Timeout

Set query execution timeout:

Query().Timeout(d time.Duration)

Parallel

Enable parallel query execution:

Query().Parallel(enabled bool)

TempFiles

Enable temporary file-based query processing for large result sets:

Query().TempFiles(enabled bool)

// Process large result sets using temporary files instead of memory
users, err := client.UserRepo().Query().
    Where(filter.User.IsActive.IsTrue()).
    Limit(100000).
    TempFiles(true).
    All(ctx)

Note: TempFiles reduces memory usage at the cost of slower performance. Not available with Live queries.

WithDeleted

Include soft-deleted records in results (only for models with som.SoftDelete):

Query().WithDeleted()

Range

Range query for models with string IDs (ULID, UUID, Rand) or complex IDs (ArrayID, ObjectID):

Query().Range(from som.RangeFrom, to som.RangeTo)

Range boundary constructors:

Constructor	Description
som.From[T](val)	Inclusive start bound
som.FromExclusive[T](val)	Exclusive start bound
som.FromStart()	Open-ended start (no lower bound)
som.To[T](val)	Exclusive end bound
som.ToInclusive[T](val)	Inclusive end bound
som.ToEnd()	Open-ended end (no upper bound)

String ID example:

results, err := client.UserRepo().Query().Range(
    som.From(som.ULID("01HY5E8ZQA1BCD2EF3GH4JK5MN")),
    som.To(som.ULID("01HY5E8ZQA9ZZZ9ZZ9ZZ9ZZ9ZZ")),
).All(ctx)

Open-ended range:

results, err := client.UserRepo().Query().Range(
    som.From(som.ULID("01HY5E8ZQA1BCD2EF3GH4JK5MN")),
    som.ToEnd(),
).All(ctx)

Complex ID example:

results, err := client.WeatherRepo().Query().Range(
    som.From(model.WeatherKey{City: "London", Date: start}),
    som.To(model.WeatherKey{City: "London", Date: end}),
).All(ctx)

Note: Range() returns a BuilderNoLive — live queries are not supported with range queries.

Execution Methods

These methods execute the query and return results.

All

Get all matching records:

func (b Builder) All(ctx context.Context) ([]*Model, error)

users, err := client.UserRepo().Query().
    Where(filter.User.IsActive.IsTrue()).
    All(ctx)

First

Get the first matching record. Returns ErrNotFound if no match:

func (b Builder) First(ctx context.Context) (*Model, error)

user, err := client.UserRepo().Query().
    Where(filter.User.Email.Equal("[e-mail]")).
    First(ctx)

if err != nil {
    if errors.Is(err, som.ErrNotFound) {
        // No matching record
    }
    return err
}
fmt.Println(user.Name)

Count

Get count of matching records:

func (b Builder) Count(ctx context.Context) (int, error)

count, err := client.UserRepo().Query().
    Where(filter.User.IsActive.IsTrue()).
    Count(ctx)

Exists

Check if any matching records exist:

func (b Builder) Exists(ctx context.Context) (bool, error)

exists, err := client.UserRepo().Query().
    Where(filter.User.Email.Equal("[e-mail]")).
    Exists(ctx)

Live

Subscribe to real-time updates:

func (b Builder) Live(ctx context.Context) (<-chan LiveResult[Model], error)

updates, err := client.UserRepo().Query().
    Where(filter.User.IsActive.IsTrue()).
    Live(ctx)

for update := range updates {
    if update.Error != nil {
        log.Println("Error:", update.Error)
        continue
    }
    fmt.Printf("Action: %s, Data: %+v\n", update.Action, update.Data)
}

AllMatches

Get all search results with metadata (scores, highlights, offsets):

func (b Builder) AllMatches(ctx context.Context) ([]SearchResult[Model], error)

results, err := client.ArticleRepo().Query().
    Search(filter.Article.Content.Matches("golang")).
    AllMatches(ctx)

for _, result := range results {
    fmt.Printf("Score: %f, Title: %s\n", result.Score(), result.Model.Title)
}

FirstMatch

Get the first search result with metadata:

func (b Builder) FirstMatch(ctx context.Context) (*SearchResult[Model], bool, error)

result, found, err := client.ArticleRepo().Query().
    Search(filter.Article.Content.Matches("golang")).
    FirstMatch(ctx)

if found {
    fmt.Printf("Best match: %s\n", result.Model.Title)
}

Iterator Methods

For processing large result sets efficiently, use the iterator methods. These leverage Go's range-over-func feature to stream results in batches.

Iterate

Iterate over all matching records in batches:

func (b Builder) Iterate(ctx context.Context, batchSize int) iter.Seq2[*Model, error]

// Process all active users in batches of 100
for user, err := range client.UserRepo().Query().
    Where(filter.User.IsActive.IsTrue()).
    Iterate(ctx, 100) {

    if err != nil {
        log.Fatal(err)
    }
    processUser(user)
}

IterateID

Iterate over record IDs only (more efficient when you only need IDs):

func (b Builder) IterateID(ctx context.Context, batchSize int) iter.Seq2[string, error]

// Collect all user IDs
var ids []string
for id, err := range client.UserRepo().Query().IterateID(ctx, 500) {
    if err != nil {
        log.Fatal(err)
    }
    ids = append(ids, id)
}

Early Termination

Iterators support breaking out early:

// Find first 10 matching a condition
count := 0
for user, err := range client.UserRepo().Query().Iterate(ctx, 50) {
    if err != nil {
        break
    }
    if someCondition(user) {
        count++
        if count >= 10 {
            break  // Stop iteration
        }
    }
}

When to Use Iterators

Scenario	Method
Process all records without loading into memory	Iterate
Need only record IDs	IterateID
Fixed number of results	Limit().All()
Need random access to results	All()

Async Methods

Every execution method has an async variant that returns immediately:

Sync	Async
All(ctx)	AllAsync(ctx)
First(ctx)	FirstAsync(ctx)
Count(ctx)	CountAsync(ctx)
Exists(ctx)	ExistsAsync(ctx)
Live(ctx)	LiveAsync(ctx)

Using Async Methods

// Start query in background
result := client.UserRepo().Query().
    Where(filter.User.IsActive.IsTrue()).
    AllAsync(ctx)

// Do other work...
doOtherWork()

// Get results when needed
users := <-result.Val()
err := <-result.Err()

Async Result Type

type asyncResult[T any] struct {
    val chan T
    err chan error
}

func (r *asyncResult[T]) Val() <-chan T
func (r *asyncResult[T]) Err() <-chan error

LiveResult Type

type LiveResult[M any] struct {
    Action string  // "CREATE", "UPDATE", or "DELETE"
    Data   *M      // The affected record
    Error  error   // Any error
}

SearchResult Type

Returned by AllMatches() and FirstMatch():

type SearchResult[M any] struct {
    Model      M                    // The matched model
    Scores     []float64            // BM25 relevance scores
    Highlights map[int]string       // Highlighted text by ref
    Offsets    map[int][]Offset     // Match positions by ref
}

Helper Methods

// Get the primary score (first in slice)
func (r SearchResult[M]) Score() float64

// Get highlighted text for a specific ref (defaults to 0)
func (r SearchResult[M]) Highlighted(ref ...int) string

// Get match offsets for a specific ref (defaults to 0)
func (r SearchResult[M]) Offset(ref ...int) []Offset

Score Sorting

The query package provides score-based sorting for search queries:

import "yourproject/gen/som/query"

Basic Score Sort

query.Score(0).Desc()      // Sort by score descending
query.Score(0).Asc()       // Sort by score ascending

Multiple Refs

query.Score(0, 1).Desc()   // Sort by combined scores

Combination Modes

query.Score(0, 1).Sum().Desc()              // Sum scores (default)
query.Score(0, 1).Max().Desc()              // Maximum score
query.Score(0, 1).Average().Desc()          // Average score
query.Score(0, 1).Weighted(2.0, 0.5).Desc() // Weighted combination

Usage Example

results, err := client.ArticleRepo().Query().
    Search(
        filter.Article.Title.Matches("golang").Ref(0),
        filter.Article.Content.Matches("golang").Ref(1),
    ).
    Order(query.Score(0, 1).Weighted(2.0, 1.0).Desc()).
    AllMatches(ctx)

Complete Example

// Complex query with all features
users, err := client.UserRepo().Query().
    // Filter conditions
    Where(
        filter.User.IsActive.IsTrue(),
        filter.User.Age.GreaterThanOrEqual(18),
        filter.Any(
            filter.User.Role.Equal("admin"),
            filter.User.Role.Equal("moderator"),
        ),
    ).
    // Sorting
    Order(
        by.User.CreatedAt.Desc(),
        by.User.Name.Asc(),
    ).
    // Pagination
    Limit(20).
    Start(0).
    // Eager loading
    Fetch(with.User.Posts...).
    // Execution options
    Timeout(5 * time.Second).
    Parallel(true).
    // Execute
    All(ctx)

Pagination Helper

func GetPage(ctx context.Context, page, pageSize int) ([]*model.User, error) {
    return client.UserRepo().Query().
        Where(filter.User.IsActive.IsTrue()).
        Order(by.User.CreatedAt.Desc()).
        Limit(pageSize).
        Start((page - 1) * pageSize).
        All(ctx)
}

// Get total for pagination UI
func GetTotal(ctx context.Context) (int, error) {
    return client.UserRepo().Query().
        Where(filter.User.IsActive.IsTrue()).
        Count(ctx)
}

Query Reuse

Queries can be built incrementally:

// Base query
baseQuery := client.UserRepo().Query().
    Where(filter.User.IsActive.IsTrue())

// Different executions
count, _ := baseQuery.Count(ctx)
first, _ := baseQuery.First(ctx)
all, _ := baseQuery.Limit(10).All(ctx)

Note: Each execution creates a new query based on the builder state at that point.