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
Uses Traitsyii\db\ActiveQueryTrait, yii\db\ActiveRelationTrait, yii\db\QueryTrait
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/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 是否将每条记录作为数组返回. yii\db\ActiveQueryTrait
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$distinct boolean 是否仅选择不同的数据行. yii\db\Query
$emulateExecution boolean 是否模拟实际的查询执行, 返回空或者false结果. yii\db\QueryTrait
$from array 要选择的表. yii\db\Query
$groupBy array 如何将查询结果分组. yii\db\Query
$having string|array|yii\db\ExpressionInterface 在 GROUP BY 子句中应用的条件. yii\db\Query
$indexBy string|callable 查询结果所依据的列的名称. yii\db\QueryTrait
$inverseOf string 与该关系相反的关系的名字. yii\db\ActiveRelationTrait
$join array 如何与其它表连接. yii\db\Query
$joinWith array 此查询与之关联的关系的列表. yii\db\ActiveQuery
$limit integer|yii\db\ExpressionInterface 返回的最大记录数. yii\db\QueryTrait
$modelClass string ActiveRecord 类的名称. yii\db\ActiveQueryTrait
$multiple boolean 此查询是否表示与多个记录的关系. yii\db\ActiveRelationTrait
$offset integer|yii\db\ExpressionInterface 0开始的记录偏移量. yii\db\QueryTrait
$on string|array 在关系上下文中使用此查询时要使用的连接条件. yii\db\ActiveQuery
$orderBy array 如何对查询结果进行排序. yii\db\QueryTrait
$params array 由参数占位符索引的查询参数值的列表. yii\db\Query
$primaryModel yii\db\ActiveRecord 关系查询的主模型. yii\db\ActiveRelationTrait
$queryCacheDependency yii\caching\Dependency 与该查询的缓存查询结果关联的依赖项. yii\db\Query
$queryCacheDuration integer|true 查询结果在高速缓存中保持有效的默认秒数. yii\db\Query
$select array 被选中的列(组). yii\db\Query
$selectOption string 应附加到SELECT关键字的附加选项. yii\db\Query
$sql string 用于检索 AR 记录的 SQL 语句. yii\db\ActiveQuery
$tablesUsedInFrom string[] 由别名索引的表名. 该属性是只读的. yii\db\Query
$union array 这用于在 SQL 语句中构造 UNION 子句. yii\db\Query
$via array|object 与连接表相关联的查询. yii\db\ActiveRelationTrait
$where string|array|yii\db\ExpressionInterface 查询条件. yii\db\QueryTrait
$with array 应当执行此查询的关系列表. yii\db\ActiveQueryTrait
$withQueries array 这用于在 SQL 语句中构造 WITH 子句. yii\db\Query

公共方法

隐藏继承的方法

