Struct QueryRequest 

pub struct QueryRequest<'a> { /* private fields */ }

Fluent builder for Laser::query. Accumulates a Query, then .fetch() returns the paged result, .fetch_typed::<T>() deserializes every row’s payload into T, .fetch_one::<T>() is the same but for at most one row.

Implementations

impl<'a> QueryRequest<'a>

pub fn deadline(self, timeout: Duration) -> Self

Set the absolute execution budget from now. The deadline applies to all pages under this query identity and is never extended by the server. The longest budget is 25 seconds. A longer one fails the fetch.

pub fn deadline_micros(self, deadline_micros: u64) -> Self

Replace the absolute execution deadline, in Unix epoch microseconds. A caller that already holds a deadline passes it through unchanged instead of converting it back into a relative budget.

pub const fn execution_id(&self) -> QueryExecutionId

The identity shared by execution, cursor pages, status, and cancellation.

pub async fn status(&self) -> Result<QueryExecutionStatus, LaserError>

Read the current execution state for this query identity.

pub async fn cancel(&self) -> Result<QueryExecutionStatus, LaserError>

Request cancellation for this query identity and return its observed state.

pub fn at_snapshot(self, snapshot_id: i64) -> Result<Self, LaserError>

Select one exact Iceberg snapshot for a lakehouse query.

pub fn at_timestamp_micros( self, timestamp_micros: i64, ) -> Result<Self, LaserError>

Select the retained Iceberg snapshot current at a timestamp.

pub fn where_eq( self, field: impl Into<String>, value: impl Into<TypedValue>, ) -> Self

Exact-match on an indexed field (point lookup).

pub fn conversation(self, conversation: ConversationId) -> Self

Narrow to the rows a single conversation produced (the conversation lens): an exact-match on the auto-projected CONVERSATION_FIELD, which a deployment materializes from every message’s gen_ai.conversation.id header. No producer-side index header is needed, so this works on any projection. Sugar over where_eq.

pub fn fork(self, fork_id: impl Into<String>) -> Self

Resolve this query against a fork’s copy-on-write view (the trunk overlaid with the fork’s speculative rows) instead of the trunk. Open the fork with Laser::fork.

pub fn filter_eq( self, field: impl Into<String>, value: impl Into<TypedValue>, ) -> Self

Filter rows where field == value.

pub fn filter_ne( self, field: impl Into<String>, value: impl Into<TypedValue>, ) -> Self

Filter rows where field != value.

pub fn filter_gt( self, field: impl Into<String>, value: impl Into<TypedValue>, ) -> Self

Filter rows where field > value (numeric if both parse as numbers, else lexical).

pub fn filter_gte( self, field: impl Into<String>, value: impl Into<TypedValue>, ) -> Self

Filter rows where field >= value.

pub fn filter_lt( self, field: impl Into<String>, value: impl Into<TypedValue>, ) -> Self

Filter rows where field < value.

pub fn filter_lte( self, field: impl Into<String>, value: impl Into<TypedValue>, ) -> Self

Filter rows where field <= value.

pub fn filter_in<T: Into<TypedValue>>( self, field: impl Into<String>, values: impl IntoIterator<Item = T>, ) -> Self

Filter rows where field is one of the given values.

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

Filter rows where field contains value (substring).

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

Filter rows where field starts with value.

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

Filter on agdx.idx.message_type.

pub fn time_range(self, start: u64, end: u64) -> Self

Filter rows whose agdx.idx.ts (epoch micros) falls in [start, end], both bounds inclusive.

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

Sort ascending by field (numeric-then-lexical).

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

Sort descending by field (numeric-then-lexical).

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

Limit the page to n rows. Zero or above MAX_PAGE_SIZE is rejected as LaserError::Invalid before the request is sent.

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

Resume from an opaque cursor that the server returned in a previous page. Replaces any offset.

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

Skip the first n matching rows.

pub fn with_payload(self) -> Self

Return the opaque payload bytes on each row (so you can decode them).

pub fn with_total(self) -> Self

Request an exact page.total (a COUNT(*) on the server). Default off: without it, page.total is None and page.has_more is still exact. Ask for this only when the exact count itself matters (e.g. rendering “page 3 of 12”), it costs a full-table scan on a wide filter.

pub fn read_your_writes(self) -> Self

Require read-your-writes: wait for the projector to apply the source log up to its current head before serving, so this query sees writes that completed before it. Bounded: if the projector cannot catch up in time the query returns QueryError::Stale (LaserError::is_stale()) instead of silently serving older data. Backend-gated: a deployment that cannot honor it returns Unsupported.

pub fn consistency(self, level: Consistency) -> Self

Set the read-consistency level explicitly (Eventual is the default, ReadYourWrites, or Strong). Strong is gated by strong_consistency.

pub fn text(self, query: impl Into<String>) -> Self

Lexical relevance search over every text-hinted indexed field. Relevance lands in each row’s score exactly as vector distance does. Gated by the keyword capability: refused locally when unadvertised, so an unaware backend can never silently drop the filter.

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

Lexical relevance search narrowed to one indexed field.

pub fn select_fields<S: Into<String>>( self, fields: impl IntoIterator<Item = S>, ) -> Self

Project only the named indexed fields into each result row.

pub fn count(self) -> Self

Aggregate: row count, output in the count result field.

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

Aggregate: sum of field, output in the sum result field.

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

Aggregate: arithmetic mean of field, output in the avg result field.

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

