Query<T extends OrmEntity> class

Fluent builder for filtering, ordering, paginating, and eager-loading models of type T.

The Query class provides a powerful and flexible API for constructing database queries in a fluent manner. It supports a wide range of operations including WHERE clauses, JOINs, ORDER BY, LIMIT, OFFSET, eager loading of relations, and various aggregation functions.

Queries are executed against a QueryContext which provides the underlying database driver and model definitions.

Example:

final users = await context.query<User>()
  .where('active', equals: true)
  .orderBy('name')
  .get();

final activePosts = await context.query<Post>()
  .joinRelation('author')
  .where('author.isActive', true)
  .get();

Constructors

Query({required ModelDefinition<T> definition, required QueryContext context, List<FilterClause>? filters, List<OrderClause>? orders, List<RawOrderExpression>? rawOrders, List<CustomOrderExpression>? customOrders, List<RelationLoad>? relations, List<JoinDefinition>? joins, List<IndexHint>? indexHints, List<FullTextWhere>? fullTextWheres, List<JsonWhereClause>? jsonWheres, List<DateWhereClause>? dateWheres, bool randomOrder = false, num? randomSeed, String? lockClause, int? limit, int? offset, QueryPredicate? predicate, List<String>? selects, List<RawSelectExpression>? rawSelects, List<CustomSelectExpression>? customSelects, List<ProjectionOrderEntry>? projectionOrder, List<AggregateExpression>? aggregates, List<String>? groupBy, List<RawGroupByExpression>? rawGroupBy, List<CustomGroupByExpression>? customGroupBy, QueryPredicate? having, List<RelationAggregate>? relationAggregates, List<RelationOrder>? relationOrders, Map<String, RelationPath>? relationPaths, Set<String>? ignoredScopes, bool globalScopesApplied = false, bool ignoreAllGlobalScopes = false, String? tableAlias, List<String>? adHocScopes, Map<String, RelationJoinRequest>? relationJoinRequests, GroupLimit? groupLimit, bool distinct = false, List<DistinctOnClause>? distinctOn, List<QueryUnion>? unions, Duration? cacheTtl, bool disableCache = false, bool disableAutoHydration = false, bool suppressEvents = false})

Properties

adHocScopes → List<String>: no setter
adHocScopes → List<String>: Available on Query<T>, provided by the UtilityExtension extension
Returns the list of ad-hoc scopes to apply.
no setter
context → QueryContext: final
definition → ModelDefinition<T>: final
disableAutoHydration → bool: Whether auto-hydration of model columns is disabled for this query.
no setter
globalScopesApplied → bool: no setter
globalScopesApplied → bool: Available on Query<T>, provided by the UtilityExtension extension
Returns whether all global scopes have been applied to this query.
no setter
hashCode → int: The hash code for this object.
no setterinherited
ignoreAllGlobalScopes → bool: no setter
ignoreAllGlobalScopes → bool: Available on Query<T>, provided by the UtilityExtension extension
Returns whether all global scopes should be ignored for this query.
no setter
ignoredGlobalScopes → Set<String>: no setter
ignoredGlobalScopes → Set<String>: Available on Query<T>, provided by the UtilityExtension extension
Returns the set of global scope identifiers that should be ignored.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
suppressEvents → bool: Whether model events are suppressed for this query.
no setter

Methods

