没有命名空间的类 yii yii\base yii\behaviors yii\caching yii\captcha yii\console yii\console\controllers yii\console\widgets yii\data yii\db yii\db\conditions yii\db\cubrid yii\db\cubrid\conditions yii\db\mssql yii\db\mssql\conditions yii\db\mysql yii\db\oci yii\db\oci\conditions yii\db\pgsql yii\db\sqlite yii\db\sqlite\conditions yii\di yii\filters yii\filters\auth yii\grid yii\helpers yii\i18n yii\log yii\mail yii\mutex yii\rbac yii\rest yii\test yii\validators yii\web yii\widgets

Class yii\db\ActiveQuery

继承yii\db\ActiveQuery » yii\db\Query » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable, yii\db\ActiveQueryInterface, yii\db\ExpressionInterface, yii\db\QueryInterface
使用 Traitsyii\db\ActiveQueryTrait, yii\db\ActiveRelationTrait, yii\db\QueryTrait
可用版本自2.0
源码 https://github.com/yiichina/yii2/blob/api/framework/db/ActiveQuery.php

ActiveQuery 表示与 Active Record 类关联的数据库查询。

ActiveQuery 可以是普通的查询,也可在关联上下文中使用。

ActiveQuery 实例通常由 yii\db\ActiveRecord::find()yii\db\ActiveRecord::findBySql() 创建。 关联查询由 yii\db\ActiveRecord::hasOne()yii\db\ActiveRecord::hasMany() 创建。

普通查询

ActiveQuery 主要提供以下几种方案去检索查询结果:

  • one():返回第一行数据。
  • all():根据查询结果返回所有的记录。
  • count():返回记录的数量。
  • sum():返回指定列的总和。
  • average():返回指定列的平均值。
  • min():返回指定列的最小值。
  • max():返回指定列的最大值。
  • scalar():返回查询结果第一行中第一列的值。
  • column():返回查询结果中第一列的值。
  • exists():返回一个表明查询结果是否有数据的值。

因为 ActiveQuery 是 yii\db\Query 的扩展,所以可以使用查询方法,比如 where()orderBy() 去自定义查询方法。

ActiveQuery 还提供以下附加查询选项:

  • with():此查询应执行的关联的列表。
  • joinWith():重用关联查询定义,以便将连接添加到查询中。
  • indexBy():对查询结果进行索引列的名称。
  • asArray():是否将每个记录作为数组返回。

可以使用相同名称的方法配置这些选项。例如:

$customers = Customer::find()->with('orders')->asArray()->all();

关联查询

在关联上下文中,ActiveQuery 表示了两个 Active Record 类之间的关系。

关联 ActiveQuery 实例通常由调用 yii\db\ActiveRecord::hasOne()yii\db\ActiveRecord::hasMany() 来创建。 一个 Active Record 类通过定义一个 getter 方法来声明关联, 该方法通过调用之一并返回创建的 ActiveQuery 对象。

关联由 $link 来指定,表示了不同表的列之间的关联; 并且由 $multiple 来表示关联的多样性。

如果关联涉及到连接表,将会通过 via()viaTable() 方法来指定。 这些方法只能在关联上下文中调用。inverseOf() 也是如此, 将关联标记为另一个关联的逆关联, 并将要添加到关联查询连接条件的条件添加到 onCondition() 中。

公共属性

隐藏继承的属性

