Query API Reference

• Query API Reference
  • Overview
  • Query Struct
  • QueryBuilder
    • Field Selection
    • Filters
    • Joins
    • Eager Loading
    • Distinct
    • Aggregations
    • Ordering
    • Pagination
  • Aggregate Types
    • AggregateFunction
    • AggregatedRow
    • AggregatedValue
  • Execution Order
  • Errors
  • Related Types

Overview

A Query describes what to retrieve from the database: which rows match, which columns to return, how to order and paginate them, and how to combine data across tables. Queries are constructed with QueryBuilder and consumed by Database::select, Database::select_raw, and Database::select_join.

For an introductory walkthrough, see the Querying Guide.

Query Struct

#![allow(unused)]
fn main() {
pub struct Query {
    columns: Select,
    pub distinct_by: Vec<String>,
    pub eager_relations: Vec<String>,
    pub filter: Option<Filter>,
    pub group_by: Vec<String>,
    pub having: Option<Filter>,
    pub joins: Vec<Join>,
    pub limit: Option<usize>,
    pub offset: Option<usize>,
    pub order_by: Vec<(String, OrderDirection)>,
}
}

Use Query::builder() to obtain a QueryBuilder.

QueryBuilder

Field Selection

The primary key is always included by Database::select::<T> even when not explicitly listed.

Filters

See Filters in the Querying Guide and JSON Filters for the full filter API.

Joins

Queries containing joins must be executed via Database::select_join. Calling Database::select::<T> with a joined query returns QueryError::JoinInsideTypedSelect.

Eager Loading

#![allow(unused)]
fn main() {
.with("posts")
}

Adds a foreign-key relation to load eagerly. Each relation is loaded once via a batch fetch keyed by the foreign-key column.

Distinct

#![allow(unused)]
fn main() {
.distinct(&["name"])
.distinct(&["category", "vendor"])
}

Sets distinct_by to the supplied list of column names. Rows are deduplicated by the tuple of values across those columns; the first row encountered for each distinct tuple is retained. Passing an empty slice is a no-op.

Semantics:

• Columns are looked up on the source record (ValuesSource::This).
• Missing columns are treated as Value::Null, so listing an unknown column collapses every row into a single result.
• Deduplication runs before ordering, offset, and limit.
• The selected fields (Select::Columns) do not need to include the distinct_by columns.

Aggregations

#![allow(unused)]
fn main() {
.group_by(&["category"])
.having(Filter::gt("count", Value::Uint64(10u64.into())))
}

Aggregations operate over the rows that survive WHERE and DISTINCT. Each group of rows sharing the same group_by tuple produces one AggregatedRow. The aggregate functions to compute are described by AggregateFunction; their results are returned as AggregatedValue entries inside the row.

The HAVING filter is evaluated after aggregation, against the grouping keys and aggregate results.

Ordering

Multiple order_by_* calls produce stable multi-key sorts; later keys break ties from earlier keys.

Pagination

Aggregate Types

Types used to describe and return aggregated query results. All three are re-exported from the wasm-dbms-api, ic-dbms-api, and ic-dbms-client preludes.

AggregateFunction

#![allow(unused)]
fn main() {
pub enum AggregateFunction {
    Count(Option<String>),
    Sum(String),
    Avg(String),
    Min(String),
    Max(String),
}
}

Describes one aggregate function to compute over a group of rows.

AggregatedRow

#![allow(unused)]
fn main() {
pub struct AggregatedRow {
    pub group_keys: Vec<Value>,
    pub values: Vec<AggregatedValue>,
}
}

A single row of aggregated output. group_keys holds the values of the group_by columns that identify the group; values holds the aggregate results in the same order as the AggregateFunction list supplied with the query.

AggregatedValue

#![allow(unused)]
fn main() {
pub enum AggregatedValue {
    Count(u64),
    Sum(Value),
    Avg(Value),
    Min(Value),
    Max(Value),
}
}

Carries the result of one aggregate function. Count is always a u64; the remaining variants wrap a Value whose concrete variant depends on the source column’s data type.

Execution Order

The select pipeline applies the query elements in this order — matching standard SQL semantics:

1. WHERE — filter is applied while scanning records (or via an index plan).
2. DISTINCT — distinct_by deduplicates the surviving rows.
3. GROUP BY / aggregates — when group_by is set, surviving rows are bucketed by the grouping tuple and the requested AggregateFunctions are computed per bucket, producing AggregatedRows.
4. HAVING — having filters the aggregated groups.
5. Eager loading — relations declared by with(...) are batch-fetched (non-aggregate selects only).
6. Column selection — non-selected columns are dropped from each row.
7. ORDER BY — order_by keys are applied in declared order.
8. OFFSET / LIMIT — applied last when order_by or distinct_by is set; otherwise applied during the scan for early termination.

When neither order_by nor distinct_by is present, the engine applies offset/limit during iteration to avoid materialising the entire result set.

Errors

All variants come from QueryError. Most are surfaced at planning time (before any rows are scanned) so callers fail fast.

Aggregate-specific (Database::aggregate)

Non-aggregate select paths

Related Types

• AggregateFunction — aggregate to compute per group
• AggregatedRow — single row of aggregated output
• AggregatedValue — single aggregate result value
• Filter — predicates for WHERE
• JsonFilter — JSON-specific predicates
• Join, JoinType — join clauses
• OrderDirection — ascending/descending
• Select — All or Columns(...)
• QueryError — query-time error variants