Class yii\db\Query

继承yii\db\Query » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable, yii\db\ExpressionInterface, yii\db\QueryInterface
Uses Traitsyii\db\QueryTrait
子类yii\db\ActiveQuery
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/db/Query.php

Query 以独立于 DBMS 的方式表示 SELECT SQL 语句.

Query 提供了一组方法, 以方便在 SELECT 语句中指定不同的子句. 这些方法可以链接在一起.

通过调用 createCommand(), 我们可以得到一个 yii\db\Command 实例, 该实例可进一步用于对数据库执行(perform/execute) DB 查询.

例如,

$query = new Query;
// 组合查询
$query->select('id, name')
    ->from('user')
    ->limit(10);
// 构建并执行查询
$rows = $query->all();
// 或者, 你可以创建 DB 命令并执行它
$command = $query->createCommand();
// $command->sql 返回实际的 SQL
$rows = $command->queryAll();

Query 在内部使用 yii\db\QueryBuilder 类生成 SQL 语句.

有关如何使用 Query 的更详细的使用指南可以在 guide article on Query Builder 中找到.

公共属性

隐藏继承的属性

属性类型描述定义在
$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
$join array 如何与其它表连接. yii\db\Query
$limit integer|yii\db\ExpressionInterface 返回的最大记录数. yii\db\QueryTrait
$offset integer|yii\db\ExpressionInterface 0开始的记录偏移量. yii\db\QueryTrait
$orderBy array 如何对查询结果进行排序. yii\db\QueryTrait
$params array 由参数占位符索引的查询参数值的列表. yii\db\Query
$queryCacheDependency yii\caching\Dependency 与该查询的缓存查询结果关联的依赖项. yii\db\Query
$queryCacheDuration integer|true 查询结果在高速缓存中保持有效的默认秒数. yii\db\Query
$select array 被选中的列(组). yii\db\Query
$selectOption string 应附加到SELECT关键字的附加选项. yii\db\Query
$tablesUsedInFrom string[] 由别名索引的表名. 该属性是只读的. yii\db\Query
$union array 这用于在 SQL 语句中构造 UNION 子句. yii\db\Query
$where string|array|yii\db\ExpressionInterface 查询条件. yii\db\QueryTrait
$withQueries array 这用于在 SQL 语句中构造 WITH 子句. yii\db\Query

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__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
all() 执行查询并以数组形式返回所有结果. yii\db\Query
andFilterCompare() 为特定列添加过滤条件, 并允许用户选择过滤器操作符. yii\db\Query
andFilterHaving() 向现有的条件添加一个额外的 HAVING 条件, 但忽略 空操作数. yii\db\Query
andFilterWhere() 将一个 WHERE 条件添加到现有条件中, 但忽略 空操作数. yii\db\QueryTrait
andHaving() 为现有的查询添加一个额外的 HAVING 条件. yii\db\Query
andWhere() 向现有条件添加一个额外的 WHERE 条件. yii\db\Query
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\Query
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
from() 设置查询的 FROM 部分. yii\db\Query
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getTablesUsedInFrom() 返回由别名索引的 from() 中使用的表名. yii\db\Query
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\base\BaseObject
innerJoin() 将 INNER JOIN 部分附加到到查询中. yii\db\Query
join() 将 JOIN 部分附加到到查询中. yii\db\Query
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
one() 执行查询并返回单行结果. yii\db\Query
orFilterHaving() 向现有的条件添加一个额外的 HAVING 条件, 但忽略 空操作数. yii\db\Query
orFilterWhere() 将一个 WHERE 条件添加到现有条件中, 但忽略 空操作数. yii\db\QueryTrait
orHaving() 为现有的查询添加一个额外的 HAVING 条件. yii\db\Query
orWhere() 向现有条件添加一个额外的 WHERE 条件. yii\db\Query
orderBy() 设置查询的 ORDER BY 部分. yii\db\QueryTrait
params() 设置要绑定到查询的参数. yii\db\Query
populate() 将原始查询结果转换为此查询指定的格式. yii\db\Query
prepare() 准备构建 SQL. yii\db\Query
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
where() 设置查询的 WHERE 部分. yii\db\Query
withQuery() 使用 WITH 语法准备一条 SQL 语句. yii\db\Query