属性类型描述被定义在
$asArray boolean 是否将每个记录作为数组返回。如果为 false(默认值), 将创建 $modelClass 的对象来表示每个记录。 yii\db\ActiveQueryTrait
$behaviors yii\base\Behavior[] List of behaviors attached to this component yii\base\Component
$distinct boolean Whether to select distinct rows of data only. yii\db\Query
$emulateExecution boolean Whether to emulate the actual query execution, returning empty or false results. yii\db\QueryTrait
$from array The table(s) to be selected from. yii\db\Query
$groupBy array How to group the query results. yii\db\Query
$having string|array|yii\db\ExpressionInterface The condition to be applied in the GROUP BY clause. yii\db\Query
$indexBy string|callable The name of the column by which the query results should be indexed by. yii\db\QueryTrait
$inverseOf string The name of the relation that is the inverse of this relation. yii\db\ActiveRelationTrait
$join array How to join with other tables. yii\db\Query
$joinWith array 此查询应与之关联的列表 yii\db\ActiveQuery
$limit integer|yii\db\ExpressionInterface Maximum number of records to be returned. yii\db\QueryTrait
$modelClass string ActiveRecord 类的名称。 yii\db\ActiveQueryTrait
$multiple boolean Whether this query represents a relation to more than one record. yii\db\ActiveRelationTrait
$offset integer|yii\db\ExpressionInterface Zero-based offset from where the records are to be returned. yii\db\QueryTrait
$on string|array 在关联上下文中使用此查询时要用到的连接条件。 当调用 yii\db\ActiveQuery::joinWith() 时,将在 ON 部分中使用该条件。 否则,条件将在查询的 WHERE 条件中使用。 有关如何指定此参数,请参照 yii\db\Query::where() yii\db\ActiveQuery
$orderBy array How to sort the query results. yii\db\QueryTrait
$params array List of query parameter values indexed by parameter placeholders. yii\db\Query
$primaryModel yii\db\ActiveRecord The primary model of a relational query. yii\db\ActiveRelationTrait
$queryCacheDependency yii\caching\Dependency The dependency to be associated with the cached query result for this query yii\db\Query
$queryCacheDuration integer|true The default number of seconds that query results can remain valid in cache. yii\db\Query
$select array The columns being selected. yii\db\Query
$selectOption string Additional option that should be appended to the 'SELECT' keyword. yii\db\Query
$sql string 要执行的用于查询 AR 记录的 SQL 语句。 通过 yii\db\ActiveRecord::findBySql() 来设置。 yii\db\ActiveQuery
$tablesUsedInFrom string[] Table names indexed by aliases yii\db\ActiveQuery
$union array This is used to construct the UNION clause(s) in a SQL statement. yii\db\Query
$via array|object The query associated with the junction table. yii\db\ActiveRelationTrait
$where string|array|yii\db\ExpressionInterface Query condition. yii\db\QueryTrait
$with array 此查询应使用的关系列表。 yii\db\ActiveQueryTrait

公共方法

隐藏继承的方法

