Query

Type

Class

Namespace

craft\db

Inherits

craft\db\Query » yii\db\Query (opens new window) » yii\base\Component (opens new window) » yii\base\BaseObject (opens new window)

Implements

yii\base\Configurable (opens new window), yii\db\ExpressionInterface (opens new window), yii\db\QueryInterface (opens new window)

Uses traits

craft\base\ClonefixTrait, yii\db\QueryTrait (opens new window)

Extended by

craft\elements\db\AssetQuery, craft\elements\db\CategoryQuery, craft\elements\db\ElementQuery, craft\elements\db\EntryQuery, craft\elements\db\GlobalSetQuery, craft\elements\db\MatrixBlockQuery, craft\elements\db\TagQuery, craft\elements\db\UserQuery, craft\test\mockclasses\elements\MockElementQuery

Since

3.0.0

Class Query

View source (opens new window)

Public Properties

Property	Description
behaviors (opens new window)	yii\base\Behavior (opens new window) – List of behaviors attached to this component.
distinct (opens new window)	boolean (opens new window) – Whether to select distinct rows of data only.
emulateExecution (opens new window)	boolean (opens new window) – Whether to emulate the actual query execution, returning empty or false results.
from (opens new window)	array (opens new window), null (opens new window) – The table(s) to be selected from.
groupBy (opens new window)	array (opens new window), null (opens new window) – How to group the query results.
having (opens new window)	string (opens new window), array (opens new window), yii\db\ExpressionInterface (opens new window), null (opens new window) – The condition to be applied in the GROUP BY clause.
indexBy (opens new window)	string (opens new window), callable (opens new window), null (opens new window) – The name of the column by which the query results should be indexed by.
join (opens new window)	array (opens new window), null (opens new window) – How to join with other tables.
limit (opens new window)	integer (opens new window), yii\db\ExpressionInterface (opens new window), null (opens new window) – Maximum number of records to be returned.
offset (opens new window)	integer (opens new window), yii\db\ExpressionInterface (opens new window), null (opens new window) – Zero-based offset from where the records are to be returned.
orderBy (opens new window)	array (opens new window), null (opens new window) – How to sort the query results.
params (opens new window)	array (opens new window), null (opens new window) – List of query parameter values indexed by parameter placeholders.
queryCacheDependency (opens new window)	yii\caching\Dependency (opens new window), null (opens new window) – The dependency to be associated with the cached query result for this query
queryCacheDuration (opens new window)	integer (opens new window), boolean (opens new window), null (opens new window) – The default number of seconds that query results can remain valid in cache.
rawSql	string (opens new window)
select (opens new window)	array (opens new window), null (opens new window) – The columns being selected.
selectOption (opens new window)	string (opens new window), null (opens new window) – Additional option that should be appended to the 'SELECT' keyword.
tablesUsedInFrom (opens new window)	string (opens new window)[] – Table names indexed by aliases.
union (opens new window)	array (opens new window), null (opens new window) – This is used to construct the UNION clause(s) in a SQL statement.
where (opens new window)	string (opens new window), array (opens new window), yii\db\ExpressionInterface (opens new window), null (opens new window) – Query condition.
withQueries (opens new window)	array (opens new window), null (opens new window) – This is used to construct the WITH section in a SQL query.

rawSql

Type

string (opens new window)

Default value

null

Access

Read-only

View source (opens new window)

Public Methods