受保护的方法

隐藏继承的方法

方法描述定义在
cleanUpTableNames() 清理表名和别名. yii\db\Query
filterCondition() 从给定的查询条件中移除 空的操作数. yii\db\QueryTrait
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\Query
setCommandCache() 如果此查询已启用缓存, 则设置 $command 缓存. yii\db\Query

属性详情

$distinct public 属性

是否仅选择不同的数据行. 如果设置为true, 则 SELECT 子句将更改为 SELECT DISTINCT.

public boolean $distinct null
$from public 属性

要选择的表. 例如, ['user', 'post']. 这用于在 SQL 语句中构造 FROM 子句.

参见 from().

public array $from null
$groupBy public 属性

如何将查询结果分组. 例如, ['company', 'department']. 这用于在 SQL 语句中构造 GROUP BY 子句.

public array $groupBy null
$having public 属性

在 GROUP BY 子句中应用的条件. 它可以是一个字符串或一个数组. 关于如何指定条件, 请参阅 where().

$join public 属性

如何与其它表连接. 每个数组元素表示一个连接规范, 该连接具有以下结构:

[$joinType, $tableName, $joinCondition]

例如,

[
    ['INNER JOIN', 'user', 'user.id = author_id'],
    ['LEFT JOIN', 'team', 'team.id = team_id'],
]
public array $join null
$params public 属性

由参数占位符索引的查询参数值的列表. 例如, [':name' => 'Dan', ':age' => 31].

public array $params = []
$queryCacheDependency public 属性 (可用自版本: 2.0.14)

与该查询的缓存查询结果关联的依赖项.

参见 cache().

$queryCacheDuration public 属性 (可用自版本: 2.0.14)

查询结果在高速缓存中保持有效的默认秒数. 使用10表示缓存的数据将永不过期. 使用负数表示不应使用查询缓存. 使用布尔值true表示应使用 yii\db\Connection::$queryCacheDuration.

参见 cache().

$select public 属性

被选中的列(组). 例如, ['id', 'name']. 这用于在 SQL 语句中构造 SELECT 子句. 如果未设置, 则意味着选择所有列.

参见 select().

public array $select null
$selectOption public 属性

应附加到SELECT关键字的附加选项. 例如, 在 MySQL 中, 可以使用SQL_CALC_FOUND_ROWS选项.

public string $selectOption null
$tablesUsedInFrom public 属性

由别名索引的表名. 该属性是只读的.

public string[] $tablesUsedInFrom null
$union public 属性

这用于在 SQL 语句中构造 UNION 子句. 每个数组元素都是以下结构的数组:

  • query: 表示查询的字符串或 yii\db\Query 对象.
  • all: boolean, 使用UNION ALL还是UNION.
public array $union null
$withQueries public 属性 (可用自版本: 2.0.35)

这用于在 SQL 语句中构造 WITH 子句. 每个数组元素都是以下结构的数组:

  • query: 表示查询的字符串或 yii\db\Query 对象.
  • alias: string, 查询的别名, 以供进一步使用.
  • recursive: boolean, 使用WITH RECURSIVE还是WITH.

参见 withQuery().

public array $withQueries null

方法详情

__toString() public 方法

返回查询的 SQL 表示形式.

public string __toString ( )
addGroupBy() public 方法

向现有的列添加额外的 group-by 列.

参见 groupBy().

public $this addGroupBy ( $columns )
$columns string|array|yii\db\ExpressionInterface

要分组的列. 列可以用字符串(eg. "id, name")或数组(eg. ['id', 'name'])指定. 除非列中包含一些括号(表示该列包含一个 DB 表达式), 否则该方法将自动引用列名称.

Note: 如果你的 group-by 是包含逗号的表达式, 则应始终使用数组来表示 group-by 信息. 否则, 该方法将无法正确确定分组列.

自版本 2.0.7 起, 可以传递一个 yii\db\Expression 对象以在普通 SQL 中显示指定 GROUP BY 部分. 自版本 2.0.14 起, 也可以传递 yii\db\ExpressionInterface 对象.

return $this

查询对象本身.

addParams() public 方法

添加要绑定到查询的其它参数.

参见 params().

public $this addParams ( $params )
$params array