方法描述定义在
() ActiveRecordInterface[] all($db = null) yii\db\ActiveRelationTrait
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 克隆内部对象. yii\db\ActiveRelationTrait
__construct() 构造函数. yii\db\ActiveQuery
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__toString() 返回查询的 SQL 表示形式. yii\db\Query
__unset() 将组件属性设置为null. yii\base\Component
addGroupBy() 向现有的列添加额外的 group-by 列. yii\db\Query
addOrderBy() 将其它 ORDER BY 列添加到查询中. yii\db\QueryTrait
addParams() 添加要绑定到查询的其它参数. yii\db\Query
addSelect() 将更多列添加到查询的 SELECT 部分. yii\db\Query
alias() $modelClass 中定义的表定义别名. yii\db\ActiveQuery
all() 执行查询并以数组形式返回所有结果. yii\db\ActiveQuery
andFilterCompare() 为特定列添加过滤条件, 并允许用户选择过滤器操作符. yii\db\Query
andFilterHaving() 向现有的条件添加一个额外的 HAVING 条件, 但忽略 空操作数. yii\db\Query
andFilterWhere() 将一个 WHERE 条件添加到现有条件中, 但忽略 空操作数. yii\db\QueryTrait
andHaving() 为现有的查询添加一个额外的 HAVING 条件. yii\db\Query
andOnCondition() 在现有的条件上增加一个 ON 条件. yii\db\ActiveQuery
andWhere() 将一个 WHERE 条件添加到现有条件中. yii\db\QueryTrait
asArray() 设置 asArray() 属性. yii\db\ActiveQueryTrait
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
average() 返回指定列值的平均值. yii\db\Query
batch() 开始批处理查询. yii\db\Query
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
cache() 为该查询启用查询缓存. yii\db\Query
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
column() 执行查询并返回结果的第一列. yii\db\Query
count() 返回记录数. yii\db\Query
create() 创建一个新的 Query 对象, 并从现有的对象中复制其属性值. yii\db\Query
createCommand() 创建可用于执行此查询的 DB 命令. yii\db\ActiveQuery
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
distinct() 设置指示是否使用 SELECT DISTINCT. yii\db\Query
each() 开始批量查询并逐行检索数据. yii\db\Query
emulateExecution() 设置是否模拟查询执行, 以防止与数据存储的任何交互. yii\db\QueryTrait
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
exists() 返回一个值, 该值指示查询结果是否包含任何数据行. yii\db\Query
filterHaving() 设置查询的 HAVING 部分, 但忽略 空操作数. yii\db\Query
filterWhere() 设置查询的 WHERE 部分, 但忽略 空操作数. yii\db\QueryTrait
findFor() 查找指定主记录的相关记录. yii\db\ActiveRelationTrait
findWith() 查找与一个或多个关系相对应的记录, 并将其填充到主要模型中. yii\db\ActiveQueryTrait
from() 设置查询的 FROM 部分. yii\db\Query
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getTablesUsedInFrom() 返回由别名索引的 from() 中使用的表名. yii\db\ActiveQuery
groupBy() 设置查询的 GROUP BY 部分. yii\db\Query
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
having() 设置查询的 HAVING 部分. yii\db\Query
indexBy() 设置 indexBy() 属性. yii\db\QueryTrait
init() 初始化对象. yii\db\ActiveQuery
innerJoin() 将 INNER JOIN 部分附加到到查询中. yii\db\Query
innerJoinWith() 内部连接与指定的关系. yii\db\ActiveQuery
inverseOf() 设置与该关系相反的关系的名称. yii\db\ActiveRelationTrait
join() 将 JOIN 部分附加到到查询中. yii\db\Query
joinWith() 以指定的关系加入. yii\db\ActiveQuery
leftJoin() 将 LEFT JOIN 部分附加到到查询中. yii\db\Query
limit() 设置查询的 LIMIT 部分. yii\db\QueryTrait
max() 返回指定列值的最大值. yii\db\Query
min() 返回指定列值的最小值. yii\db\Query
noCache() 禁用此查询的查询缓存. yii\db\Query
off() 从该组件分离现有的事件处理程序. yii\base\Component
offset() 设置查询的 OFFSET 部分. yii\db\QueryTrait
on() 将事件处理程序附加到事件. yii\base\Component
onCondition() 设置关系查询的 ON 条件. yii\db\ActiveQuery
one() 执行查询并返回单行结果. yii\db\ActiveQuery
orFilterHaving() 向现有的条件添加一个额外的 HAVING 条件, 但忽略 空操作数. yii\db\Query
orFilterWhere() 将一个 WHERE 条件添加到现有条件中, 但忽略 空操作数. yii\db\QueryTrait
orHaving() 为现有的查询添加一个额外的 HAVING 条件. yii\db\Query
orOnCondition() 在现有的条件上增加一个 ON 条件. yii\db\ActiveQuery
orWhere() 将一个 WHERE 条件添加到现有条件中. yii\db\QueryTrait
orderBy() 设置查询的 ORDER BY 部分. yii\db\QueryTrait
params() 设置要绑定到查询的参数. yii\db\Query
populate() 将原始查询结果转换为此查询指定的格式. yii\db\ActiveQuery
populateRelation() 查找相关记录并将其填充到主模型中. yii\db\ActiveRelationTrait
prepare() 准备构建 SQL. yii\db\ActiveQuery
rightJoin() 将 RIGHT JOIN 部分附加到到查询中. yii\db\Query
scalar() 以标量值的形式返回查询结果. yii\db\Query
select() 设置查询的 SELECT 部分. yii\db\Query
sum() 返回指定列值的总和. yii\db\Query
trigger() 触发事件. yii\base\Component
union() 使用 UNION 运算符附加一条 SQL 语句. yii\db\Query
via() 指定与连接表关联的关系. yii\db\ActiveRelationTrait
viaTable() 指定关系查询的连接表. yii\db\ActiveQuery
where() 设置查询的 WHERE 部分. yii\db\QueryTrait
with() 指定应该执行此查询的关系. yii\db\ActiveQueryTrait
withQuery() 使用 WITH 语法准备一条 SQL 语句. yii\db\Query