Method	Description
__call() (opens new window)	Calls the named method which is not a class method.
__clone()
__construct() (opens new window)	Constructor.
__get() (opens new window)	Returns the value of a component property.
__isset() (opens new window)	Checks if a property is set, i.e. defined and not null.
__set() (opens new window)	Sets the value of a component property.
__toString() (opens new window)	Returns the SQL representation of Query
__unset() (opens new window)	Sets a component property to be null.
addGroupBy() (opens new window)	Adds additional group-by columns to the existing ones.
addOrderBy() (opens new window)	Adds additional ORDER BY columns to the query.
addParams() (opens new window)	Adds additional parameters to be bound to the query.
addSelect() (opens new window)	Add more columns to the SELECT part of the query.
all()	Executes the query and returns all results as an array.
andFilterCompare() (opens new window)	Adds a filtering condition for a specific column and allow the user to choose a filter operator.
andFilterHaving() (opens new window)	Adds an additional HAVING condition to the existing one but ignores empty operands (opens new window).
andFilterWhere() (opens new window)	Adds an additional WHERE condition to the existing one but ignores empty operands (opens new window).
andHaving() (opens new window)	Adds an additional HAVING condition to the existing one.
andWhere()	Adds an additional WHERE condition to the existing one.
attachBehavior() (opens new window)	Attaches a behavior to this component.
attachBehaviors() (opens new window)	Attaches a list of behaviors to the component.
average() (opens new window)	Returns the average of the specified column values.
batch() (opens new window)	Starts a batch query.
behaviors()	Returns a list of behaviors that this component should behave as.
cache() (opens new window)	Enables query cache for this Query.
canGetProperty() (opens new window)	Returns a value indicating whether a property can be read.
canSetProperty() (opens new window)	Returns a value indicating whether a property can be set.
className() (opens new window)	Returns the fully qualified name of this class.
column()	Executes the query and returns the first column of the result.
count() (opens new window)	Returns the number of records.
create() (opens new window)	Creates a new Query object and copies its property values from an existing one.
createCommand() (opens new window)	Creates a DB command that can be used to execute this query.
detachBehavior() (opens new window)	Detaches a behavior from the component.
detachBehaviors() (opens new window)	Detaches all behaviors from the component.
distinct() (opens new window)	Sets the value indicating whether to SELECT DISTINCT or not.
each() (opens new window)	Starts a batch query and retrieves data row by row.
emulateExecution() (opens new window)	Sets whether to emulate query execution, preventing any interaction with data storage.
ensureBehaviors() (opens new window)	Makes sure that the behaviors declared in behaviors() (opens new window) are attached to this component.
exists()	Returns a value indicating whether the query result contains any row of data.
filterHaving() (opens new window)	Sets the HAVING part of the query but ignores empty operands (opens new window).
filterWhere() (opens new window)	Sets the WHERE part of the query but ignores empty operands (opens new window).
from() (opens new window)	Sets the FROM part of the query.
getBehavior() (opens new window)	Returns the named behavior object.
getBehaviors() (opens new window)	Returns all behaviors attached to this component.
getRawSql()	Shortcut for createCommand()->getRawSql().
getTablesUsedInFrom() (opens new window)	Returns table names used in from() (opens new window) indexed by aliases.
groupBy() (opens new window)	Sets the GROUP BY part of the query.
hasEventHandlers() (opens new window)	Returns a value indicating whether there is any handler attached to the named event.
hasMethod() (opens new window)	Returns a value indicating whether a method is defined.
hasProperty() (opens new window)	Returns a value indicating whether a property is defined for this component.
having() (opens new window)	Sets the HAVING part of the query.
indexBy() (opens new window)	Sets the indexBy() (opens new window) property.
init()	Initializes the object.
innerJoin() (opens new window)	Appends an INNER JOIN part to the query.
isJoined()	Returns whether a given table has been joined in this query.
join() (opens new window)	Appends a JOIN part to the query.
leftJoin() (opens new window)	Appends a LEFT OUTER JOIN part to the query.
limit() (opens new window)	Determines the number of {elements} that should be returned.
max() (opens new window)	Returns the maximum of the specified column values.
min() (opens new window)	Returns the minimum of the specified column values.
noCache() (opens new window)	Disables query cache for this Query.
nth()	Executes the query and returns a single row of result at a given offset.
off() (opens new window)	Detaches an existing event handler from this component.
offset() (opens new window)	Determines how many {elements} should be skipped in the results.
on() (opens new window)	Attaches an event handler to an event.
one()	Executes the query and returns a single row of result.
orFilterHaving() (opens new window)	Adds an additional HAVING condition to the existing one but ignores empty operands (opens new window).
orFilterWhere() (opens new window)	Adds an additional WHERE condition to the existing one but ignores empty operands (opens new window).
orHaving() (opens new window)	Adds an additional HAVING condition to the existing one.
orWhere()	Adds an additional WHERE condition to the existing one.
orderBy() (opens new window)	Determines the order that the {elements} should be returned in. (If empty, defaults to {default-order-by}.)
pairs()	Executes the query and returns the first two columns in the results as key/value pairs.
params() (opens new window)	Sets the parameters to be bound to the query.
populate() (opens new window)	Converts the raw query results into the format as specified by this query.
prepare() (opens new window)	Prepares for building SQL.
rightJoin() (opens new window)	Appends a RIGHT OUTER JOIN part to the query.
scalar()	Returns the query result as a scalar value.
select() (opens new window)	Sets the SELECT part of the query.
sum() (opens new window)	Returns the sum of the specified column values.
trigger() (opens new window)	Triggers an event.
union() (opens new window)	Appends a SQL statement using UNION operator.
where()	Sets the WHERE part of the query.
withQuery() (opens new window)	Prepends a SQL statement using WITH syntax.

