QueryBuilder<T> class

Fluent, parameterized SQL builder. T is what rows hydrate into: a model when built from a ModelDefinition, or a Row map from DB.table().

Every value goes to the driver as a bound parameter. Table and column names are validated as identifiers; trusted fragments go through RawSql.

Available extensions

Constructors

QueryBuilder(Connection connection, String table, {required T hydrate(Row row), ModelDefinition<T>? definition})

Properties

columns → List<Object>
final
connection ↔ Connection
getter/setter pair
definition → ModelDefinition<T>?
final
eagerLoads → Map<String, RelationConstraint?>
final
fromClause → String
The FROM target, table as alias when aliased.
no setter
grammar → Grammar
no setter
groups → List<String>
final
hashCode → int
The hash code for this object.
no setterinherited
havings → List<WhereClause>
final
isDistinct ↔ bool
getter/setter pair
joins → List<JoinClause>
final
limitValue ↔ int?
getter/setter pair
offsetValue ↔ int?
getter/setter pair
orders → List<OrderClause>
final
qualifier → String
What column references in this query qualify against: the table, or its alias when whereHas had to alias it.
no setter
removedScopes → Set<String>
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
table → String
final
wheres → List<WhereClause>
final

Methods

addSelect(List<Object> selected) → QueryBuilder<T>
applyScopes() → QueryBuilder<T>
Applies global scopes once. Called on a clone before compiling.
avg(String column) → Future<num?>
chunk(int size, FutureOr<bool?> callback(List<T> rows)) → Future<void>
Processes the table in pages of size; return false from callback to stop early. Ordered by primary key unless you ordered.
clone() → QueryBuilder<T>
A deep copy; the original is untouched by later calls on the copy.
compile() → Compiled
count([String column = '*']) → Future<int>
create(Map<String, Object?> attributes) → Future<T>
Mass-assign and insert; fires model events. Model queries only.
crossJoin(String table) → QueryBuilder<T>
decrement(String column, [num amount = 1, Map<String, Object?> extra = const {}]) → Future<int>
delete([Object? id]) → Future<int>
Deletes matching rows, or soft-deletes them when the model uses soft deletes. Returns affected rows.
distinct([bool value = true]) → QueryBuilder<T>
doesntExist() → Future<bool>
exists() → Future<bool>
find(Object id) → Future<T?>
findMany(Iterable<Object> ids) → Future<List<T>>
findOrFail(Object id) → Future<T>
first() → Future<T?>
firstOrCreate(Map<String, Object?> match, [Map<String, Object?> extra = const {}]) → Future<T>
firstOrFail() → Future<T>
firstOrNull() → Future<T?>
forceCreate(Map<String, Object?> attributes) → Future<T>
forceDelete() → Future<int>
Deletes matching rows for real, even with soft deletes.
forPage(int page, int perPage) → QueryBuilder<T>
get() → Future<List<T>>
groupBy(List<String> columnNames) → QueryBuilder<T>
has(String relation) → QueryBuilder<T>
having(Object column, Object operatorOrValue, [Object? value = _absent]) → QueryBuilder<T>
havingRaw(String sql, [List<Object?> bindings = const []]) → QueryBuilder<T>
includes(Request request, {required List<String> allow, int maxDepth = 2}) → QueryBuilder<T>

Available on QueryBuilder<T>, provided by the RequestIncludes extension

Eager loads the relations named by ?include=posts,posts.comments, restricted to allow and to maxDepth levels.
increment(String column, [num amount = 1, Map<String, Object?> extra = const {}]) → Future<int>
insert(Object rows) → Future<int>
Inserts one map or a list of maps. Returns the number of rows.
insertGetId(Map<String, Object?> row) → Future<Object?>
join(String table, String first, [String operator = '=', String? second, String type = 'inner']) → QueryBuilder<T>
latest([String? column]) → QueryBuilder<T>
lazy({int chunkSize = 100}) → Stream<T>
Streams rows one at a time, fetching chunkSize per query.
leftJoin(String table, String first, [String operator = '=', String? second]) → QueryBuilder<T>
limit(int value) → QueryBuilder<T>
max(String column) → Future<Object?>
min(String column) → Future<Object?>
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
offset(int value) → QueryBuilder<T>
oldest([String? column]) → QueryBuilder<T>
onlyTrashed() → QueryBuilder<T>
Soft deletes: only trashed rows.
orderBy(String column, {bool descending = false}) → QueryBuilder<T>
Direction is a boolean, never a string from the request.
orderByDesc(String column) → QueryBuilder<T>
orderByRaw(String sql, [List<Object?> bindings = const []]) → QueryBuilder<T>
orWhere(Object column, [Object? operatorOrValue = _absent, Object? value = _absent]) → QueryBuilder<T>
orWhereHas(String relation, [RelationConstraint? constraint]) → QueryBuilder<T>
orWhereIn(String column, Object values) → QueryBuilder<T>
orWhereLike(String column, String pattern, {bool caseInsensitive = false}) → QueryBuilder<T>
orWhereNotIn(String column, Object values) → QueryBuilder<T>
orWhereNotNull(String column) → QueryBuilder<T>
orWhereNull(String column) → QueryBuilder<T>
orWhereRaw(String sql, [List<Object?> bindings = const []]) → QueryBuilder<T>
paginate({int page = 1, int perPage = 15}) → Future<Paginator<T>>
paginateRequest(Request request, {int? perPage}) → Future<Paginator<T>>