受保护的方法

隐藏继承的方法

方法描述定义在
cleanUpTableNames() 清理表名和别名. yii\db\Query
createModels() 将找到的行转换为模型实例. yii\db\ActiveQueryTrait
filterCondition() 从给定的查询条件中移除 空的操作数. yii\db\QueryTrait
getPrimaryTableName() 返回主表名称. yii\db\ActiveQuery
getTableNameAndAlias() 返回 $modelClass 的表名和表别名. yii\db\ActiveQuery
getUnaliasedColumnsFromSelect() yii\db\Query
getUniqueColumns() 返回唯一的列名列表, 不包括重复项. yii\db\Query
isEmpty() 判断给定值是否为. yii\db\QueryTrait
normalizeOrderBy() 规范 ORDER BY 数据的格式. yii\db\QueryTrait
normalizeSelect() 标准化传递给 select()addSelect() 的 SELECT 列. yii\db\Query
queryScalar() 首先通过设置 select() 来查询标量值. yii\db\ActiveQuery
setCommandCache() 如果此查询已启用缓存, 则设置 $command 缓存. yii\db\Query

事件

隐藏继承的事件

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

属性详情

$joinWith public 属性

此查询与之关联的关系的列表.

public array $joinWith null
$on public 属性

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

参见 onCondition().

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

用于检索 AR 记录的 SQL 语句. 这是由 yii\db\ActiveRecord::findBySql() 设置.

public string $sql null

方法详情

__construct() public 方法

构造函数.

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

与该查询关联的模型类.

$config array

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

alias() public 方法 (可用自版本: 2.0.7)

$modelClass 中定义的表定义别名.

该方法会调整 from(), 以便已定义的别名将被覆盖. 如果未定义, 则 from() 将使用给定的别名填充.

public $this alias ( $alias )
$alias string

表别名.

return $this

查询对象本身.

all() public 方法

执行查询并以数组形式返回所有结果.

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

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

return array|yii\db\ActiveRecord[]

查询结果. 如果查询没有任何结果, 则返回一个空数组.

andOnCondition() public 方法

在现有的条件上增加一个 ON 条件.

新条件和现有条件将使用AND运算符合并.

参见:

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

新的 ON 条件. 有关如何指定此参数, 请参考 yii\db\Query::where().

$params array

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

return $this

查询对象本身.

createCommand() public 方法

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

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

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

return yii\db\Command

创建的 DB 命令实例.

getPrimaryTableName() protected 方法 (可用自版本: 2.0.12)

返回主表名称.

protected string getPrimaryTableName ( )
return string

主表名称.

getTableNameAndAlias() protected 方法 (可用自版本: 2.0.16)

返回 $modelClass 的表名和表别名.

protected array getTableNameAndAlias ( )
return array

表名和表别名.

getTablesUsedInFrom() public 方法 (可用自版本: 2.0.12)

返回由别名索引的 from() 中使用的表名.

别名和名称都包含在{{}}.

public string[] getTablesUsedInFrom ( )
return string[]

由别名索引的表名.

throws yii\base\InvalidConfigException
init() public 方法

初始化对象.