all()

Executes the query and returns all results as an array.

View source (opens new window)

Arguments

• $db (yii\db\Connection (opens new window), null (opens new window)) – The database connection used to generate the SQL statement. If this parameter is not given, the db application component will be used.

Returns

array (opens new window) – The query results. If the query results in nothing, an empty array will be returned.

andWhere()

Adds an additional WHERE condition to the existing one.

The new condition and the existing one will be joined using the AND operator.

View source (opens new window)

Arguments

• $condition (string (opens new window), array (opens new window), yii\db\ExpressionInterface (opens new window)) – The new WHERE condition. Please refer to where() on how to specify this parameter.
• $params (array (opens new window)) – The parameters (name => value) to be bound to the query.

Returns

$this – The query object itself

behaviors()

Returns a list of behaviors that this component should behave as.

Child classes may override this method to specify the behaviors they want to behave as.

The return value of this method should be an array of behavior objects or configurations indexed by behavior names. A behavior configuration can be either a string specifying the behavior class or an array of the following structure:

'behaviorName' => [
    'class' => 'BehaviorClass',
    'property1' => 'value1',
    'property2' => 'value2',
]

Note that a behavior class must extend from \craft\db\Behavior. Behaviors can be attached using a name or anonymously. When a name is used as the array key, using this name, the behavior can later be retrieved using getBehavior() (opens new window) or be detached using detachBehavior() (opens new window). Anonymous behaviors can not be retrieved or detached.

Behaviors declared in this method will be attached to the component automatically (on demand).

View source (opens new window)

Returns

array (opens new window) – The behavior configurations.

column()

Executes the query and returns the first column of the result.

View source (opens new window)

Arguments

• $db (yii\db\Connection (opens new window), null (opens new window)) – The database connection used to generate the SQL statement. If this parameter is not given, the db application component will be used.

Returns

array (opens new window) – The first column of the query result. An empty array is returned if the query results in nothing.

exists()

Returns a value indicating whether the query result contains any row of data.

View source (opens new window)

Arguments

• $db (yii\db\Connection (opens new window), null (opens new window)) – The database connection used to generate the SQL statement. If this parameter is not given, the db application component will be used.

Returns

boolean (opens new window) – Whether the query result contains any row of data.

getRawSql()

Shortcut for createCommand()->getRawSql().

See also:

• createCommand() (opens new window)
• yii\db\Command::getRawSql() (opens new window)

View source (opens new window)

Arguments

• $db (yii\db\Connection (opens new window), null (opens new window)) – The database connection used to generate the SQL statement. If this parameter is not given, the db application component will be used.

Returns

string (opens new window)

init()

Initializes the object.

This method is invoked at the end of the constructor after the object is initialized with the given configuration.

View source (opens new window)

isJoined()

Returns whether a given table has been joined in this query.

View source (opens new window)

Arguments

• $table (string (opens new window))

Returns

boolean (opens new window)

nth()

Executes the query and returns a single row of result at a given offset.

View source (opens new window)