方法描述被定义在
__call() Calls the named method which is not a class method. yii\base\Component
__clone() Clones internal objects. yii\db\ActiveRelationTrait
__construct() 构造函数。 yii\db\ActiveQuery
__get() Returns the value of a component property. yii\base\Component
__isset() Checks if a property is set, i.e. defined and not null. yii\base\Component
__set() Sets the value of a component property. yii\base\Component
__toString() Returns the SQL representation of Query yii\db\Query
__unset() Sets a component property to be null. yii\base\Component
addGroupBy() Adds additional group-by columns to the existing ones. yii\db\Query
addOrderBy() Adds additional ORDER BY columns to the query. yii\db\QueryTrait
addParams() Adds additional parameters to be bound to the query. yii\db\Query
addSelect() Add more columns to the SELECT part of the query. yii\db\Query
alias() $modelClass 中的表定义别名。 yii\db\ActiveQuery
all() 执行查询并将所有结果作为数组返回。 yii\db\ActiveQuery
andFilterCompare() Adds a filtering condition for a specific column and allow the user to choose a filter operator. yii\db\Query
andFilterHaving() Adds an additional HAVING condition to the existing one but ignores empty operands. yii\db\Query
andFilterWhere() Adds an additional WHERE condition to the existing one but ignores empty operands. yii\db\QueryTrait
andHaving() Adds an additional HAVING condition to the existing one. yii\db\Query
andOnCondition() 向现有条件添加额外的 ON 条件。 新条件和现有条件将使用 'AND' 运算符链接。 yii\db\ActiveQuery
andWhere() Adds an additional WHERE condition to the existing one. yii\db\QueryTrait
asArray() 设置 asArray() 属性。 yii\db\ActiveQueryTrait
attachBehavior() Attaches a behavior to this component. yii\base\Component
attachBehaviors() Attaches a list of behaviors to the component. yii\base\Component
average() Returns the average of the specified column values. yii\db\Query
batch() Starts a batch query. yii\db\Query
behaviors() Returns a list of behaviors that this component should behave as. yii\base\Component
cache() Enables query cache for this Query. yii\db\Query
canGetProperty() Returns a value indicating whether a property can be read. yii\base\Component
canSetProperty() Returns a value indicating whether a property can be set. yii\base\Component
className() Returns the fully qualified name of this class. yii\base\BaseObject
column() Executes the query and returns the first column of the result. yii\db\Query
count() Returns the number of records. yii\db\Query
create() Creates a new Query object and copies its property values from an existing one. yii\db\Query
createCommand() 创建可以用于执行此查询的 DB 命令。 yii\db\ActiveQuery
detachBehavior() Detaches a behavior from the component. yii\base\Component
detachBehaviors() Detaches all behaviors from the component. yii\base\Component
distinct() Sets the value indicating whether to SELECT DISTINCT or not. yii\db\Query
each() Starts a batch query and retrieves data row by row. yii\db\Query
emulateExecution() Sets whether to emulate query execution, preventing any interaction with data storage. yii\db\QueryTrait
ensureBehaviors() Makes sure that the behaviors declared in behaviors() are attached to this component. yii\base\Component
exists() Returns a value indicating whether the query result contains any row of data. yii\db\Query
filterHaving() Sets the HAVING part of the query but ignores empty operands. yii\db\Query
filterWhere() Sets the WHERE part of the query but ignores empty operands. yii\db\QueryTrait
findFor() Finds the related records for the specified primary record. yii\db\ActiveRelationTrait
findWith() 查找对应于一个或多个关系的记录,并将它们填充到主模型中。 yii\db\ActiveQueryTrait
from() Sets the FROM part of the query. yii\db\Query
getBehavior() Returns the named behavior object. yii\base\Component
getBehaviors() Returns all behaviors attached to this component. yii\base\Component
getTablesUsedInFrom() Returns table names used in from() indexed by aliases. yii\db\ActiveQuery
groupBy() Sets the GROUP BY part of the query. yii\db\Query
hasEventHandlers() Returns a value indicating whether there is any handler attached to the named event. yii\base\Component
hasMethod() Returns a value indicating whether a method is defined. yii\base\Component
hasProperty() Returns a value indicating whether a property is defined for this component. yii\base\Component
having() Sets the HAVING part of the query. yii\db\Query
indexBy() Sets the indexBy() property. yii\db\QueryTrait
init() 初始化对象。 在构造函数的末尾调用此方法。默认执行将触发 EVENT_INIT 事件。 如果你重写这个方法, 确保你在最后要调用父类的执行方法去触发这个事件。 yii\db\ActiveQuery
innerJoin() Appends an INNER JOIN part to the query. yii\db\Query
innerJoinWith() 与指定关联的内连接。 这是 joinWith() 的便捷方法,连接类型设置为 "INNER JOIN"。 关于此方法的详细用法,请参阅 joinWith() yii\db\ActiveQuery
inverseOf() Sets the name of the relation that is the inverse of this relation. yii\db\ActiveRelationTrait
join() Appends a JOIN part to the query. yii\db\Query
joinWith() 与指定关联的连接。 yii\db\ActiveQuery
leftJoin() Appends a LEFT OUTER JOIN part to the query. yii\db\Query
limit() Sets the LIMIT part of the query. yii\db\QueryTrait
max() Returns the maximum of the specified column values. yii\db\Query
min() Returns the minimum of the specified column values. yii\db\Query
noCache() Disables query cache for this Query. yii\db\Query
off() Detaches an existing event handler from this component. yii\base\Component
offset() Sets the OFFSET part of the query. yii\db\QueryTrait
on() Attaches an event handler to an event. yii\base\Component
onCondition() 设置关联查询的 ON 条件。 调用 yii\db\ActiveQuery::joinWith() 时,将在 ON 部分中使用该条件。 否则,条件将在查询的 WHERE 部分中使用。 yii\db\ActiveQuery
one() 执行查询并返回单行结果。 yii\db\ActiveQuery
orFilterHaving() Adds an additional HAVING condition to the existing one but ignores empty operands. yii\db\Query
orFilterWhere() Adds an additional WHERE condition to the existing one but ignores empty operands. yii\db\QueryTrait
orHaving() Adds an additional HAVING condition to the existing one. yii\db\Query
orOnCondition() 将附加条件 ON 添加到现有条件中。 新条件和现有的条件都将使用 'OR' 运算符连接。 yii\db\ActiveQuery
orWhere() Adds an additional WHERE condition to the existing one. yii\db\QueryTrait
orderBy() Sets the ORDER BY part of the query. yii\db\QueryTrait
params() Sets the parameters to be bound to the query. yii\db\Query
populate() Converts the raw query results into the format as specified by this query. yii\db\ActiveQuery
populateRelation() Finds the related records and populates them into the primary models. yii\db\ActiveRelationTrait
prepare() Prepares for building SQL. yii\db\ActiveQuery
rightJoin() Appends a RIGHT OUTER JOIN part to the query. yii\db\Query
scalar() Returns the query result as a scalar value. yii\db\Query
select() Sets the SELECT part of the query. yii\db\Query
sum() Returns the sum of the specified column values. yii\db\Query
trigger() Triggers an event. yii\base\Component
union() Appends a SQL statement using UNION operator. yii\db\Query
via() Specifies the relation associated with the junction table. yii\db\ActiveRelationTrait
viaTable() 指定关联查询的连接表。 yii\db\ActiveQuery
where() Sets the WHERE part of the query. yii\db\QueryTrait
with() 指定应该执行此查询的关系。 yii\db\ActiveQueryTrait