由参数占位符索引的查询参数值的列表. 例如, [':name' => 'Dan', ':age' => 31].

return $this

查询对象本身.

addSelect() public 方法

将更多列添加到查询的 SELECT 部分.

Note: 如果以前未指定 select(), 但也要选择所有剩余的列, 则应显示的包含*:

$query->addSelect(["*", "CONCAT(first_name, ' ', last_name) AS full_name"])->one();

参见 select().

public $this addSelect ( $columns )
$columns string|array|yii\db\ExpressionInterface

要添加到选择的列. 有关此参数格式的更多详细信息, 请参阅 select().

return $this

查询对象本身.

all() public 方法

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

public array all ( $db null )
$db yii\db\Connection

用于生成 SQL 语句的 DB 连接. 如果未提供此参数, 则将使用应用程序db组件.

return array

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

andFilterCompare() public 方法 (可用自版本: 2.0.8)

为特定列添加过滤条件, 并允许用户选择过滤器操作符.

它为给定字段添加了额外的 WHERE 条件, 并根据给定值的前几个字符确定比较运算符. 与 andFilterWhere() 中添加条件的方式相同, 因此将忽略 空值. 新条件和现有条件将使用AND运算符合并.

比较运算符根据给定值中的前几个字符智能确定的. 特别是, 如果它们以给定值中的开头字符出现, 它将识别以下运算符:

  • <: 该列必须小于给定的值.
  • >: 该列必须大于给定的值.
  • <=: 该列必须小于或等于给定的值.
  • >=: 该列必须大于或等于给定的值.
  • <>: 该列不能与给定的值相同.
  • =: 该列必须等于给定的值.
  • 如果没有检测到上述操作符, 则使用$defaultOperator.
public $this andFilterCompare ( $name, $value, $defaultOperator '=' )
$name string

列名.

$value string

前面带有比较运算符(可选)的列值.

$defaultOperator string

$value中未指定运算符时使用的运算符. 默认为=, 执行完全匹配.

return $this

查询对象本身.

andFilterHaving() public 方法 (可用自版本: 2.0.11)

向现有的条件添加一个额外的 HAVING 条件, 但忽略 空操作数.

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

该方法类似于 andHaving(). 主要区别在于此方法将删除 空查询操作数. 因此, 此方法最适合基于用户输入的过滤器值构建查询条件.

参见:

public $this andFilterHaving ( array $condition )
$condition array

新的 HAVING 条件. 有关如何指定此参数, 请参阅 having().

return $this

查询对象本身.

andHaving() public 方法

为现有的查询添加一个额外的 HAVING 条件.

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

参见:

public $this andHaving ( $condition, $params = [] )
$condition string|array|yii\db\ExpressionInterface

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

$params array

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

return $this

查询对象本身.

andWhere() public 方法

向现有条件添加一个额外的 WHERE 条件.

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

参见:

public $this andWhere ( $condition, $params = [] )
$condition string|array|yii\db\ExpressionInterface

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

$params array

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

return $this

查询对象本身.

average() public 方法

返回指定列值的平均值.

public mixed average ( $q, $db null )
$q string

列名或表达式. 确保在表达式中正确地使用 quote 列名称.

$db yii\db\Connection

用于生成 SQL 语句的 DB 连接. 如果未提供此参数, 则将使用应用程序db组件.

return mixed

指定列值的平均值.

batch() public 方法

开始批处理查询.

批处理查询支持批量提取数据, 这可以使内存使用量保持在限制之下. 该方法将返回一个实现 Iterator 接口的 yii\db\BatchQueryResult 对象, 并且可以遍历来批量检索数据.

例如,

$query = (new Query)->from('user');
foreach ($query->batch() as $rows) {
    // $rows 是来自 user 表的100行或更少行的数组
}
public yii\db\BatchQueryResult batch ( $batchSize 100, $db null )
$batchSize integer

每个批次中要提取的记录数.

$db yii\db\Connection

数据库连接. 如果未设置, 将会使用应用程序db组件.

return yii\db\BatchQueryResult

批量查询结果. 它实现了 Iterator 接口, 并可以遍历以批量检索数据.

cache() public 方法 (可用自版本: 2.0.14)

为该查询启用查询缓存.

public $this cache ( $duration true, $dependency null )
$duration integer|true

