Documentation

Query extends Query
in package

Query represents a SELECT SQL statement in a way that is independent of DBMS.

Query provides a set of methods to facilitate the specification of different clauses in a SELECT statement. These methods can be chained together.

By calling [[createCommand()]], we can get a [[Command]] instance which can be further used to perform/execute the DB query against a database.

Table of Contents

batch()  : BatchQueryResult
Starts a batch query.
createCommand()  : Command
Creates a DB command that can be used to execute this query.
each()  : BatchQueryResult
Starts a batch query and retrieves data row by row.
one()  : array<string|int, mixed>|bool
Executes the query and returns a single row of result.
scalar()  : string|false|null
Returns the query result as a scalar value.
queryScalar()  : bool|string
Queries a scalar value by setting [[select]] first.

Methods

batch()

Starts a batch query.

public batch([int $batchSize = 100 ][, Db $db = null ]) : BatchQueryResult

A batch query supports fetching data in batches, which can keep the memory usage under a limit. This method will return a [[BatchQueryResult]] object which implements the [[\Iterator]] interface and can be traversed to retrieve the data in batches.

Parameters
$batchSize : int = 100

the number of records to be fetched in each batch.

$db : Db = null

the database connection. If not set, the "db" application component will be used.

Return values
BatchQueryResult

the batch query result. It implements the [[\Iterator]] interface and can be traversed to retrieve the data in batches.

createCommand()

Creates a DB command that can be used to execute this query.

public createCommand([Db $db = null ]) : Command
Parameters
$db : Db = null

the database connection used to generate the SQL statement. If this parameter is not given, the db application component will be used.

Return values
Command

the created DB command instance.

each()

Starts a batch query and retrieves data row by row.

public each([int $batchSize = 100 ][, Db $db = null ]) : BatchQueryResult

This method is similar to [[batch()]] except that in each iteration of the result, only one row of data is returned. For example,

Parameters
$batchSize : int = 100

the number of records to be fetched in each batch.

$db : Db = null

the database connection. If not set, the "db" application component will be used.

Return values
BatchQueryResult

the batch query result. It implements the [[\Iterator]] interface and can be traversed to retrieve the data in batches.

one()

Executes the query and returns a single row of result.

public one([Db $db = null ]) : array<string|int, mixed>|bool
Parameters
$db : Db = null

the database connection used to generate the SQL statement. If this parameter is not given, the db application component will be used.

Return values
array<string|int, mixed>|bool

the first row (in terms of an array) of the query result. False is returned if the query results in nothing.

scalar()

Returns the query result as a scalar value.

public scalar([Db $db = null ]) : string|false|null

The value returned will be the first column in the first row of the query results.

Parameters
$db : Db = null

the database connection used to generate the SQL statement. If this parameter is not given, the db application component will be used.

Return values
string|false|null

the value of the first column in the first row of the query result. False is returned if the query result is empty.

queryScalar()

Queries a scalar value by setting [[select]] first.

protected queryScalar(string|ExpressionInterface $selectExpression, Db|null $db) : bool|string

Restores the value of select to make this query reusable.

Parameters
$selectExpression : string|ExpressionInterface
$db : Db|null
Return values
bool|string

Search results