Query<R, F extends Fields> class

An immutable typed query bound to a SQL context.

Composition methods return new descriptions. compile and inspect perform no I/O; reads execute only with a bound database or session. select changes the result type without changing the typed source fields.

Implementers
Available extensions

Properties

database → QueryContext
The compilation or execution context that owns this query.
final
dependencies → ({bool opaque, Set<TableSchema> tables})
Physical read dependencies used by subscriptions, including relation batches.
no setter
hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

asCte(String name) → Cte<R, F>
Names this query as a CTE for further typed composition.
bind(QueryContext context) → Query<R, F>
Rebind the root description to an execution context. Nested queries retain their original context and are rejected when they do not match.
compile() → SqlCommand
Validates and compiles SQL with separately bound parameters, without I/O.
count({ExecutionOptions options = const ExecutionOptions()}) → Future<int>
Counts the query's result rows, including its limit, offset and grouping.
cursorToken(List<CursorTerm> cursor(F)) → String

Available on Query<R, F>, provided by the KeysetQuery extension

Versioned, lossless cursor transport. This is pagination input, not an authorization token. The next query still applies its own WHERE policies.
delete() → Mutation<F>
Prepares a delete; no SQL runs until the mutation is executed.
distinct() → Query<R, F>
Removes duplicate SQL projections before any Dart mapping.
exists({ExecutionOptions options = const ExecutionOptions()}) → Future<bool>
Checks whether the current query yields at least one row.
existsExpression() → Expr<bool>
Builds a SQL EXISTS expression without executing a read.
first({ExecutionOptions options = const ExecutionOptions()}) → Future<R>
Returns the first selected row, or throws QUERY.CARDINALITY if empty.
firstOrNull({ExecutionOptions options = const ExecutionOptions()}) → Future<R?>
Returns the first selected row, or null when the query is empty.
get({ExecutionOptions options = const ExecutionOptions()}) → Future<List<R>>
Executes the query and decodes all selected rows.
groupBy(List<Expr<Object?>> group(F)) → Query<R, F>
Replaces SQL grouping expressions; selected non-aggregates must be grouped.
having(Expr<bool?> condition(F)) → Query<R, F>
Adds an aggregate filter with AND to the existing HAVING clause.
inspect() → QueryPlan
Inspects SQL and conditional relation batches without acquiring a connection. This does not ask the database optimizer for an execution plan.
join<S, G extends Fields>(TableAlias<S, G> alias, {required Expr<bool?> on(F, G)}) → Query<R, F>
Adds an inner join using an independently created table alias.
leftJoin<S, G extends Fields>(TableAlias<S, G> alias, {required Expr<bool?> on(F, G)}) → Query<R, F>
Adds a left join; use the alias's optional selection for absent rows.
map<S>(S mapper(R)) → Query<S, F>
Maps decoded rows in Dart. This does not create SQL columns or change database DISTINCT/UNION semantics; compose SQL set operations first.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
orderBy(List<OrderTerm> order(F)) → Query<R, F>
Replaces the query's ordering with the supplied expressions.
scalar() → Expr<R?>
Converts a scalar selection into a nullable SQL subquery.
seekAfter(List<CursorTerm> cursor(F)) → Query<R, F>

Available on Query<R, F>, provided by the KeysetQuery extension

Adds a lexicographic boundary after cursor and replaces query ordering.
seekToken(String token, {required List<OrderTerm> orderBy(F)}) → Query<R, F>

Available on Query<R, F>, provided by the KeysetQuery extension

Restores a cursorToken using the expected table and complete sort order.
select<S>(Selection<S> selection(F)) → Query<S, F>
Chooses the SQL columns and result type to decode.
single({ExecutionOptions options = const ExecutionOptions()}) → Future<R>
Returns exactly one selected row or throws QUERY.CARDINALITY.
singleOrNull({ExecutionOptions options = const ExecutionOptions()}) → Future<R?>
Returns the only selected row, or null when empty.
skip(int count) → Query<R, F>
Replaces the row offset; count must be nonnegative.
stream({int batchSize = 128, ExecutionOptions options = const ExecutionOptions()}) → Stream<R>

Available on Query<R, F>, provided by the QueryStreaming extension

One database cursor, fetched on demand. Related rows are loaded per root batch on the same connection. Pause/await-for consumption provides demand.
take(int count) → Query<R, F>
Replaces the row limit; count must be nonnegative.
toString() → String
A string representation of this object.
inherited
union<G extends Fields>(Query<R, G> other) → Query<R, UnionFields<F>>

Available on Query<R, F>, provided by the SetQueries extension

Combines SQL scalars or .row projections. Both operands must use this database/session and the same codecs, column types and nullability.
unionAll<G extends Fields>(Query<R, G> other) → Query<R, UnionFields<F>>

Available on Query<R, F>, provided by the SetQueries extension

Keeps duplicate SQL rows. Row order requires an explicit final orderBy.
update(List<Assignment> assignments(F)) → Mutation<F>
Prepares an update; call the mutation's execute or returning method.
watch({Iterable<TableSchema> reads = const [], ExecutionOptions options = const ExecutionOptions()}) → Stream<List<R>>

Available on Query<R, F>, provided by the WatchQuery extension

Initial snapshot followed by fresh snapshots after relevant committed writes. Add tables hidden inside raw SQL with reads. Read errors are emitted without closing the stream, allowing a later invalidation to retry the query.
where(Expr<bool?> condition(F)) → Query<R, F>
Adds a predicate with AND, preserving any existing filter.

Operators

operator ==(Object other) → bool
The equality operator.
inherited