受保护的方法

隐藏继承的方法

方法描述被定义在
cleanUpTableNames() Clean up table names and aliases Both aliases and names are enclosed into {{ and }}. yii\db\Query
createModels() 将找到的行转换为模型实例。 yii\db\ActiveQueryTrait
filterCondition() Removes empty operands from the given query condition. yii\db\QueryTrait
getPrimaryTableName() yii\db\ActiveQuery
getTableNameAndAlias() 返回 $modelClass 的表名或是表别名。 yii\db\ActiveQuery
getUnaliasedColumnsFromSelect() yii\db\Query
getUniqueColumns() Returns unique column names excluding duplicates. yii\db\Query
isEmpty() Returns a value indicating whether the give value is "empty". yii\db\QueryTrait
normalizeOrderBy() Normalizes format of ORDER BY data. yii\db\QueryTrait
queryScalar() Queries a scalar value by setting select() first. yii\db\ActiveQuery
setCommandCache() Sets $command cache, if this query has enabled caching. yii\db\Query

Events

隐藏继承的事件

事件类型描述被定义在
EVENT_INIT \yii\db\Event 通过 init() 初始化查询时触发的事件。 yii\db\ActiveQuery

属性详情

$joinWith 公共 属性

此查询应与之关联的列表

public array $joinWith null
$on 公共 属性

在关联上下文中使用此查询时要用到的连接条件。 当调用 yii\db\ActiveQuery::joinWith() 时,将在 ON 部分中使用该条件。 否则,条件将在查询的 WHERE 条件中使用。 有关如何指定此参数,请参照 yii\db\Query::where()

参见 onCondition().

public string|array $on null
$sql 公共 属性

要执行的用于查询 AR 记录的 SQL 语句。 通过 yii\db\ActiveRecord::findBySql() 来设置。

public string $sql null
$tablesUsedInFrom 公共 只读 属性

Table names indexed by aliases

方法详情

__construct() 公共 方法

构造函数。

public void __construct($modelClass, $config = [])
$modelClass string

与查询关联的模型类

$config array

要应用于新创建的查询对象的配置

alias() 公共 方法 (自版本 2.0.7 可用)

$modelClass 中的表定义别名。

此方法将调整 from() 以便覆盖已定义的别名。 如果没有定义,from() 将会使用给定的别名。

public $this alias($alias)
$alias string

表的别名.

return $this

查询对象本身

all() 公共 方法