查询结果可以在缓存中保持有效的秒数. 使用0表示缓存的数据将永不过期. 使用负数表示不应使用查询缓存. 使用布尔值true表示应使用 yii\db\Connection::$queryCacheDuration. 默认为true.

$dependency yii\caching\Dependency

与缓存结果关联的缓存依赖项.

return $this

查询对象本身.

cleanUpTableNames() protected 方法 (可用自版本: 2.0.14)

清理表名和别名.

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

protected string[] cleanUpTableNames ( $tableNames )
$tableNames array

非空数组.

return string[]

由别名索引的表名.

column() public 方法

执行查询并返回结果的第一列.

public array column ( $db null )
$db yii\db\Connection

用于生成 SQL 语句的 DB 连接. 如果未提供此参数, 则将使用应用程序db组件.

return array

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

count() public 方法

返回记录数.

public integer|string count ( $q '*', $db null )
$q string

COUNT 表达式. 默认为*. 确保在表达式中正确地使用 quote 列名称.

$db yii\db\Connection

用于生成 SQL 语句的 DB 连接. 如果未提供此参数, 则将使用应用程序db组件.

return integer|string

记录数. 结果可能是一个字符串, 具体取决于底层的数据库引擎, 并支持高于 32 位 PHP 整数可以处理的整数值.

create() public static 方法

创建一个新的 Query 对象, 并从现有的对象中复制其属性值.

被复制的属性是查询构建器将使用的属性.

public static yii\db\Query create ( $from )
$from yii\db\Query

源查询对象.

return yii\db\Query

新的 Query 对象.

createCommand() public 方法

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

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

用于生成 SQL 语句的数据库连接. 如果未提供此参数, 则将使用应用程序db组件.

return yii\db\Command

创建的 DB 命令实例.

distinct() public 方法

设置指示是否使用 SELECT DISTINCT.

public $this distinct ( $value true )
$value boolean

是否使用 SELECT DISTINCT.

return $this

查询对象本身.

each() public 方法

开始批量查询并逐行检索数据.

此方法与 batch() 类似, 不同之处在于, 在每次结果迭代中仅返回一行数据. 例如:

$query = (new Query)->from('user');
foreach ($query->each() as $row) {
}
public yii\db\BatchQueryResult each ( $batchSize 100, $db null )
$batchSize integer

每个批次中要提取的记录数.

$db yii\db\Connection

数据库连接. 如果未设置, 将会使用应用程序db组件.

return yii\db\BatchQueryResult

批量查询结果. 它实现了 Iterator 接口, 并可以遍历以批量检索数据.

exists() public 方法

返回一个值, 该值指示查询结果是否包含任何数据行.

public boolean exists ( $db null )
$db yii\db\Connection

用于生成 SQL 语句的 DB 连接. 如果未提供此参数, 则将使用应用程序db组件.

return boolean

查询结果是否包含任何数据行.

filterHaving() public 方法 (可用自版本: 2.0.11)

设置查询的 HAVING 部分, 但忽略 空操作数.

该方法类似于 having(). 主要区别在于此方法将删除 空查询操作数. 因此, 此方法最适合基于用户输入的过滤器值构建查询条件.

以下代码显示了此方法与 having() 之间的区别:

// HAVING `age`=:age
$query->filterHaving(['name' => null, 'age' => 20]);
// HAVING `age`=:age
$query->having(['age' => 20]);
// HAVING `name` IS NULL AND `age`=:age
$query->having(['name' => null, 'age' => 20]);

Note: having() 不同, 你无法将绑定参数传递给此方法.

参见:

public $this filterHaving ( array $condition )
$condition array

应放在 HAVING 部分的条件. 有关如何指定此参数, 请参阅 having().

return $this

查询对象本身.

from() public 方法

设置查询的 FROM 部分.

public $this from ( $tables )
$tables string|array|yii\db\ExpressionInterface

要从中选择的表. 这可以是指定一个或多个表名的字符串(eg. 'user')或数组(eg. ['user', 'profile']). 表名可以包含模式前缀(eg. 'public.user')和/或表别名(eg. 'user u'). 该方法将自动引用表名, 除非它包含一些括号(表示该表作为子查询或 DB 表达式给出的).