addSelect(String column) → Query<T>: Available on Query<T>, provided by the SelectExtension extension
Adds a single column to the select projection.
applySoftDeleteFilter(FieldDefinition field) → Query<T>
avg(String expression, {String? alias}) → Query<T>: Available on Query<T>, provided by the AggregateExtension extension
Adds an AVG aggregate to the select projection.
avgValue(String expression, {String? alias}) → Future<num?>: Available on Query<T>, provided by the AggregateExtension extension
Executes an AVG aggregate and returns the result.
chunk(int size, ChunkCallback<T> callback, {int startPage = 1}) → Future<void>: Available on Query<T>, provided by the PaginateExtension extension
Iterates rows in fixed-size chunks, invoking callback for each batch.
chunkById(int size, ChunkCallback<T> callback, {String? column}) → Future<void>: Available on Query<T>, provided by the PaginateExtension extension
Iterates rows ordered by column (defaults to the primary key).
count({String expression = '*'}) → Future<int>: Available on Query<T>, provided by the UtilityExtension extension
Returns the number of rows that match the current query.
countAggregate({String expression = '*', String? alias}) → Query<T>: Available on Query<T>, provided by the AggregateExtension extension
Adds a COUNT aggregate to the select projection.
create(Map<String, dynamic> attributes) → Future<T>: Available on Query<T>, provided by the CrudExtension extension
Creates a single record from the given attributes map. Returns the created model instance with its generated ID.
createMany(List<Map<String, dynamic>> records) → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Creates multiple records from a list of attribute maps. Returns the created model instances with their generated IDs.
crossJoin(Object table, [Object? constraint, Object? operator, Object? second]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a CROSS JOIN clause to the query. When constraint is omitted, a simple CROSS JOIN table is emitted.
crossJoinSub(Query query, String alias, [Object? constraint, Object? operator, Object? second]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a CROSS JOIN against a subquery.
cursorPaginate({int perPage = 15, Object? cursor, String? column, bool descending = false}) → Future<CursorPageResult<T>>: Available on Query<T>, provided by the PaginateExtension extension
Cursor-based pagination that resumes from cursor when present.
debugPlan() → QueryPlan: Exposes the built plan for tests.
decrement(String column, [num amount = 1]) → Future<int>: Available on Query<T>, provided by the CrudExtension extension
Decrements the value of a numeric column by amount.
delete() → Future<int>: Available on Query<T>, provided by the CrudExtension extension
Deletes all records matching the query conditions.
deleteReturning() → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Deletes matching rows and returns hydrated models when the driver supports RETURNING.
deleteWhere(Object where) → Future<int>: Available on Query<T>, provided by the CrudExtension extension
Deletes records matching a flexible where input (PK, map, DTO, partial, tracked model).
deleteWhereMany(List<Object> wheres) → Future<int>: Available on Query<T>, provided by the CrudExtension extension
Deletes multiple records using flexible where inputs.
deleteWhereManyReturning(List<Object> wheres) → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Deletes multiple records using flexible where inputs and returns hydrated models.
deleteWhereReturning(Object where) → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Deletes records using flexible where inputs and returns hydrated models.
destroy(dynamic ids) → Future<int>: Available on Query<T>, provided by the CrudExtension extension
Deletes records by their primary key(s). Accepts a single ID or a list of IDs. Returns the number of deleted rows.
distinct([Iterable<String> columns = const []]) → Query<T>: Available on Query<T>, provided by the DistinctExtension extension
Applies DISTINCT (and optional DISTINCT ON) semantics to the select.
doesntExist() → Future<bool>: Available on Query<T>, provided by the UtilityExtension extension
Returns true if no rows match the current query.
dontRemember() → Query<T>: Available on Query<T>, provided by the QueryCachingExtension extension
Disable caching for this query (even if parent had caching).
each(Future<void> callback(T model), {int chunkSize = 100}) → Future<void>: Available on Query<T>, provided by the StreamingExtension extension
Iterates over query results with a callback.
eachById(int size, RowCallback<T> callback, {String? column}) → Future<void>: Available on Query<T>, provided by the PaginateExtension extension
Visits each row individually in ID order using chunkById under the hood.
exists() → Future<bool>: Available on Query<T>, provided by the UtilityExtension extension
Returns true if any rows match the current query.
find(Object key) → Future<T?>: Available on Query<T>, provided by the CrudExtension extension
Finds a model by its primary key.
findMany(Iterable<Object> keys) → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Finds multiple models by their primary keys.
findOrFail(Object key) → Future<T>: Available on Query<T>, provided by the CrudExtension extension
Finds a model by primary key or throws when missing.
first() → Future<T?>: Available on Query<T>, provided by the CrudExtension extension
Returns the first model instance or null when no rows exist.
firstOrCreate(Map<String, dynamic> attributes, [Map<String, dynamic> values = const {}]) → Future<T>: Available on Query<T>, provided by the CrudExtension extension
Finds the first record matching the attributes, or creates it if not found.
firstOrFail({Object? key}) → Future<T>: Available on Query<T>, provided by the CrudExtension extension
Returns the first model or throws when no records exist.
firstOrNull() → Future<T?>: Available on Query<T>, provided by the CrudExtension extension
Alias for first to match Laravel naming.
firstPartial<P extends PartialEntity<T>>(P factory(Map<String, Object?>)) → Future<P?>: Available on Query<T>, provided by the CrudExtension extension
Returns the first result as a partial entity or null if none exist.
firstRow() → Future<QueryRow<T>?>: Available on Query<T>, provided by the CrudExtension extension
Returns the first matching row or null if none exist.
forceDelete() → Future<int>: Available on Query<T>, provided by the SoftDeleteExtension extension
Permanently deletes models that match the current query constraints, bypassing soft deletes.
forceIndex(List<String> indexes) → Query<T>: Available on Query<T>, provided by the IndexExtension extension
Applies a FORCE INDEX hint (MySQL/MariaDB only).
get() → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Returns only the models without the surrounding QueryRow metadata.
getPartial<P extends PartialEntity<T>>(P factory(Map<String, Object?>)) → Future<List<P>>: Available on Query<T>, provided by the CrudExtension extension
Returns results hydrated into partial entities.
groupBy(List<String> columns) → Query<T>: Available on Query<T>, provided by the GroupingExtension extension
Groups rows by the provided columns.
groupByExtension(String key, [Object? payload]) → Query<T>: Available on Query<T>, provided by the GroupingExtension extension
Adds a custom GROUP BY expression compiled by a driver extension.
groupByRaw(String sql, [List<Object?> bindings = const []]) → Query<T>: Available on Query<T>, provided by the RawQueryExtension extension
Adds a raw GROUP BY expression.
having(String field, PredicateOperator operator, Object? value) → Query<T>: Available on Query<T>, provided by the GroupingExtension extension
Adds a HAVING predicate over grouped rows.
havingBitwise(String field, String operator, Object value) → Query<T>: Available on Query<T>, provided by the GroupingExtension extension
Adds a HAVING clause with a bitwise operator.
havingExtension(String key, [Object? payload]) → Query<T>: Available on Query<T>, provided by the GroupingExtension extension
Adds a custom HAVING predicate compiled by a driver extension.
havingRaw(String sql, [List<Object?> bindings = const []]) → Query<T>: Available on Query<T>, provided by the GroupingExtension extension
Adds a raw HAVING fragment.
ignoreIndex(List<String> indexes) → Query<T>: Available on Query<T>, provided by the IndexExtension extension
Applies an IGNORE INDEX hint (MySQL/MariaDB only).
increment(String column, [num amount = 1]) → Future<int>: Available on Query<T>, provided by the CrudExtension extension
Increments the value of a numeric column by amount.
insertGetIds(List<T> records) → Future<List<int>>: Available on Query<T>, provided by the BatchOperationsExtension extension
Inserts multiple records and returns all generated IDs.
insertInput(Object input, {bool ignoreConflicts = false}) → Future<T>: Available on Query<T>, provided by the CrudExtension extension
insertManyInputs(List<Object> inputs, {bool ignoreConflicts = false, bool returning = true, bool fallbackToOriginalWhenNoReturn = true}) → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Inserts flexible inputs and returns hydrated models.
insertManyInputsRaw(List<Object> inputs, {bool ignoreConflicts = false}) → Future<MutationResult>: Available on Query<T>, provided by the CrudExtension extension
Inserts flexible inputs and returns the raw MutationResult.
insertOrIgnoreUsing(Iterable<String> columns, Query source) → Future<int>: Available on Query<T>, provided by the UnionExtension extension
Inserts rows into this query's table using the results of source, ignoring duplicate key errors.
insertUsing(Iterable<String> columns, Query source, {bool ignoreConflicts = false}) → Future<int>: Available on Query<T>, provided by the UnionExtension extension
Inserts rows into this query's table using the results of source. The columns list must contain one entry per value selected by source.
join(Object table, Object constraint, [Object? operator, Object? second]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds an INNER JOIN clause to the query.
joinLateral(Query query, String alias, {JoinType type = JoinType.inner, JoinConstraintBuilder? on}) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a (driver-gated) LATERAL JOIN clause.
joinRelation(String relation, {JoinType type = JoinType.inner}) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Joins a relation path without eager loading it.
joinSub(Query query, String alias, Object constraint, [Object? operator, Object? second]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds an INNER JOIN against a subquery.
joinWhere(Object table, Object column, [Object? operator, Object? value]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds an INNER JOIN ... WHERE clause to the query.
leftJoin(Object table, Object constraint, [Object? operator, Object? second]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a LEFT JOIN clause to the query.
leftJoinLateral(Query query, String alias, {JoinConstraintBuilder? on}) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a LEFT JOIN LATERAL clause.
leftJoinSub(Query query, String alias, Object constraint, [Object? operator, Object? second]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a LEFT JOIN against a subquery.
leftJoinWhere(Object table, Object column, [Object? operator, Object? value]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a LEFT JOIN ... WHERE clause to the query.
limit(int? value) → Query<T>: Available on Query<T>, provided by the PaginateExtension extension
Limits the number of rows returned.
limitPerGroup(int limit, String column, {int? offset}) → Query<T>: Available on Query<T>, provided by the GroupingExtension extension
Limits the number of rows returned per group.
lock(String clause) → Query<T>: Available on Query<T>, provided by the LockExtension extension
Adds a custom lock clause to the query.
lockForUpdate() → Query<T>: Available on Query<T>, provided by the LockExtension extension
Adds a FOR UPDATE lock clause to the query.
macro(String name, [List<Object?> args = const []]) → Query<T>: Available on Query<T>, provided by the ScopeExtension extension
Applies a registered query macro to the query.
mapRows<R extends OrmEntity>(R mapper(AdHocRow row)) → MappedAdHocQuery<R>: Available on Query<AdHocRow>, provided by the MapQueryExtensions extension
markGlobalScopesApplied() → Query<T>: Available on Query<T>, provided by the UtilityExtension extension
Marks this query as having global scopes applied.
max(String expression, {String? alias}) → Query<T>: Available on Query<T>, provided by the AggregateExtension extension
Adds a MAX aggregate to the select projection.
maxValue(String expression, {String? alias}) → Future<num?>: Available on Query<T>, provided by the AggregateExtension extension
Executes a MAX aggregate and returns the result.
min(String expression, {String? alias}) → Query<T>: Available on Query<T>, provided by the AggregateExtension extension
Adds a MIN aggregate to the select projection.
minValue(String expression, {String? alias}) → Future<num?>: Available on Query<T>, provided by the AggregateExtension extension
Executes a MIN aggregate and returns the result.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
offset(int? value) → Query<T>: Available on Query<T>, provided by the PaginateExtension extension
Skips value rows before reading results.
onlyTrashed() → Query<T>: Available on Query<T>, provided by the SoftDeleteExtension extension
Retrieves only soft-deleted models.
orderBy(String field, {bool descending = false}) → Query<T>: Available on Query<T>, provided by the OrderExtension extension
Orders results by field. Set descending to sort in reverse.
orderByExtension(String key, {Object? payload, bool descending = false}) → Query<T>: Available on Query<T>, provided by the OrderExtension extension
Orders results using a driver extension expression.
orderByRandom([num? seed]) → Query<T>: Available on Query<T>, provided by the OrderExtension extension
Orders results randomly.
orderByRaw(String sql, [List<Object?> bindings = const []]) → Query<T>: Available on Query<T>, provided by the RawQueryExtension extension
Adds a raw ORDER BY expression.
orderByRelation(String relation, {bool descending = false, RelationAggregateType aggregate = RelationAggregateType.count, PredicateCallback<OrmEntity>? constraint, bool distinct = false}) → Query<T>: Available on Query<T>, provided by the RelationExtension extension
Orders results based on a relation aggregate.
orHavingBitwise(String field, String operator, Object value) → Query<T>: Available on Query<T>, provided by the GroupingExtension extension
Adds a HAVING clause with a bitwise operator using OR chaining.
orHavingExtension(String key, [Object? payload]) → Query<T>: Available on Query<T>, provided by the GroupingExtension extension
Adds a custom HAVING predicate using OR logic.
orHavingRaw(String sql, [List<Object?> bindings = const []]) → Query<T>: Available on Query<T>, provided by the GroupingExtension extension
Adds a raw HAVING fragment using OR logic.
orWhere(Object fieldOrCallback, [Object? value, PredicateOperator operator = PredicateOperator.equals]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
OR variant of where.
orWhereBitwise(String field, String operator, Object value) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a bitwise predicate with OR chaining.
orWhereExists(Query subquery) → Query<T>: Available on Query<T>, provided by the SubqueryExtension extension
Adds an OR WHERE EXISTS subquery predicate.
orWhereExtension(String key, [Object? payload]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a custom WHERE predicate using OR logic.
orWhereHas(String relation, [PredicateCallback<OrmEntity>? constraint]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds an OR WHERE HAS clause for a relation.
orWhereHasTyped<TRelated extends OrmEntity>(String relation, [PredicateCallback<TRelated>? constraint]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Typed variant of orWhereHas that accepts a typed predicate callback.
orWhereInSubquery(String field, Query subquery) → Query<T>: Available on Query<T>, provided by the SubqueryExtension extension
Adds an OR WHERE IN subquery predicate.
orWhereJsonContains(String field, Object? value) → Query<T>: Available on Query<T>, provided by the JsonExtension extension
Adds an OR JSON containment predicate.
orWhereJsonContainsKey(String field) → Query<T>: Available on Query<T>, provided by the JsonExtension extension
Adds an OR JSON containsKey predicate.
orWhereJsonLength(String field, int length, {PredicateOperator operator = PredicateOperator.equals}) → Query<T>: Available on Query<T>, provided by the JsonExtension extension
Adds an OR JSON length predicate.
orWhereJsonOverlaps(String field, Object value) → Query<T>: Available on Query<T>, provided by the JsonExtension extension
Adds an OR JSON overlaps predicate.
orWhereNotExists(Query subquery) → Query<T>: Available on Query<T>, provided by the SubqueryExtension extension
Adds an OR WHERE NOT EXISTS subquery predicate.
orWhereNotInSubquery(String field, Query subquery) → Query<T>: Available on Query<T>, provided by the SubqueryExtension extension
Adds an OR WHERE NOT IN subquery predicate.
orWhereTyped(PredicateCallback<T> callback) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a typed predicate callback with OR logic.
paginate({int perPage = 15, int page = 1}) → Future<PageResult<T>>: Available on Query<T>, provided by the PaginateExtension extension
Returns a paginated payload including totals and metadata.
pluck<R>(String field) → Future<List<R>>: Available on Query<T>, provided by the CrudExtension extension
Returns a list of values from field.
previewDeleteWherePlan(List<Object> wheres, {bool returning = false}) → MutationPlan: Available on Query<T>, provided by the CrudExtension extension
Builds but does not execute a delete plan for flexible inputs (useful for previews).
previewInsertPlan(List<Object> inputs, {bool ignoreConflicts = false, bool returning = false}) → MutationPlan: Available on Query<T>, provided by the CrudExtension extension
Builds but does not execute an insert plan (useful for previews).
previewUpdatePlan(List<Object> inputs, {Object? where, JsonUpdateBuilder<T>? jsonUpdates, bool returning = false}) → MutationPlan: Available on Query<T>, provided by the CrudExtension extension
Builds but does not execute an update plan (useful for previews).
previewUpsertPlan(List<Object> inputs, {List<String>? uniqueBy, List<String>? updateColumns, JsonUpdateBuilder<T>? jsonUpdates, bool returning = false}) → MutationPlan: Available on Query<T>, provided by the CrudExtension extension
Builds but does not execute an upsert plan (useful for previews).
remember(Duration ttl) → Query<T>: Available on Query<T>, provided by the QueryCachingExtension extension
Cache query results for the specified duration.
rememberForever() → Query<T>: Available on Query<T>, provided by the QueryCachingExtension extension
Cache query results indefinitely (until manually cleared).
restore() → Future<int>: Available on Query<T>, provided by the SoftDeleteExtension extension
Restores soft-deleted models that match the current query constraints.
rightJoin(Object table, Object constraint, [Object? operator, Object? second]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a RIGHT JOIN clause to the query.
rightJoinSub(Query query, String alias, Object constraint, [Object? operator, Object? second]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a RIGHT JOIN against a subquery.
rightJoinWhere(Object table, Object column, [Object? operator, Object? value]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a RIGHT JOIN ... WHERE clause to the query.
rows() → Future<List<QueryRow<T>>>: Available on Query<T>, provided by the CrudExtension extension
Executes the query and returns hydrated QueryRow objects.
scope(String name, [List<Object?> args = const []]) → Query<T>: Available on Query<T>, provided by the ScopeExtension extension
Applies a registered local scope to the query.
select(List<String> columns) → Query<T>: Available on Query<T>, provided by the SelectExtension extension
Only the specified columns will be retrieved from the database.
selectExtension(String key, {Object? payload, String? alias}) → Query<T>: Available on Query<T>, provided by the SelectExtension extension
Adds a custom select expression compiled by a driver extension.
selectRaw(String sql, {String? alias, List<Object?> bindings = const []}) → Query<T>: Available on Query<T>, provided by the SelectExtension extension
Adds a raw select expression with optional bindings.
sharedLock() → Query<T>: Available on Query<T>, provided by the LockExtension extension
Adds a SHARED LOCK clause to the query.
simplePaginate({int perPage = 15, int page = 1}) → Future<SimplePageResult<T>>: Available on Query<T>, provided by the PaginateExtension extension
Returns a simplified pagination payload without running a count query.
sole() → Future<T>: Available on Query<T>, provided by the CrudExtension extension
Ensures there is exactly one record and returns it.
straightJoin(Object table, Object constraint, [Object? operator, Object? second]) → Query<T>: Available on Query<T>, provided by the JoinExtension extension
Adds a STRAIGHT_JOIN clause (MySQL / MariaDB only).
stream({int chunkSize = 100}) → Stream<T>: Available on Query<T>, provided by the StreamingExtension extension
Returns an async stream of query results.
streamModels() → Stream<T>: Available on Query<T>, provided by the PaginateExtension extension
Streams models sequentially.
streamRows({int eagerLoadBatchSize = Query._defaultStreamEagerBatchSize}) → Stream<QueryRow<T>>: Available on Query<T>, provided by the PaginateExtension extension
Streams rows sequentially (still buffered by the underlying driver).
sum(String expression, {String? alias}) → Query<T>: Available on Query<T>, provided by the AggregateExtension extension
Adds a SUM aggregate to the select projection.
sumValue(String expression, {String? alias}) → Future<num?>: Available on Query<T>, provided by the AggregateExtension extension
Executes a SUM aggregate and returns the result.
tap(void callback(Query<T> query)) → Query<T>: Available on Query<T>, provided by the UtilityExtension extension
Taps into the query chain without modifying it.
toSql() → StatementPreview: Available on Query<T>, provided by the UtilityExtension extension
Returns the SQL preview without executing the query.
toString() → String: A string representation of this object.
inherited
union(Query query) → Query<T>: Available on Query<T>, provided by the UnionExtension extension
Adds a UNION clause combining the current query with query.
unionAll(Query query) → Query<T>: Available on Query<T>, provided by the UnionExtension extension
Adds a UNION ALL clause combining the current query with query.
unless(Object condition, Query<T> callback(Query<T> query)) → Query<T>: Available on Query<T>, provided by the UtilityExtension extension
Conditionally applies a callback to the query when the condition is false.
update(Map<String, Object?> values) → Future<int>: Available on Query<T>, provided by the CrudExtension extension
Updates rows that match the current query constraints.
updateBatch(List<Map<String, Object?>> updates, {Object uniqueBy = 'id'}) → Future<int>: Available on Query<T>, provided by the BatchOperationsExtension extension
Updates multiple rows with different values in a single batch operation.
updateInputs(List<Object> inputs, {Object? where, JsonUpdateBuilder<T>? jsonUpdates}) → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Updates rows using flexible inputs.
updateInputsRaw(List<Object> inputs, {Object? where, JsonUpdateBuilder<T>? jsonUpdates}) → Future<MutationResult>: Available on Query<T>, provided by the CrudExtension extension
Updates rows using flexible inputs and returns the raw MutationResult.
updateOrCreate(Map<String, dynamic> attributes, Map<String, dynamic> values) → Future<T>: Available on Query<T>, provided by the CrudExtension extension
Updates the first record matching the attributes, or creates it if not found.
updateOrInsert(Map<String, Object?> attributes, Map<String, Object?> values) → Future<bool>: Available on Query<T>, provided by the CrudExtension extension
Updates existing record or inserts if it doesn't exist.
updateReturning(Object values) → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Updates rows and returns hydrated models using driver RETURNING when available.
updateValues(Object values) → Future<int>: Available on Query<T>, provided by the CrudExtension extension
Updates matching records using flexible inputs.
upsert(Map<String, dynamic> attributes, {List<String>? uniqueBy, List<String>? updateColumns}) → Future<T>: Available on Query<T>, provided by the CrudExtension extension
Upserts (insert or update) a single record.
upsertInputs(List<Object> inputs, {List<String>? uniqueBy, List<String>? updateColumns, JsonUpdateBuilder<T>? jsonUpdates}) → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Upserts flexible inputs and returns hydrated models.
upsertMany(List<Map<String, dynamic>> records, {List<String>? uniqueBy, List<String>? updateColumns}) → Future<List<T>>: Available on Query<T>, provided by the CrudExtension extension
Upserts (inserts or updates) multiple records.
useIndex(List<String> indexes) → Query<T>: Available on Query<T>, provided by the IndexExtension extension
Applies a USE INDEX hint (MySQL/MariaDB only).
value<R>(String field) → Future<R?>: Available on Query<T>, provided by the SelectExtension extension
Returns the value of field from the first row, or null when missing.
when(Object condition, Query<T> callback(Query<T> query)) → Query<T>: Available on Query<T>, provided by the UtilityExtension extension
Conditionally applies a callback to the query.
where(Object fieldOrCallback, [Object? value, PredicateOperator operator = PredicateOperator.equals]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Generic where that accepts either a column comparison or a grouped predicate callback.
whereBetween(String field, Object lower, Object upper) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a WHERE BETWEEN predicate.
whereBitwise(String field, String operator, Object value) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a bitwise predicate.
whereColumn(String left, String right, {PredicateOperator operator = PredicateOperator.columnEquals}) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a predicate comparing two columns.
whereDate(String field, Object valueOrOperator, [Object? value]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Compares the DATE portion of field. Defaults to equality comparisons when only a single value is supplied.
whereDay(String field, Object valueOrOperator, [Object? value]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Filters by calendar day (1-31) regardless of timezone.
whereEquals(String field, Object? value) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds an equality comparison for the column mapped by field.
whereExists(Query subquery) → Query<T>: Available on Query<T>, provided by the SubqueryExtension extension
Adds a WHERE EXISTS subquery predicate.
whereExtension(String key, [Object? payload]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a custom WHERE predicate compiled by a driver extension.
whereFullText(List<String> columns, Object value, {String? language, FullTextMode mode = FullTextMode.natural, bool expanded = false, String? indexName}) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a full-text predicate.
whereGreaterThan(String field, Object value) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a > comparison for field.
whereGreaterThanOrEqual(String field, Object value) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a >= comparison for field.
whereHas(String relation, [PredicateCallback<OrmEntity>? constraint]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a WHERE HAS clause for a relation.
whereHasTyped<TRelated extends OrmEntity>(String relation, [PredicateCallback<TRelated>? constraint]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Typed variant of whereHas that accepts a typed predicate callback.
whereILike(String field, Object value) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds an ILIKE predicate.
whereIn(String field, Iterable<Object?> values) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds an IN comparison for field using values.
whereInSubquery(String field, Query subquery) → Query<T>: Available on Query<T>, provided by the SubqueryExtension extension
Adds a WHERE IN subquery predicate.
whereJsonContains(String field, Object? value, {String? path}) → Query<T>: Available on Query<T>, provided by the JsonExtension extension
Adds a JSON containment predicate (dialect-aware).
whereJsonContainsKey(String field, [String? path]) → Query<T>: Available on Query<T>, provided by the JsonExtension extension
Adds a JSON contains key predicate.
whereJsonLength(String field, Object operatorOrLength, [int? length]) → Query<T>: Available on Query<T>, provided by the JsonExtension extension
Adds a JSON length comparison predicate.
whereJsonOverlaps(String field, Object value, {String? path}) → Query<T>: Available on Query<T>, provided by the JsonExtension extension
Adds a JSON overlaps predicate (at least one shared array element).
whereLessThan(String field, Object value) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a < comparison for field.
whereLessThanOrEqual(String field, Object value) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a <= comparison for field.
whereLike(String field, Object value, {bool caseInsensitive = false}) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a LIKE predicate.
whereMonth(String field, Object valueOrOperator, [Object? value]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Filters by calendar month (1-12).
whereNotBetween(String field, Object lower, Object upper) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a WHERE NOT BETWEEN predicate.
whereNotEquals(String field, Object? value) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a != comparison for the column mapped by field.
whereNotExists(Query subquery) → Query<T>: Available on Query<T>, provided by the SubqueryExtension extension
Adds a WHERE NOT EXISTS subquery predicate.
whereNotILike(String field, Object value) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a NOT ILIKE predicate.
whereNotIn(String field, Iterable<Object?> values) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a NOT IN comparison for field using values.
whereNotInSubquery(String field, Query subquery) → Query<T>: Available on Query<T>, provided by the SubqueryExtension extension
Adds a WHERE NOT IN subquery predicate.
whereNotLike(String field, Object value, {bool caseInsensitive = false}) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a NOT LIKE predicate.
whereNotNull(String field) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a NOT NULL predicate.
whereNull(String field) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a NULL predicate.
whereRaw(String sql, [List<Object?> bindings = const []]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a raw predicate fragment.
whereTime(String field, Object valueOrOperator, [Object? value]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Compares the HH:mm:ss component of field.
whereTyped(PredicateCallback<T> callback) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Adds a typed predicate callback to the query.
whereYear(String field, Object valueOrOperator, [Object? value]) → Query<T>: Available on Query<T>, provided by the WhereExtension extension
Filters by four-digit calendar year.
with_(List<String> names) → Query<T>: Available on Query<T>, provided by the RelationExtension extension
Requests eager loading for multiple relations.
withAggregate(AggregateFunction function, String expression, {String? alias}) → Query<T>: Available on Query<T>, provided by the AggregateExtension extension
Registers an aggregate projection, e.g. count('*').
withAvg(String relation, String column, {String? alias, PredicateCallback<OrmEntity>? constraint}) → Query<T>: Available on Query<T>, provided by the RelationExtension extension
Adds a WITH AVG aggregate for a relation.
withCount(String relation, {String? alias, PredicateCallback<OrmEntity>? constraint, bool distinct = false}) → Query<T>: Available on Query<T>, provided by the RelationExtension extension
Adds a WITH COUNT aggregate for a relation.
withExists(String relation, {String? alias, PredicateCallback<OrmEntity>? constraint}) → Query<T>: Available on Query<T>, provided by the RelationExtension extension
Adds a WITH EXISTS aggregate for a relation.
withMax(String relation, String column, {String? alias, PredicateCallback<OrmEntity>? constraint}) → Query<T>: Available on Query<T>, provided by the RelationExtension extension
Adds a WITH MAX aggregate for a relation.
withMin(String relation, String column, {String? alias, PredicateCallback<OrmEntity>? constraint}) → Query<T>: Available on Query<T>, provided by the RelationExtension extension
Adds a WITH MIN aggregate for a relation.
withoutAutoHydration() → Query<T>: Disables auto-hydration columns for aggregate or projection-heavy queries.
withoutDistinct() → Query<T>: Available on Query<T>, provided by the DistinctExtension extension
Removes any previously applied DISTINCT state.
withoutEvents() → Query<T>: Returns a query that suppresses all model lifecycle events.
withoutGlobalScope(String scope) → Query<T>: Available on Query<T>, provided by the ScopeExtension extension
Removes a specific global scope from the query.
withoutGlobalScopes([List<String>? scopes]) → Query<T>: Available on Query<T>, provided by the ScopeExtension extension
Removes all global scopes from the query.
withRelation(String name, [PredicateCallback<OrmEntity>? constraint]) → Query<T>: Available on Query<T>, provided by the RelationExtension extension
Requests eager loading for the relation named name.
withRelationTyped<TRelated extends OrmEntity>(String name, [PredicateCallback<TRelated>? constraint]) → Query<T>: Available on Query<T>, provided by the RelationExtension extension
Typed variant of withRelation that accepts a typed predicate callback.
withSum(String relation, String column, {String? alias, PredicateCallback<OrmEntity>? constraint}) → Query<T>: Available on Query<T>, provided by the RelationExtension extension
Adds a WITH SUM aggregate for a relation.
withTrashed() → Query<T>: Available on Query<T>, provided by the SoftDeleteExtension extension
Includes soft-deleted models in the query results.

Operators

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

Query<T extends OrmEntity> class

Constructors

Properties

Methods

Operators

ormed library