Aggregate: minimum of field, output in the min result field.

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

Aggregate: maximum of field, output in the max result field.

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

Aggregate: distinct count of field, output in the result field count_distinct.

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

Aggregate: population standard deviation of field, output in the stddev result field. Backend-gated (columnar backends only).

pub fn percentile(self, field: impl Into<String>, fraction: f64) -> Self

Aggregate: the fraction quantile of field (e.g. 0.95 for p95), output in the percentile result field. Backend-gated (columnar backends only).

pub fn agg_as( self, func: AggFunc, field: Option<String>, fraction: Option<f64>, alias: impl Into<String>, ) -> Self

Add an aggregate with an explicit output alias. Use to return several aggregates of the same kind in one query, or to name the output column.

pub fn group_by<S: Into<String>>( self, fields: impl IntoIterator<Item = S>, ) -> Self

Group the aggregate by the named fields.

pub fn window(self, field: impl Into<String>, every_micros: u64) -> Self

Bucket the aggregate into tumbling windows of every_micros over the timestamp field. Each result row carries a window_start header (the bucket’s lower edge in epoch micros).

pub fn having(self, filter: Filter) -> Self

Keep only aggregate groups matching filter. Predicate fields reference an aggregate alias (e.g. count) or a group key, not raw row fields.

pub fn distinct(self) -> Self

Return only distinct rows over the projected fields. Requires select_fields.

pub fn raw_sql(self, dialect: SqlDialect, sql: impl Into<String>) -> Self

Opt-in raw-SQL escape hatch: run sql (a single read-only SELECT) on the index’s backend. SQL backends only, not portable. Result columns come back as typed positional values aligned with the result fields.

pub fn raw_sql_with<V: Into<TypedValue>>( self, dialect: SqlDialect, sql: impl Into<String>, params: impl IntoIterator<Item = V>, ) -> Self

Like raw_sql but with positional bind params.

pub fn nearest(self, embedding: Vec<f32>, top_k: usize) -> Self

Approximate nearest-neighbour search against the default vector field (VECTOR_FIELD = "embedding"). Use nearest_in to point at a different field name.

pub fn nearest_in( self, field: impl Into<String>, embedding: Vec<f32>, top_k: usize, ) -> Self

Approximate nearest-neighbour search on an explicit field. Use when your projector stores the vector under a custom payload key.

pub async fn fetch(self) -> Result<QueryResult, LaserError>

Run the query and return the paged result + metadata.

pub async fn fetch_typed<T: DeserializeOwned>( self, ) -> Result<Vec<T>, LaserError>

Run the query, then deserialize every row’s payload into T (JSON). with_payload() is implied. Single-page only: use .stream_typed() or .fetch_all_typed() if there may be more than MAX_PAGE_SIZE matches.

pub async fn fetch_one<T: DeserializeOwned>( self, ) -> Result<Option<T>, LaserError>

Like fetch_typed but caps the result at one row.

pub async fn fetch_typed_with<C, T>(self) -> Result<Vec<T>, LaserError>

where C: Decoder<T>,

Like fetch_typed but decode each row’s payload with any Decoder (Json, Msgpack, or your own codec) instead of being locked to JSON. with_payload() is implied.

let readings: Vec<Reading> = laser.query("readings").fetch_typed_with::<Msgpack, _>().await?;

pub async fn fetch_one_with<C, T>(self) -> Result<Option<T>, LaserError>

where C: Decoder<T>,

Like fetch_one but decode the row with any Decoder instead of JSON.

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

Cap the total rows a rows walk may yield. Explicit by design (the bounded-reads law): a paged walk with no ceiling is an unbounded read dressed as a stream, so the ceiling is the caller writing a number, never a silent default.

pub fn rows(self) -> Result<QueryRows<'a>, LaserError>

Walk matching rows across pages, bounded by an explicit max_rows. Each .next().await yields the next row and the walk stops at the cap or the last page, whichever comes first. The grammar’s streaming terminal, mirroring the kv scan’s .entries().

let mut rows = laser.query("readings").where_eq("status", "degraded").max_rows(1_000).rows()?;
while let Some(row) = rows.next().await? {
    let _ = row;
}

pub fn rows_typed<T: DeserializeOwned>( self, ) -> Result<TypedQueryRows<'a, T>, LaserError>

Like rows but each yield is T decoded from the row’s payload, under the same explicit max_rows ceiling. with_payload() is implied, and the publisher must have chained .inline_payload() for the bytes to be there.

pub async fn fetch_all(self) -> Result<Vec<Row>, LaserError>

Materialize EVERY matching row by walking pages internally: the explicit full-result opt-in. Convenient when you need them all and the working set fits comfortably in memory. Prefer the bounded rows walk when it might not.

pub async fn fetch_all_typed<T: DeserializeOwned>( self, ) -> Result<Vec<T>, LaserError>

Materialize EVERY matching row, decoded into T: the explicit full-result opt-in, see fetch_all.

pub fn into_query(self) -> Query

Inspect the raw Query the builder produced (debugging).

pub fn filter(self, filter: Filter) -> Self

AND filter into the query’s predicate tree. The fluent filter_* helpers route through here, so chained filters compose as a conjunction. Build Any/Not subtrees with Filter::any/Filter::negate and pass them here.

Trait Implementations

impl<'a> From<QueryRequest<'a>> for Query

fn from(request: QueryRequest<'a>) -> Self

Converts to this type from the input type.