在构造函数的末尾调用此方法. 默认实现将触发 EVENT_INIT 事件. 如果重写此方法, 请确保在最后调用父实现以确保事件的触发.

public void init ( )
innerJoinWith() public 方法

内部连接与指定的关系.

这是 joinWith() 的快捷方法, 其连接类型设置为INNER JOIN. 有关此方法的详细用法, 请参阅 joinWith().

参见 joinWith().

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

要加入的关系.

$eagerLoading boolean|array

是否预先加载关系.

Note: 这并不意味着从查询结果中填充关系. 仍将执行额外的查询以引入相关数据.

return $this

查询对象本身.

joinWith() public 方法

以指定的关系加入.

此方法允许你可以重用现有的关系定义来执行 JOIN 查询. 根据指定关系的定义, 该方法将向当前查询追加一个或多个 JOIN 语句.

如果$eagerLoading参数为true, 则该方法还将对指定的关系执行预先加载, 这相当于使用指定的关系调用 with().

Note: 因为将执行 JOIN 查询, 所以你有责任消除列名的歧义.

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

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

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

  • 每个数组元素表示一个关系.
  • 你可以将关系名称指定为数组键, 并提供一个匿名函数, 这些函数可用于即使修改关系查询作为数组值.
  • 如果关系查询不需要修改, 则可以使用关系名称作为数组值.

关系名称可以选择包含关系表的别名(eg. 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();
// 使用"books"表的别名"b"查找包含'Science fiction'(科幻小说)类别的图书的所有订单
Order::find()->joinWith(['books b'], true, 'INNER JOIN')->where(['b.category' => 'Science fiction'])->all();

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

$eagerLoading boolean|array

是否预先加载$with中指定的关系. 默认为true. 如果是布尔值, 则适用于$with中指定的所有关系. 使用一个数组来显式地列出$with中的哪些关系需要预先加载.

Note: 这并不意味着从查询结果中填充关系. 仍将执行额外的查询以引入相关数据.

$joinType string|array

$with中指定的关系的连接类型. 如果是字符串, 则适用于$with中指定的所有关系. 使用relationName => joinType格式的数组来为不同的关系指定不同的连接类型.

return $this

查询对象本身.

onCondition() public 方法

设置关系查询的 ON 条件.

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

yii\db\ActiveRecord 类中声明关系时, 请使用此方法来指定其它条件:

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

Note: 在连接以及获取相关记录时将应用此条件. 因此, 条件中只能使用相关表的字段. 尝试访问主记录的字段将在非连接查询中导致错误.

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

ON 条件. 有关如何指定此参数, 请参考 yii\db\Query::where().

$params array

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

return $this

查询对象本身.

one() public 方法

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

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

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

return yii\db\ActiveRecord|array|null

单行查询结果. 根据 asArray() 的设置, 查询结果可能是数组或 ActiveRecord 对象. 如果查询没有任何结果, 则返回null.

orOnCondition() public 方法

在现有的条件上增加一个 ON 条件.

新条件和现有条件将使用OR运算符合并.

参见:

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

新的 ON 条件. 有关如何指定此参数, 请参考 yii\db\Query::where().

$params array

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

return $this

查询对象本身.

populate() public 方法

将原始查询结果转换为此查询指定的格式.

此方法在内部用于将从数据库获取的数据转换为此查询所需的格式.

public array populate ( $rows )
$rows array

来自数据库的原始查询结果.

return array

转换后的查询结果.

prepare() public 方法

准备构建 SQL.

yii\db\QueryBuilder 在从查询对象开始构建 SQL 时会调用此方法. 在将查询转换为 SQL 语句时, 可以重写此方法以做一些最终的准备工作.

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

准备好的查询实例, yii\db\QueryBuilder 将使用它来构建 SQL.

queryScalar() protected 方法

首先通过设置 select() 来查询标量值.

还原 select 的值以使此查询可重用.

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

指定关系查询的连接表.

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

查询对象本身.

throws yii\base\InvalidConfigException

查询未正确初始化时.

事件详情

EVENT_INIT 事件类型 \yii\db\Event

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