Available on QueryBuilder<T>, provided by the RequestPagination extension

paginateRequest(request) — reads ?page= and ?per_page= and delegates to seshat's paginate({page, perPage}).
pluck(String column, [String? key]) → Future<Object>
One column as a list, or a {key: value} map when key is given.
pluckList(String column) → Future<List<Object?>>
prepared() → QueryBuilder<T>
A scoped copy ready to compile.
reorder() → QueryBuilder<T>
restore() → Future<int>
Soft deletes: un-trash matching rows.
rightJoin(String table, String first, [String operator = '=', String? second]) → QueryBuilder<T>
select(List<Object> selected) → QueryBuilder<T>
selectRaw(String sql, [List<Object?> bindings = const []]) → QueryBuilder<T>
skip(int value) → QueryBuilder<T>
sum(String column) → Future<num?>
take(int value) → QueryBuilder<T>
toSql() → String
The SELECT this builder would run, with ? placeholders.
toString() → String
A string representation of this object.
inherited
truncate() → Future<void>
update(Map<String, Object?> values) → Future<int>
Bulk update of every row matching the query. Returns affected rows.
updateOrCreate(Map<String, Object?> match, Map<String, Object?> values) → Future<T>
using(Connection other) → QueryBuilder<T>
Run this query (and any query derived from it) on other; used for transactions: User.query().using(tx).
value(String column) → Future<Object?>
A single column of the first row.
where(Object column, [Object? operatorOrValue = _absent, Object? value = _absent]) → QueryBuilder<T>
where('age', '>', 18), where('active', true), where('x', null) (becomes is null), or where((q) => q.where(..).orWhere(..)).
whereBetween(String column, Object? low, Object? high) → QueryBuilder<T>
whereColumn(String first, String operatorOrSecond, [String? second]) → QueryBuilder<T>
Compare two columns: whereColumn('updated_at', '>', 'created_at').
whereDoesntHave(String relation, [RelationConstraint? constraint]) → QueryBuilder<T>
whereExists(QueryBuilder<Object?> query, {bool not = false}) → QueryBuilder<T>
whereHas(String relation, [RelationConstraint? constraint]) → QueryBuilder<T>
whereHas('posts', (q) => q.where('published', true)).
whereIn(String column, Object values) → QueryBuilder<T>
whereIn('id', [1, 2]) or whereIn('id', subquery).
whereKey(Object id) → QueryBuilder<T>
where primaryKey = id (or in for a list of ids).
whereLike(String column, String pattern, {bool caseInsensitive = false}) → QueryBuilder<T>
like with the pattern bound as a parameter. On PostgreSQL like is case-sensitive; pass caseInsensitive: true for ilike.
whereNot(Object column, Object? value) → QueryBuilder<T>
whereNotBetween(String column, Object? low, Object? high) → QueryBuilder<T>
whereNotExists(QueryBuilder<Object?> query) → QueryBuilder<T>
whereNotIn(String column, Object values) → QueryBuilder<T>
whereNotLike(String column, String pattern) → QueryBuilder<T>
whereNotNull(String column) → QueryBuilder<T>
whereNull(String column) → QueryBuilder<T>
whereRaw(String sql, [List<Object?> bindings = const []]) → QueryBuilder<T>
Trusted SQL. Never interpolate user input into sql; bind it.
with_(List<String> relations) → QueryBuilder<T>
Eager load relations: with_(['posts', 'posts.comments']).
withoutGlobalScope(String name) → QueryBuilder<T>
withoutGlobalScopes() → QueryBuilder<T>
withTrashed() → QueryBuilder<T>
Soft deletes: include trashed rows.
withWhere(String relation, RelationConstraint constraint) → QueryBuilder<T>
Eager load with extra constraints on the related query.

Operators

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