Class yii\db\ActiveQuery
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 |
$link | array | The columns of the primary and foreign tables that establish a relation. | yii\db\ActiveRelationTrait |
$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 |
属性详情
此查询应与之关联的列表
在关联上下文中使用此查询时要用到的连接条件。 当调用 yii\db\ActiveQuery::joinWith() 时,将在 ON 部分中使用该条件。 否则,条件将在查询的 WHERE 条件中使用。 有关如何指定此参数,请参照 yii\db\Query::where()。
参见 onCondition().
要执行的用于查询 AR 记录的 SQL 语句。 通过 yii\db\ActiveRecord::findBySql() 来设置。
Table names indexed by aliases
方法详情
构造函数。
public void __construct($modelClass, $config = []) | ||
$modelClass | string | 与查询关联的模型类 |
$config | array | 要应用于新创建的查询对象的配置 |
为 $modelClass 中的表定义别名。
public $this alias($alias) | ||
$alias | string | 表的别名. |
return | $this | 查询对象本身 |
---|
执行查询并将所有结果作为数组返回。
public array|yii\db\ActiveRecord[] all($db = null) | ||
$db | yii\db\Connection | 用于创建 DB 命令的 DB 连接。 如果为 NULL,将使用 $modelClass 返回的 DB 连接。 |
return | array|yii\db\ActiveRecord[] | 查询的结果。如果没有查询结果,将返回一个空数组。 |
---|
public $this andOnCondition($condition, $params = []) | ||
$condition | string|array | 新的 ON 条件, 请参阅 where() 关于如何指定参数。 |
$params | array | 要绑定到查询的参数(name => value)。 |
return | $this | 查询对象本身 |
---|
创建可以用于执行此查询的 DB 命令。
public yii\db\Command createCommand($db = null) | ||
$db | yii\db\Connection|null | 用于创建 DB 命令的 DB 连接。
如果为 |
return | yii\db\Command | 创建的 DB 命令实例。 |
---|
protected string getPrimaryTableName() | ||
return | string | 主表名 |
---|
返回 $modelClass 的表名或是表别名。
protected array getTableNameAndAlias() | ||
return | array | 表名和表别名。 |
---|
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 |
初始化对象。 在构造函数的末尾调用此方法。默认执行将触发 EVENT_INIT 事件。 如果你重写这个方法, 确保你在最后要调用父类的执行方法去触发这个事件。
public void init() |
与指定关联的内连接。 这是 joinWith() 的便捷方法,连接类型设置为 "INNER JOIN"。 关于此方法的详细用法,请参阅 joinWith()。
参见 joinWith().
public $this innerJoinWith($with, $eagerLoading = true) | ||
$with | string|array | 连接的关联 |
$eagerLoading | boolean|array | 是否即时加载这个关联。 请注意, 这并不意味着,关联是从查询结果中填充的。 仍将执行额外查询以引入相关数据。 |
return | $this | 查询对象本身 |
---|
与指定关联的连接。
此方法将允许你重用现有的关联定义来执行 JOIN 查询。 基于指定关联的定义, 该方法将一个或多个 JOIN 语句附加到当前查询。
如果 $eagerLoading
参数为真,该方法还将对指定的关联执行即时加载,
相当于使用指定关联调用 with()。
注意,因为将执行 JOIN 查询,所以你需要消除列名的歧义。
此方法与 with() 不同之处在于,它将构建并执行主表的 JOIN SQL 语句。
并且当 $eagerLoading
为真时,除了指定关联之外,还将调用 with()。
public $this joinWith($with, $eagerLoading = true, $joinType = 'LEFT JOIN') | ||
$with | string|array | 要加入的关联。 这可以是表示关联名称的字符串,也可以是具有以下语义的数组:
关联名称可以可选地包含关联表的别名(e.g. 也可以指定子关联,请参阅 with() 的语法。 以下是一些例子:
别名语法从 2.0.7 版本开始可用。 |
$eagerLoading | boolean|array | 是否即时加载关联
在 |
$joinType | string|array |
|
return | $this | 查询对象本身 |
---|
设置关联查询的 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 | 查询对象本身 |
---|
执行查询并返回单行结果。
public yii\db\ActiveRecord|array|null one($db = null) | ||
$db | yii\db\Connection|null | 用于创建 DB 命令的 DB 连接。
如果为 |
return | yii\db\ActiveRecord|array|null | 单行查询结果。
根据 asArray() 的设置,查询的结果可以是数组或 ActiveRecord 对象。
如果没有查询结果将返回 |
---|
public $this orOnCondition($condition, $params = []) | ||
$condition | string|array | 新的 ON 条件。有关如何指定此参数, 请参阅 where()。 |
$params | array | 参数 (name => value) 将被绑定到查询条件中。 |
return | $this | 查询对象本身 |
---|
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 |
---|
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 |
---|
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 |
指定关联查询的连接表。
在 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 的回调,用于定制与连接表相关的关联。
它的签名是 |
return | $this | 查询对象本身 |
---|
事件详情
通过 init() 初始化查询时触发的事件。