Arguments

• $n (integer (opens new window)) – The offset of the row to return. If offset() (opens new window) is set, $offset will be added to it.
• $db (yii\db\Connection (opens new window), null (opens new window)) – The database connection used to generate the SQL statement. If this parameter is not given, the db application component will be used.

Returns

array (opens new window), null (opens new window) – The row (in terms of an array) of the query result. Null is returned if the query results in nothing.

one()

Executes the query and returns a single row of result.

View source (opens new window)

Arguments

• $db (yii\db\Connection (opens new window), null (opens new window)) – The database connection used to generate the SQL statement. If this parameter is not given, the db application component will be used.

Returns

mixed, null (opens new window) – First row of the query result array, or null if there are no query results.

orWhere()

Adds an additional WHERE condition to the existing one.

The new condition and the existing one will be joined using the OR operator.

View source (opens new window)

Arguments

• $condition (string (opens new window), array (opens new window), yii\db\ExpressionInterface (opens new window)) – The new WHERE condition. Please refer to where() on how to specify this parameter.
• $params (array (opens new window)) – The parameters (name => value) to be bound to the query.

Returns

$this – The query object itself

pairs()

Executes the query and returns the first two columns in the results as key/value pairs.

View source (opens new window)

Arguments

• $db (yii\db\Connection (opens new window), null (opens new window)) – The database connection used to execute the query. If this parameter is not given, the db application component will be used.

Returns

array (opens new window) – The query results. If the query results in nothing, an empty array will be returned.

Throws

• yii\base\Exception (opens new window)
  if less than two columns were selected

scalar()

Returns the query result as a scalar value.

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

View source (opens new window)

Arguments

• $db (yii\db\Connection (opens new window), null (opens new window)) – The database connection used to generate the SQL statement. If this parameter is not given, the db application component will be used.

Returns

string (opens new window), integer (opens new window), null (opens new window), false (opens new window) – The value of the first column in the first row of the query result. False is returned if the query result is empty.

where()

Sets the WHERE part of the query.

The method requires a $condition parameter, and optionally a $params parameter specifying the values to be bound to the query.

The $condition parameter should be either a string (e.g. 'id=1') or an array.

{@inheritdoc}

View source (opens new window)

Arguments

• $condition (string (opens new window), array (opens new window), yii\db\ExpressionInterface (opens new window)) – The conditions that should be put in the WHERE part.
• $params (array (opens new window)) – The parameters (name => value) to be bound to the query.

Returns

$this – The query object itself

Protected Methods

Method	Description
cleanUpTableNames() (opens new window)	Clean up table names and aliases Both aliases and names are enclosed into .
filterCondition() (opens new window)	Removes empty operands (opens new window) from the given query condition.
getUnaliasedColumnsFromSelect() (opens new window)
getUniqueColumns() (opens new window)	Returns unique column names excluding duplicates.
isEmpty() (opens new window)	Returns a value indicating whether the give value is "empty".
normalizeOrderBy() (opens new window)	Normalizes format of ORDER BY data.
normalizeSelect() (opens new window)	Normalizes the SELECT columns passed to select() (opens new window) or addSelect() (opens new window).
queryScalar()	Queries a scalar value by setting select() (opens new window) first.
setCommandCache() (opens new window)	Sets $command cache, if this query has enabled caching.

queryScalar()

Queries a scalar value by setting select() (opens new window) first.

Restores the value of select to make this query reusable.

View source (opens new window)

Arguments

• $selectExpression (string (opens new window), yii\db\ExpressionInterface (opens new window))
• $db (yii\db\Connection (opens new window), null (opens new window)) – The database connection used to execute the query.

Returns

boolean (opens new window), string (opens new window), null (opens new window)

Throws

• Throwable (opens new window)
  if can't create command

Events

EVENT_DEFINE_BEHAVIORS

Type

craft\events\DefineBehaviorsEvent

The event that is triggered when defining the class behaviors

See also behaviors()

EVENT_INIT

Type

yii\base\Event (opens new window)

The event that is triggered after the query's init cycle

See also init()