Struct QueryBuilder 

pub struct QueryBuilder { /* private fields */ }

Fluent query builder.

Example

let plan = QueryBuilder::new()
    .measurement("cpu")
    .tag("host", "server-01")
    .field("usage_idle")
    .range(start_ts, end_ts)
    .build()?;

Implementations

impl QueryBuilder

pub fn new() -> Self

Create a new empty query builder.

pub fn measurement(self, name: impl Into<String>) -> Self

Set the measurement to query.

pub fn tag(self, key: impl Into<String>, value: impl Into<String>) -> Self

Add a tag equality filter.

pub fn tags(self, tags: &[(&str, &str)]) -> Self

Add multiple tag equality filters.

pub fn field(self, name: impl Into<String>) -> Self

Add a field to the projection (select only these columns).

pub fn fields(self, names: &[&str]) -> Self

Add multiple fields to the projection.

pub fn range(self, start: Timestamp, end: Timestamp) -> Self

Set the time range filter.

pub fn last(self, duration: Duration) -> Self

Set the time range to the last duration from now.

Uses the current system time as the end point.

pub fn aggregate(self, function: AggFn) -> Self

Add an aggregation function.

pub fn group_by(self, columns: &[&str]) -> Self

Set the group-by columns for aggregation.

pub fn estimated_cardinality(self, cardinality: usize) -> Self

Set the estimated group-key cardinality.

When set, the query engine selects between hash-based and sort-based aggregation strategies. Low cardinality (≤ 1024) uses sort-based grouping for better cache locality and sorted output.

pub fn downsample(self, bucket: TimeBucket, function: AggFn) -> Self

Bucket results by bucket, and aggregate each bucket with function.

The bucket carries its own calendar, so all three of these mean what they say:

// A fixed five minutes, aligned to the Unix epoch.
.downsample(TimeBucket::fixed(Duration::from_secs(300)), AggFn::Avg)
// A calendar day in Berlin — 23 hours on the spring transition.
.downsample(TimeBucket::parse("1d", Some("Europe/Berlin"))?, AggFn::Max)
// A calendar month, which is not a span of anything.
.downsample(TimeBucket::parse("1mo", None)?, AggFn::Sum)

pub fn limit(self, n: usize) -> Self

Limit the number of returned rows.

pub fn offset(self, n: usize) -> Self

Skip the first n rows before returning results.

Must be used together with limit().

pub fn window(self, func: WindowFn) -> Self

Add a window function.

pub fn window_partition_by(self, columns: &[&str]) -> Self

Set the partition-by columns for window functions.

pub fn window_value_column(self, column: impl Into<String>) -> Self

Set the value column for window functions.

If not set, the first numeric field column is used by default.

pub fn namespace(self, ns: impl Into<String>) -> Self

Set the namespace scope for tenant isolation.

This embeds the NamespaceId structurally in the query plan AND injects the __namespace__ tag filter, ensuring data isolation even if the HTTP layer is bypassed.

pub fn namespace_scope(self, ns: Option<&str>) -> Self

Apply an optional namespace scope.

None means “no tenancy” — the single-tenant server and the embedded API, where points carry no namespace tag and a filter on one would match nothing. Call sites use this rather than branching, so that scoping a read is one uniform call instead of an if each of them can forget.

pub fn build(self) -> Result<QueryPlan>

Build and validate the query plan.

Errors

Returns QueryError::Validation if: No measurement is specified Time range is invalid (start > end)

Trait Implementations

impl Clone for QueryBuilder

fn clone(&self) -> QueryBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QueryBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for QueryBuilder

fn default() -> Self

Returns the “default value” for a type.