QueryBuilder<T> class

Generic Query Builder.

Implemented types

• QueryBuilderInterface<T>

Constructors

QueryBuilder(DatabaseConnection connection, Grammar grammar, String table, {T modelFactory(Map<String, dynamic>)?})

Properties

bindings → List

no setter, override

columns → List

no setter, override

connection → DatabaseConnection

final

grammar → Grammar

final

hashCode → int

The hash code for this object.

no setter, inherited

modelFactory → T Function(Map<String, dynamic>)?

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

table → String

no setter, override

wheres → List<Map<String, dynamic>>

no setter

Methods

addSelect(List<String> columns) → QueryBuilderInterface<T>

Add more columns to select

override

asStream() → Stream<T>

Returns a stream of results for memory-efficient processing.

override

avg(String column) → Future<num>

Returns the average of a numeric column.

override

chunk(int size, Future<void> callback(List<T> items)) → Future<void>

Process results in chunks

override

chunkById(int size, Future<void> callback(List<T> items), {String column = 'id', String? alias}) → Future<void>

Process results in chunks by ID (more efficient for large datasets)

override

clone() → QueryBuilderInterface<T>

Clones the current query builder instance.

override

count() → Future<int>

Returns total count of matched rows.

override

crossJoin(String table) → QueryBuilderInterface<T>

CROSS JOIN

override

cursorPaginate({int perPage = 15, String? cursor, String column = 'id'}) → Future<Map<String, dynamic>>

Cursor-based pagination for efficient large dataset navigation

override

decrement(String column, [int amount = 1]) → Future<int>

Decrement a column value

override

delete() → Future<void>

Deletes rows matching where conditions.

override

distinct([bool distinct = true]) → QueryBuilderInterface<T>

SELECT DISTINCT

override

doesntHave(String relation) → QueryBuilderInterface<T>

Query without any of the relationship

override

exists() → Future<bool>

Returns true if any row matches the query.

override

find(dynamic id, [String column = 'id']) → Future<T?>

Find a record by its primary key.

override

findOrFail(dynamic id, [String column = 'id']) → Future<T>

Find a record by its primary key or throw an exception.

override

first() → Future<T?>

Returns the first row only.

override

forPage(int page, int perPage) → QueryBuilderInterface<T>

fromRaw(String sql, [List bindings = const []]) → QueryBuilderInterface<T>

Set raw SQL as the FROM clause

override

fromSub(QueryBuilderInterface query, String alias) → QueryBuilderInterface<T>

Set a subquery as the FROM clause

override

get() → Future<List<T>>

Executes and returns all matching rows.

override

groupBy(String column) → QueryBuilderInterface<T>

Adds GROUP BY clause.

override

has(String relation, [String operator = '>=', int count = 1]) → QueryBuilderInterface<T>

Query with relationship count

override

having(String column, String operator, dynamic value) → QueryBuilderInterface<T>

Adds HAVING clause.

override

increment(String column, [int amount = 1]) → Future<int>

Increment a column value

override

incrementEach(Map<String, int> columns, [Map<String, dynamic> extras = const {}]) → Future<void>

Increment multiple columns

override

inRandomOrder() → QueryBuilderInterface<T>

ORDER BY RAND()

override

insert(Map<String, dynamic> values) → Future<int>

Inserts a new row.

override

insertMany(List<Map<String, dynamic>> values) → Future<List<int>>

Insert multiple rows at once

override

join(String table, String first, String operator, String second, [String type = 'INNER']) → QueryBuilderInterface<T>

INNER JOIN

override

latest([String column = 'created_at']) → QueryBuilderInterface<T>

Shorthand for orderBy(column, 'DESC')

override

lazy([int chunkSize = 1000]) → Stream<T>

Lazy load results as a stream (alternative to asStream for chunking)

override

leftJoin(String table, String first, String operator, String second) → QueryBuilderInterface<T>

LEFT JOIN

override

limit(int count) → QueryBuilderInterface<T>

Limits the number of results.

override

lockForUpdate() → QueryBuilderInterface<T>

Add exclusive lock (FOR UPDATE) - prevents reads and updates