当表被指定为一个数组时, 还可以将数组键作为表别名(如果表不需要别名, 请不要使用字符串键).

使用 Query 对象来表示一个子查询. 在这种情况下, 相应的数组键将被用作子查询的别名.

要在普通 SQL 中指定FROM部分, 你可以传递 yii\db\ExpressionInterface 的实例.

这里有些例子:

// SELECT * FROM  `user` `u`, `profile`;
$query = (new \yii\db\Query)->from(['u' => 'user', 'profile']);

// SELECT * FROM (SELECT * FROM `user` WHERE `active` = 1) `activeusers`;
$subquery = (new \yii\db\Query)->from('user')->where(['active' => true])
$query = (new \yii\db\Query)->from(['activeusers' => $subquery]);

// subquery can also be a string with plain SQL wrapped in parenthesis
// SELECT * FROM (SELECT * FROM `user` WHERE `active` = 1) `activeusers`;
$subquery = "(SELECT * FROM `user` WHERE `active` = 1)";
$query = (new \yii\db\Query)->from(['activeusers' => $subquery]);
return $this

查询对象本身.

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

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

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

public string[] getTablesUsedInFrom ( )
return string[]

由别名索引的表名.

throws yii\base\InvalidConfigException
getUnaliasedColumnsFromSelect() protected 方法 (可用自版本: 2.0.14)
弃用 in 2.0.21

protected array getUnaliasedColumnsFromSelect ( )
return array

SELECT 语句中不带别名的列的列表.

getUniqueColumns() protected 方法 (可用自版本: 2.0.14)
弃用 in 2.0.21

返回唯一的列名列表, 不包括重复项.

要删除的列:

  • 如果列定义已存在于具有相同别名的 SELECT 部分中.
  • 如果没有别名的 SELECT 部分中已存在没有别名的列定义.
protected void getUniqueColumns ( $columns )
$columns array

要合并到选择的列.

groupBy() public 方法

设置查询的 GROUP BY 部分.

参见 addGroupBy().

public $this groupBy ( $columns )
$columns string|array|yii\db\ExpressionInterface

要分组的列. 列可以用字符串(eg. "id, name")或数组(eg. ['id', 'name'])指定. 除非列中包含一些括号(表示该列包含一个 DB 表达式), 否则该方法将自动引用列名称.

Note: 如果你的 group-by 是包含逗号的表达式, 则应始终使用数组来表示 group-by 信息. 否则, 该方法将无法正确确定分组列.

自版本 2.0.7 起, 可以传递一个 yii\db\Expression 对象以在普通 SQL 中显示指定 GROUP BY 部分. 自版本 2.0.14 起, 也可以传递 yii\db\ExpressionInterface 对象.

return $this

查询对象本身.

having() public 方法

设置查询的 HAVING 部分.

参见:

public $this having ( $condition, $params = [] )
$condition string|array|yii\db\ExpressionInterface

HAVING 之后的条件. 有关如何指定此参数, 请参阅 where().

$params array

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

return $this

查询对象本身.

innerJoin() public 方法

将 INNER JOIN 部分附加到到查询中.

public $this innerJoin ( $table, $on '', $params = [] )
$table string|array

要连接的表或子查询.

使用字符串来表示要连接的表的名称. 表名可以包含模式前缀(eg. 'public.user')和/或表别名(eg. 'user u'). 该方法将自动引用表名, 除非它包含一些括号(表示该表作为子查询或 DB 表达式给出的).

你还可以使用数组键作为表别名(eg. ['u' => 'user'])将表指定为具有一个元素的数组.

要连接子查询, 请使用一个数组, 该数组包含一个元素, 其值设置为表示子查询的 yii\db\Query 对象, 对应的键表示别名.

$on string|array

应该出现在 ON 部分的连接条件. 有关如何指定此参数, 请参阅 where().

$params array

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

return $this

查询对象本身.

join() public 方法

将 JOIN 部分附加到到查询中.

第一个参数指定连接的类型.

public $this join ( $type, $table, $on '', $params = [] )
$type string

连接的类型, 例如: INNER JOIN, LEFT JOIN.

$table string|array

要连接的表或子查询.