执行查询并将所有结果作为数组返回。

public array|yii\db\ActiveRecord[] all($db null)
$db yii\db\Connection

用于创建 DB 命令的 DB 连接。 如果为 NULL,将使用 $modelClass 返回的 DB 连接。

return array|yii\db\ActiveRecord[]

查询的结果。如果没有查询结果,将返回一个空数组。

andOnCondition() 公共 方法

向现有条件添加额外的 ON 条件。 新条件和现有条件将使用 'AND' 运算符链接。

参见:

public $this andOnCondition($condition, $params = [])
$condition string|array

新的 ON 条件, 请参阅 where() 关于如何指定参数。

$params array

要绑定到查询的参数(name => value)。

return $this

查询对象本身

createCommand() 公共 方法

创建可以用于执行此查询的 DB 命令。

public yii\db\Command createCommand($db null)
$db yii\db\Connection|null

用于创建 DB 命令的 DB 连接。 如果为 null,将使用 $modelClass 返回 DB 连接。

return yii\db\Command

创建的 DB 命令实例。

getPrimaryTableName() 受保护 方法 (自版本 2.0.12 可用)

protected string getPrimaryTableName()
return string

主表名

getTableNameAndAlias() 受保护 方法 (自版本 2.0.16 可用)

返回 $modelClass 的表名或是表别名。

protected array getTableNameAndAlias()
return array

表名和表别名。

getTablesUsedInFrom() 公共 方法 (自版本 2.0.12 可用)

Returns table names used in from() indexed by aliases.

Both aliases and names are enclosed into {{ and }}.

public string[] getTablesUsedInFrom()
return string[]

Table names indexed by aliases

throws yii\base\InvalidConfigException
init() 公共 方法

初始化对象。 在构造函数的末尾调用此方法。默认执行将触发 EVENT_INIT 事件。 如果你重写这个方法, 确保你在最后要调用父类的执行方法去触发这个事件。

public void init()
innerJoinWith() 公共 方法

与指定关联的内连接。 这是 joinWith() 的便捷方法,连接类型设置为 "INNER JOIN"。 关于此方法的详细用法,请参阅 joinWith()

参见 joinWith().

public $this innerJoinWith($with, $eagerLoading true)
$with string|array

连接的关联

$eagerLoading boolean|array

是否即时加载这个关联。 请注意, 这并不意味着,关联是从查询结果中填充的。 仍将执行额外查询以引入相关数据。

return $this

查询对象本身

joinWith() 公共 方法

与指定关联的连接。

此方法将允许你重用现有的关联定义来执行 JOIN 查询。 基于指定关联的定义, 该方法将一个或多个 JOIN 语句附加到当前查询。

如果 $eagerLoading 参数为真,该方法还将对指定的关联执行即时加载, 相当于使用指定关联调用 with()

注意,因为将执行 JOIN 查询,所以你需要消除列名的歧义。

此方法与 with() 不同之处在于,它将构建并执行主表的 JOIN SQL 语句。 并且当 $eagerLoading 为真时,除了指定关联之外,还将调用 with()

public $this joinWith($with, $eagerLoading true, $joinType 'LEFT JOIN')
$with string|array

要加入的关联。 这可以是表示关联名称的字符串,也可以是具有以下语义的数组:

  • 每个数组元素表示单个关联。
  • 你可以将关联名称指定为数组的键,并提供匿名函数, 该函数可以用于动态修改关联查询作为数组值。
  • 如果关联查询不需要修改,你可以使用关联名作为数组值。

关联名称可以可选地包含关联表的别名(e.g. books b)。

也可以指定子关联,请参阅 with() 的语法。

以下是一些例子:

// 查找所有包含书籍的订单,并即使加载 "books"
Order::find()->joinWith('books', true, 'INNER JOIN')->all();
// 查找所有订单,即时加载 "books",并按书名对订单和书籍进行排序。
Order::find()->joinWith([
    'books' => function (\yii\db\ActiveQuery $query) {
        $query->orderBy('item.name');
    }
])->all();
// 查找所有包含 'Science fiction' 类图书的所有订单,图书表将使用 "b" 作为别名
Order::find()->joinWith(['books b'], true, 'INNER JOIN')->where(['b.category' => 'Science fiction'])->all();

