QueryBuilderInterface<T> class abstract

A generic interface for building SQL-like queries dynamically. Supports both raw Map responses or strongly-typed KhademModel instances.

Example usage:

final users = await UserModel.q<UserModel>()
  .where('active', '=', true)
  .orderBy('created_at', direction: 'DESC')
  .limit(10)
  .get();

Implementers

• QueryBuilder

Constructors

QueryBuilderInterface()

Properties

bindings → List

no setter

columns → List

no setter

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

table → String

no setter

Methods

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

Add more columns to select

asStream() → Stream<T>

Returns a stream of results for memory-efficient processing.

avg(String column) → Future<num>

Returns the average of a numeric column.

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

Process results in chunks

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)

clone() → QueryBuilderInterface<T>

Clones the current query builder instance.

count() → Future<int>

Returns total count of matched rows.

crossJoin(String table) → QueryBuilderInterface<T>

CROSS JOIN

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

Cursor-based pagination for efficient large dataset navigation

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

Decrement a column value

delete() → Future<void>

Deletes rows matching where conditions.

distinct() → QueryBuilderInterface<T>

SELECT DISTINCT

doesntHave(String relation) → QueryBuilderInterface<T>

Query without any of the relationship

exists() → Future<bool>

Returns true if any row matches the query.

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

Find a record by its primary key.

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

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

first() → Future<T?>

Returns the first row only.

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

Set raw SQL as the FROM clause

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

Set a subquery as the FROM clause

get() → Future<List<T>>

Executes and returns all matching rows.

groupBy(String column) → QueryBuilderInterface<T>

Adds GROUP BY clause.

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

Query with relationship count

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

Adds HAVING clause.

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

Increment a column value

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

Increment multiple columns

inRandomOrder() → QueryBuilderInterface<T>

ORDER BY RAND()

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

Inserts a new row.

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

Insert multiple rows at once

join(String table, String firstColumn, String operator, String secondColumn) → QueryBuilderInterface<T>

INNER JOIN

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

Shorthand for orderBy(column, 'DESC')

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

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

leftJoin(String table, String firstColumn, String operator, String secondColumn) → QueryBuilderInterface<T>

LEFT JOIN

limit(int number) → QueryBuilderInterface<T>

Limits the number of results.

lockForUpdate() → QueryBuilderInterface<T>

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

max(String column) → Future<int>

Returns the maximum value of a numeric column.

min(String column) → Future<int>

Returns the minimum value of a numeric column.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

offset(int number) → QueryBuilderInterface<T>

Offsets the results (useful with pagination).

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

Shorthand for orderBy(column, 'ASC')

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

Adds ORDER BY clause.

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

Adds OR HAVING clause.

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

Adds an OR WHERE clause.

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

OR WHERE column BETWEEN start AND end

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

OR WHERE column1 operator column2

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

OR WHERE DATE(column) = date

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

OR WHERE DAY(column) = day

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

OR version of whereDoesntHave

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

OR WHERE EXISTS (subquery)

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

OR version of whereHas

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

OR WHERE column IN (values)

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

OR WHERE JSON_CONTAINS

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

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

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

OR WHERE NOT JSON_CONTAINS(column, value, path)

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

OR WHERE JSON_LENGTH(column, path) operator value

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

OR WHERE column LIKE pattern

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

OR WHERE MONTH(column) = month

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

Add a nested OR WHERE clause group

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

OR WHERE column NOT BETWEEN start AND end

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

OR WHERE NOT EXISTS (subquery)

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

OR WHERE column NOT IN (values)

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

OR WHERE column NOT LIKE pattern

orWhereNotNull(String column) → QueryBuilderInterface<T>

OR WHERE column IS NOT NULL

orWhereNull(String column) → QueryBuilderInterface<T>

OR WHERE column IS NULL

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

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

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

Adds a raw SQL OR WHERE clause.

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

OR WHERE TIME(column) = time

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

OR WHERE YEAR(column) = year

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

Returns a paginated result.

pluck(String column) → Future<List>

Returns a single column values as list.

rightJoin(String table, String firstColumn, String operator, String secondColumn) → QueryBuilderInterface<T>

RIGHT JOIN

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

Selects specific columns (defaults to *).

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

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

Add a subquery to the SELECT clause

sharedLock() → QueryBuilderInterface<T>

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

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

Simple pagination without total count (faster)

skip(int number) → QueryBuilderInterface<T>

Alias for offset.

sum(String column) → Future<num>

Returns the sum of a numeric column.

take(int number) → QueryBuilderInterface<T>

Alias for limit.

toSql() → String

Returns the raw SQL string.

toString() → String

A string representation of this object.

inherited

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

UNION - combines results from two queries (removes duplicates)

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

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

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

Updates rows matching where conditions.

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

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

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

Conditionally adds clauses based on condition.

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

Adds a basic WHERE clause.

whereAfterToday(String column) → QueryBuilderInterface<T>

WHERE column date is after today

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

Matches ALL of the conditions

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

Matches ANY of the columns with the given operator and value

whereBeforeToday(String column) → QueryBuilderInterface<T>

WHERE column date is before today

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

WHERE column BETWEEN start AND end

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

WHERE column value is BETWEEN two other columns' values

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

WHERE column1 operator column2 (compare two columns)

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

WHERE DATE(column) = date

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

WHERE DAY(column) = day

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

Query for absence of a relationship

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

WHERE EXISTS (subquery)

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

Full-text search using MySQL MATCH AGAINST

whereFuture(String column) → QueryBuilderInterface<T>

WHERE column is in the future

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()

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

WHERE column IN (values)

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

WHERE column IN (subquery)

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

WHERE JSON_CONTAINS(column, value, path)

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

WHERE JSON_CONTAINS_PATH(column, 'one', path)

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

WHERE NOT JSON_CONTAINS(column, value, path)

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

WHERE JSON_LENGTH(column, path) operator value

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

WHERE column LIKE pattern

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

WHERE MONTH(column) = month

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

Add a nested WHERE clause group

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

Matches NONE of the conditions

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

WHERE column NOT BETWEEN start AND end

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

WHERE column value is NOT BETWEEN two other columns' values

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

WHERE NOT EXISTS (subquery)

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

WHERE column NOT IN (values)

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

WHERE column NOT LIKE pattern

whereNotNull(String column) → QueryBuilderInterface<T>

WHERE column IS NOT NULL

whereNull(String column) → QueryBuilderInterface<T>

WHERE column IS NULL

wherePast(String column) → QueryBuilderInterface<T>

WHERE column is in the past

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

Add a nested WHERE clause group (Alias for whereNested)

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

Adds a raw SQL WHERE clause.

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

WHERE TIME(column) = time

whereToday(String column) → QueryBuilderInterface<T>

WHERE column date is today

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

WHERE YEAR(column) = year

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

Load relationship average aggregates without loading the full relationships.

withCount(dynamic relations) → QueryBuilderInterface<T>

Load relationship counts without loading the full relationships.

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

Load relationship maximum aggregates without loading the full relationships.

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

Load relationship minimum aggregates without loading the full relationships.

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

Replaces the model's defaultRelations with the specified list.

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

Excludes specific relations from the model's defaultRelations.

withRelations(List relations) → QueryBuilderInterface<T>

Eagerly loads relations for the query.

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

Load relationship sum aggregates without loading the full relationships.

Operators

operator ==(Object other) → bool

The equality operator.

inherited