使用字符串来表示要连接的表的名称. 表名可以包含模式前缀(eg. 'public.user')和/或表别名(eg. 'user u'). 该方法将自动引用表名, 除非它包含一些括号(表示该表作为子查询或 DB 表达式给出的).

你还可以使用数组键作为表别名(eg. ['u' => 'user'])将表指定为具有一个元素的数组.

要连接子查询, 请使用一个数组, 该数组包含一个元素, 其值设置为表示子查询的 yii\db\Query 对象, 对应的键表示别名.

$on string|array

应该出现在 ON 部分的连接条件. 有关如何指定此参数, 请参阅 where().

Note: where() 的数组格式旨在将列与值匹配, 而不是将列与列匹配, 因此以下内容将无法按预期工作: ['post.author_id' => 'user.id'], 它将使用post.author_id列值与字符串'user.id'相匹配. 建议在此处使用更适合连接的字符串语法.

'post.author_id = user.id'
$params array

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

return $this

查询对象本身.

leftJoin() public 方法

将 LEFT JOIN 部分附加到到查询中.

public $this leftJoin ( $table, $on '', $params = [] )
$table string|array

要连接的表或子查询.

使用字符串来表示要连接的表的名称. 表名可以包含模式前缀(eg. 'public.user')和/或表别名(eg. 'user u'). 该方法将自动引用表名, 除非它包含一些括号(表示该表作为子查询或 DB 表达式给出的).

你还可以使用数组键作为表别名(eg. ['u' => 'user'])将表指定为具有一个元素的数组.

要连接子查询, 请使用一个数组, 该数组包含一个元素, 其值设置为表示子查询的 yii\db\Query 对象, 对应的键表示别名.

$on string|array

应该出现在 ON 部分的连接条件. 有关如何指定此参数, 请参阅 where().

$params array

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

return $this

查询对象本身.

max() public 方法

返回指定列值的最大值.

public mixed max ( $q, $db null )
$q string

列名或表达式. 确保在表达式中正确地使用 quote 列名称.

$db yii\db\Connection

用于生成 SQL 语句的 DB 连接. 如果未提供此参数, 则将使用应用程序db组件.

return mixed

指定列值的最大值.

min() public 方法

返回指定列值的最小值.

public mixed min ( $q, $db null )
$q string

列名或表达式. 确保在表达式中正确地使用 quote 列名称.

$db yii\db\Connection

用于生成 SQL 语句的 DB 连接. 如果未提供此参数, 则将使用应用程序db组件.

return mixed

指定列值的最小值.

noCache() public 方法 (可用自版本: 2.0.14)

禁用此查询的查询缓存.

public $this noCache ( )
return $this

查询对象本身.

normalizeSelect() protected 方法 (可用自版本: 2.0.21)

标准化传递给 select()addSelect() 的 SELECT 列.

protected array normalizeSelect ( $columns )
$columns string|array|yii\db\ExpressionInterface
one() public 方法

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

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

用于生成 SQL 语句的 DB 连接. 如果未提供此参数, 则将使用应用程序db组件.

return array|boolean

查询结果的第一行(以数组表示). 如果查询没有任何结果, 则返回false.

orFilterHaving() public 方法 (可用自版本: 2.0.11)

向现有的条件添加一个额外的 HAVING 条件, 但忽略 空操作数.

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

该方法类似于 orHaving(). 主要区别在于此方法将删除 空查询操作数. 因此, 此方法最适合基于用户输入的过滤器值构建查询条件.

参见:

public $this orFilterHaving ( array $condition )
$condition array

新的 HAVING 条件. 有关如何指定此参数, 请参阅 having().

return $this

查询对象本身.

orHaving() public 方法

为现有的查询添加一个额外的 HAVING 条件.

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

参见:

public $this orHaving ( $condition, $params = [] )
$condition string|array|yii\db\ExpressionInterface

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

$params array

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

return $this

查询对象本身.

orWhere() public 方法

向现有条件添加一个额外的 WHERE 条件.

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

参见:

public $this orWhere ( $condition, $params = [] )
$condition string|array|yii\db\ExpressionInterface

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

$params array

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

return $this

查询对象本身.

params() public 方法

设置要绑定到查询的参数.

参见 addParams().

public $this params ( $params )
$params array