别名语法从 2.0.7 版本开始可用。

$eagerLoading boolean|array

是否即时加载关联 在 $with中指定。当为布尔值时,它适用于 $with 中指定所有关联。 使用数组明确列出需要即时加载 $with 中的哪些关联。 注意,这并不意味着, 从查询结果中填充关联。 仍将执行额外查询以引入相关数据。 默认为 true

$joinType string|array

$with 中指定的关联的连接类型。 当它为字符串,它适用于 $with 中指定的所有关联。 使用 relationName => joinType 格式数组为不同的关联指定不同的连接类型。

return $this

查询对象本身

onCondition() 公共 方法

设置关联查询的 ON 条件。 调用 yii\db\ActiveQuery::joinWith() 时,将在 ON 部分中使用该条件。 否则,条件将在查询的 WHERE 部分中使用。

yii\db\ActiveRecord 类声明关联时,使用此方法指定额外条件:

public function getActiveUsers()
{
    return $this->hasMany(User::className(), ['id' => 'user_id'])
                ->onCondition(['active' => true]);
}

请注意,此条件适用于连接以及获取相关记录时。 因此,在该条件中只能使用相关表的字段。尝试访问主记录的字段将导致 non-join-query 的错误。

public $this onCondition($condition, $params = [])
$condition string|array

ON 条件。请参阅 yii\db\Query::where() 查看如果指定参数。

$params array

要绑定到查询的参数(name => value)。

return $this

查询对象本身

one() 公共 方法

执行查询并返回单行结果。

public yii\db\ActiveRecord|array|null one($db null)
$db yii\db\Connection|null

用于创建 DB 命令的 DB 连接。 如果为 null,将使用 $modelClass 返回的 DB 连接。

return yii\db\ActiveRecord|array|null

单行查询结果。 根据 asArray() 的设置,查询的结果可以是数组或 ActiveRecord 对象。 如果没有查询结果将返回 null

orOnCondition() 公共 方法

将附加条件 ON 添加到现有条件中。 新条件和现有的条件都将使用 'OR' 运算符连接。

参见:

public $this orOnCondition($condition, $params = [])
$condition string|array

新的 ON 条件。有关如何指定此参数, 请参阅 where()

$params array

参数 (name => value) 将被绑定到查询条件中。

return $this

查询对象本身

populate() 公共 方法

Converts the raw query results into the format as specified by this query.

This method is internally used to convert the data fetched from database into the format as required by this query.

public array populate($rows)
$rows array

The raw query result from database

return array

The converted query result

prepare() 公共 方法

Prepares for building SQL.

This method is called by yii\db\QueryBuilder when it starts to build SQL from a query object. You may override this method to do some final preparation work when converting a query into a SQL statement.

public $this prepare($builder)
$builder yii\db\QueryBuilder
return $this

A prepared query instance which will be used by yii\db\QueryBuilder to build the SQL

queryScalar() 受保护 方法

Queries a scalar value by setting select() first.

Restores the value of select to make this query reusable.

protected boolean|string queryScalar($selectExpression, $db)
$selectExpression string|yii\db\ExpressionInterface
$db yii\db\Connection|null
viaTable() 公共 方法

指定关联查询的连接表。

yii\db\ActiveRecord 类中声明关联时,使用此方法去指定连接表:

public function getItems()
{
    return $this->hasMany(Item::className(), ['id' => 'item_id'])
                ->viaTable('order_item', ['order_id' => 'id']);
}

参见 via().

public $this viaTable($tableName, $link, callable $callable null)
$tableName string

连接表的名称。

$link array

连接表和关联表 $primaryModel 之间的连接。 数组的键表示连接表的列, 值表示 $primaryModel 表中的列。

$callable callable

一个 PHP 的回调,用于定制与连接表相关的关联。 它的签名是 function($query),其中 $query 是要定制的查询。

return $this

查询对象本身

事件详情

EVENT_INIT event of type \yii\db\Event

通过 init() 初始化查询时触发的事件。