override

max(String column) → Future<int>

Returns the maximum value of a numeric column.

override

min(String column) → Future<int>

Returns the minimum value of a numeric column.

override

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

offset(int count) → QueryBuilderInterface<T>

Offsets the results (useful with pagination).

override

oldest([String column = 'created_at']) → QueryBuilderInterface<T>

Shorthand for orderBy(column, 'ASC')

override

orderBy(String column, {String direction = 'ASC'}) → QueryBuilderInterface<T>

Adds ORDER BY clause.

override

orderByRaw(String sql) → QueryBuilderInterface<T>

orHaving(String column, String operator, dynamic value) → QueryBuilderInterface<T>

Adds OR HAVING clause.

override

orWhere(String column, String operator, dynamic value) → QueryBuilderInterface<T>

Adds an OR WHERE clause.

override

orWhereBetween(String column, dynamic start, dynamic end) → QueryBuilderInterface<T>

OR WHERE column BETWEEN start AND end

override

orWhereColumn(String column1, String operator, String column2) → QueryBuilderInterface<T>

OR WHERE column1 operator column2

override

orWhereDate(String column, String date) → QueryBuilderInterface<T>

OR WHERE DATE(column) = date

override

orWhereDay(String column, int day) → QueryBuilderInterface<T>

OR WHERE DAY(column) = day

override

orWhereDoesntHave(String relation, [void callback(QueryBuilderInterface query)?]) → QueryBuilderInterface<T>

OR version of whereDoesntHave

override

orWhereExists(String callback(QueryBuilderInterface query)) → QueryBuilderInterface<T>

OR WHERE EXISTS (subquery)

override

orWhereHas(String relation, [void callback(QueryBuilderInterface query)?, String operator = '>=', int count = 1]) → QueryBuilderInterface<T>

OR version of whereHas

override

orWhereIn(String column, List values) → QueryBuilderInterface<T>

OR WHERE column IN (values)

override

orWhereJsonContains(String column, dynamic value, [String? path]) → QueryBuilderInterface<T>

OR WHERE JSON_CONTAINS

override

orWhereJsonContainsKey(String column, String path) → QueryBuilderInterface<T>

OR WHERE JSON_CONTAINS_PATH(column, 'one', path)

override

orWhereJsonDoesntContain(String column, dynamic value, [String? path]) → QueryBuilderInterface<T>

OR WHERE NOT JSON_CONTAINS(column, value, path)

override

orWhereJsonLength(String column, String operator, int length, [String? path]) → QueryBuilderInterface<T>

OR WHERE JSON_LENGTH(column, path) operator value

override

orWhereLike(String column, String pattern) → QueryBuilderInterface<T>

OR WHERE column LIKE pattern

override

orWhereMonth(String column, int month) → QueryBuilderInterface<T>

OR WHERE MONTH(column) = month

override

orWhereNested(void callback(QueryBuilderInterface<T> query)) → QueryBuilderInterface<T>

Add a nested OR WHERE clause group

override

orWhereNotBetween(String column, dynamic start, dynamic end) → QueryBuilderInterface<T>

OR WHERE column NOT BETWEEN start AND end

override

orWhereNotExists(String callback(QueryBuilderInterface query)) → QueryBuilderInterface<T>

OR WHERE NOT EXISTS (subquery)

override

orWhereNotIn(String column, List values) → QueryBuilderInterface<T>

OR WHERE column NOT IN (values)

override

orWhereNotLike(String column, String pattern) → QueryBuilderInterface<T>

OR WHERE column NOT LIKE pattern

override

orWhereNotNull(String column) → QueryBuilderInterface<T>

OR WHERE column IS NOT NULL

override

orWhereNull(String column) → QueryBuilderInterface<T>

OR WHERE column IS NULL

override

orWhereQuery(void callback(QueryBuilderInterface<T> query)) → QueryBuilderInterface<T>

Add a nested OR WHERE clause group (Alias for orWhereNested)

override

orWhereRaw(String sql, [List bindings = const []]) → QueryBuilderInterface<T>

Adds a raw SQL OR WHERE clause.

override