由参数占位符索引的查询参数值的列表. 例如, [':name' => 'Dan', ':age' => 31].

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
rightJoin() public 方法

将 RIGHT JOIN 部分附加到到查询中.

public $this rightJoin ( $table, $on '', $params = [] )
$table string|array

要连接的表或子查询.

使用字符串来表示要连接的表的名称. 表名可以包含模式前缀(eg. 'public.user')和/或表别名(eg. 'user u'). 该方法将自动引用表名, 除非它包含一些括号(表示该表作为子查询或 DB 表达式给出的).

你还可以使用数组键作为表别名(eg. ['u' => 'user'])将表指定为具有一个元素的数组.

要连接子查询, 请使用一个数组, 该数组包含一个元素, 其值设置为表示子查询的 yii\db\Query 对象, 对应的键表示别名.

$on string|array

应该出现在 ON 部分的连接条件. 有关如何指定此参数, 请参阅 where().

$params array

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

return $this

查询对象本身.

scalar() public 方法

以标量值的形式返回查询结果.

返回的值将是查询结果第一行中的第一列.

public string|integer|null|false scalar ( $db null )
$db yii\db\Connection

用于生成 SQL 语句的 DB 连接. 如果未提供此参数, 则将使用应用程序db组件.

return string|integer|null|false

查询结果第一行中第一列的值. 如果查询结果为空, 则返回false.

select() public 方法

设置查询的 SELECT 部分.

public $this select ( $columns, $option null )
$columns string|array|yii\db\ExpressionInterface

要选择的列. 列可以用字符串(eg. "id, name")或数组(eg. ['id', 'name'])指定. 列可以以表名作为前缀(eg. "user.id")和/或包含列别名(eg. "user.id AS user_id"). 除非列中包含一些括号(表示该列包含 DB 表达式), 否则该方法将自动引用列名称. DB 表达式也可以以 yii\db\ExpressionInterface 对象的形式传递.

Note: 如果选择类似于CONCAT(first_name, ' ', last_name)这样的表达式, 则应使用数组来指定列. 否则, 该表达式可能会错误地分成几个部分.

当将列指定为数组时, 你也可以使用数组键作为列别名(如果列不需要别名, 请不要使用字符串键).

从版本2.0.1开始, 你也可以通过将每个这样的列指定为表示子查询的Query实例来选择子查询作为列.

$option string

应附加到SELECT关键字的附加选项. 例如, 在 MySQL 中, 可以使用SQL_CALC_FOUND_ROWS选项.

return $this

查询对象本身.

setCommandCache() protected 方法 (可用自版本: 2.0.14)

如果此查询已启用缓存, 则设置 $command 缓存.

protected yii\db\Command setCommandCache ( $command )
$command yii\db\Command
sum() public 方法

返回指定列值的总和.

public mixed sum ( $q, $db null )
$q string

列名或表达式. 确保在表达式中正确地使用 quote 列名称.

$db yii\db\Connection

用于生成 SQL 语句的 DB 连接. 如果未提供此参数, 则将使用应用程序db组件.

return mixed

指定列值的总和.

union() public 方法

使用 UNION 运算符附加一条 SQL 语句.

public $this union ( $sql, $all false )
$sql string|yii\db\Query

要使用 UNION 运算符附加的 SQL 语句.

$all boolean

如果使用UNION ALL, 则为true; 如果使用UNION, 则为false.

return $this

查询对象本身.

where() public 方法

设置查询的 WHERE 部分.

该方法需要一个$condition参数, 以及一个可选的$params参数, 该参数指定要绑定到查询的值.

$condition参数应该时字符串(eg. 'id=1')或数组.

{@inheritdoc}

参见:

public $this where ( $condition, $params = [] )
$condition string|array|yii\db\ExpressionInterface

应该放在 WHERE 部分的条件.

$params array

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

return $this

查询对象本身.

withQuery() public 方法 (可用自版本: 2.0.35)

使用 WITH 语法准备一条 SQL 语句.

public $this withQuery ( $query, $alias, $recursive false )
$query string|yii\db\Query

使用 WITH 前缀的 SQL 语句.

$alias string

WITH 构造中的查询别名.

$recursive boolean

如果使用WITH RECURSIVE, 则为true; 如果使用WITH, 则为false.

return $this

查询对象本身.