orWhereTime(String column, String time) → QueryBuilderInterface<T>

OR WHERE TIME(column) = time

override

orWhereYear(String column, int year) → QueryBuilderInterface<T>

OR WHERE YEAR(column) = year

override

paginate({int? page = 1, int? perPage = 15}) → Future<PaginatedResult<T>>

Returns a paginated result.

override

pluck(String column) → Future<List>

Returns a single column values as list.

override

rightJoin(String table, String first, String operator, String second) → QueryBuilderInterface<T>

RIGHT JOIN

override

select(List<String> columns) → QueryBuilderInterface<T>

Selects specific columns (defaults to *).

override

selectRaw(String sql, [List bindings = const []]) → QueryBuilderInterface<T>

override

selectSub(QueryBuilderInterface query, String alias) → QueryBuilderInterface<T>

Add a subquery to the SELECT clause

override

sharedLock() → QueryBuilderInterface<T>

Add shared lock (FOR SHARE) - prevents updates until transaction completes

override

simplePaginate({int perPage = 15, int page = 1}) → Future<Map<String, dynamic>>

Simple pagination without total count (faster)

override

skip(int count) → QueryBuilderInterface<T>

Alias for offset.

override

sum(String column) → Future<num>

Returns the sum of a numeric column.

override

take(int count) → QueryBuilderInterface<T>

Alias for limit.

override

toSql() → String

Returns the raw SQL string.

override

toString() → String

A string representation of this object.

inherited

union(QueryBuilderInterface<T> query) → QueryBuilderInterface<T>

UNION - combines results from two queries (removes duplicates)

override

unionAll(QueryBuilderInterface<T> query) → QueryBuilderInterface<T>

UNION ALL - combines results from two queries (keeps duplicates)

override

update(Map<String, dynamic> values) → Future<void>

Updates rows matching where conditions.

override

upsert(List<Map<String, dynamic>> values, {required List<String> uniqueBy, List<String>? update}) → Future<int>

Insert or update (UPSERT) - MySQL: INSERT ... ON DUPLICATE KEY UPDATE

override

when(bool condition, QueryBuilderInterface<T> builder(QueryBuilderInterface<T> q)) → QueryBuilderInterface<T>

Conditionally adds clauses based on condition.

override

where(String column, String operator, dynamic value) → QueryBuilderInterface<T>

Adds a basic WHERE clause.

override

whereAfterToday(String column) → QueryBuilderInterface<T>

WHERE column date is after today

override

whereAll(Map<String, dynamic> conditions) → QueryBuilderInterface<T>

Matches ALL of the conditions

override

whereAny(List<String> columns, String operator, dynamic value) → QueryBuilderInterface<T>

Matches ANY of the columns with the given operator and value

override

whereBeforeToday(String column) → QueryBuilderInterface<T>

WHERE column date is before today

override

whereBetween(String column, dynamic start, dynamic end) → QueryBuilderInterface<T>

WHERE column BETWEEN start AND end

override

whereBetweenColumns(String column, String startColumn, String endColumn) → QueryBuilderInterface<T>

WHERE column value is BETWEEN two other columns' values

override

whereColumn(String column1, String operator, String column2) → QueryBuilderInterface<T>

WHERE column1 operator column2 (compare two columns)

override

whereDate(String column, String date) → QueryBuilderInterface<T>

WHERE DATE(column) = date

override

whereDay(String column, int day) → QueryBuilderInterface<T>

WHERE DAY(column) = day

override

whereDoesntHave(String relation, [void callback(QueryBuilderInterface query)?]) → QueryBuilderInterface<T>

Query for absence of a relationship

override

whereExists(String callback(QueryBuilderInterface query)) → QueryBuilderInterface<T>

WHERE EXISTS (subquery)

override

whereFullText(List<String> columns, String searchTerm, {String mode = 'natural'}) → QueryBuilderInterface<T>

Full-text search using MySQL MATCH AGAINST

override

whereFuture(String column) → QueryBuilderInterface<T>

WHERE column is in the future

override

whereHas(String relation, [void callback(QueryBuilderInterface query)?, String operator = '>=', int count = 1]) → QueryBuilderInterface<T>

Query for existence of a relationship with optional constraints Equivalent to Laravel's whereHas()

override

whereIn(String column, List values) → QueryBuilderInterface<T>

WHERE column IN (values)

override

whereInSubquery(String column, String callback(QueryBuilderInterface query)) → QueryBuilderInterface<T>

WHERE column IN (subquery)

override

whereJsonContains(String column, dynamic value, [String? path]) → QueryBuilderInterface<T>

WHERE JSON_CONTAINS(column, value, path)

override

whereJsonContainsKey(String column, String path) → QueryBuilderInterface<T>

WHERE JSON_CONTAINS_PATH(column, 'one', path)

override

whereJsonDoesntContain(String column, dynamic value, [String? path]) → QueryBuilderInterface<T>

WHERE NOT JSON_CONTAINS(column, value, path)

override

whereJsonLength(String column, String operator, int length, [String? path]) → QueryBuilderInterface<T>

WHERE JSON_LENGTH(column, path) operator value

override

whereLike(String column, String pattern) → QueryBuilderInterface<T>

WHERE column LIKE pattern

override

whereMonth(String column, int month) → QueryBuilderInterface<T>

WHERE MONTH(column) = month

override

whereNested(void callback(QueryBuilderInterface<T> query)) → QueryBuilderInterface<T>

Add a nested WHERE clause group

override

whereNone(Map<String, dynamic> conditions) → QueryBuilderInterface<T>

Matches NONE of the conditions

override

whereNotBetween(String column, dynamic start, dynamic end) → QueryBuilderInterface<T>

WHERE column NOT BETWEEN start AND end

override

whereNotBetweenColumns(String column, String startColumn, String endColumn) → QueryBuilderInterface<T>

WHERE column value is NOT BETWEEN two other columns' values

override

whereNotExists(String callback(QueryBuilderInterface query)) → QueryBuilderInterface<T>

WHERE NOT EXISTS (subquery)

override

whereNotIn(String column, List values) → QueryBuilderInterface<T>

WHERE column NOT IN (values)

override

whereNotLike(String column, String pattern) → QueryBuilderInterface<T>

WHERE column NOT LIKE pattern

override

whereNotNull(String column) → QueryBuilderInterface<T>

WHERE column IS NOT NULL

override

whereNull(String column) → QueryBuilderInterface<T>

WHERE column IS NULL

override

wherePast(String column) → QueryBuilderInterface<T>

WHERE column is in the past

override

whereQuery(void callback(QueryBuilderInterface<T> query)) → QueryBuilderInterface<T>

Add a nested WHERE clause group (Alias for whereNested)

override

whereRaw(String sql, [List bindings = const [], String boolean = 'AND']) → QueryBuilderInterface<T>

Adds a raw SQL WHERE clause.

override

whereTime(String column, String time) → QueryBuilderInterface<T>

WHERE TIME(column) = time

override

whereToday(String column) → QueryBuilderInterface<T>

WHERE column date is today

override

whereYear(String column, int year) → QueryBuilderInterface<T>

WHERE YEAR(column) = year

override

withAvg(String relation, String column) → QueryBuilderInterface<T>

Load relationship average aggregates without loading the full relationships.

override

withCount(dynamic relations) → QueryBuilderInterface<T>

Load relationship counts without loading the full relationships.

override

withMax(String relation, String column) → QueryBuilderInterface<T>

Load relationship maximum aggregates without loading the full relationships.

override

withMin(String relation, String column) → QueryBuilderInterface<T>

Load relationship minimum aggregates without loading the full relationships.

override

withOnly(List<String> relations) → QueryBuilderInterface<T>

Replaces the model's defaultRelations with the specified list.

override

without(List<String> relations) → QueryBuilderInterface<T>

Excludes specific relations from the model's defaultRelations.

override

withRelations(List relations) → QueryBuilderInterface<T>

Eagerly loads relations for the query.

override

withSum(String relation, String column) → QueryBuilderInterface<T>

Load relationship sum aggregates without loading the full relationships.

override

Operators

operator ==(Object other) → bool

The equality operator.

inherited