类 - QDB_Select

用于初始化一个查询的内容

可用的集合类型

可用的 JOIN 操作类型

可用的 UNICODE 类型

查询参数初始化

手工指定的 SQL 语句

构造查询的各个部分

查询可以使用的关联

查询参数（仅用于一次查询）

指示查询上下文中当前的表名称或其别名

当前查询已经连接的数据表

字段名映射

当前查询所服务的 ActiveRecord 继承类的元信息对象

执行数据库查询的适配器

查询ID

构造函数

设置要使用的数据库访问对象

返回当前使用的数据库访问对象

手动设置查询 SQL

创建一个 SELECT DISTINCT 查询

添加一个要查询的表及其要查询的字段

$table 参数指定要从哪个数据表查询数据。该参数可以是字符串、名值对或者一个表数据入口对象。

如果 $table 是一个字符串，则假定为一个表名称，或者是“表名称 AS 别名”； 如果 $table 是一个表数据入口对象，则表名称由表数据入口对象确定； 如果 $table 是一个名值对，则键名假定为要在查询中使用的表别名，键值可以是字符串或表数据入口对象。

如果要指定数据表所属 schema，可以采用如下形式：

$select->from('schema名.表名称');
// 或者
$select->from(array('表别名' => 'schema名.表名称'));

如果 $table 是一个表数据入口对象，则 schmea 由表数据入口对象确定。

$cols 参数指定了要查询该表的哪些字段，如果不指定则默认为 '*'（既查询所有字段）。 $cols 可以是一个以“,”分割的字段名字符串，也可以是一个数组，以及一个 QDB_Expr 对象。

例如：

// SELECT `posts`.`title`, `posts`.`body` FROM `posts`
$select->from('posts', 'title, body');

还可以为字段名指定查询时使用的别名，例如：

// 指定字段别名
// SELECT `posts`.`title` AS `t` FROM `posts`
$select->from('posts', array('t' => 'title'));

$cols 是字符串或数组时，字段名会被自动转义。 如果 $cols 是一个 QDB_Expr 对象，则表达式中的字段名需要使用“[]”来指定转义。

// SELECT LEFT(`posts`.`title`, 5) FROM `posts`
$expr = new QDB_Expr('LEFT([title], 5)');
$select->form('posts', $expr);
 
// SELECT LEFT(`p`.`title`, 5) FROM `posts` `p`
$expr = new QDB_Expr('LEFT([title], 5)');
$select->form(array('p' => 'posts'), $expr);

from() 的更多用法：

// 指定要查询的数据表及字段
$select->from('posts', 'title, body');
 
// 为数据表指定别名
$select->from(array('别名' => '表名称'), '字段名, 字段名'));
 
// 通过表数据入口指定表
$select->form($table_posts, '字段名, 字段名');
 
// 通过表数据入口指定表和别名
$select->form(array('别名' => $table_posts), array('别名' => '字段名', '字段名'));

如果 $table 参数为空，则通过 $cols 参数指定的字段名前面不会添加数据表名称。

添加要查询的字段

$cols 和 $table 参数的规则同 from() 方法。

如果没有指定 $table 参数，则假定这些字段属于第一个 FROM 操作添加的表。 但是也可以用“表名称.字段名”的方式来指定字段所属表。

除此以外，还可以通过 $table 参数批量指定这些字段所属表。

指定要查询的字段

$cols 和 $table 参数的规则同 from() 方法。

如果没有指定 $table 参数，则假定这些字段属于第一个 FROM 操作添加的表。 但是也可以用“表名称.字段名”的方式来指定字段所属表。

除此以外，还可以通过 $table 参数批量指定这些字段所属表。

添加一个 WHERE 查询条件，与其他 WHERE 条件之间以 AND 布尔运算符连接

where() 方法的参数格式是可变的，具有下列几种形式：

// 使用字符串做查询条件
$select->where('id = 1')
 
// 使用 ? 作为参数占位符
$select->where('id = ?', $id)
 
// 使用多个参数占位符
$select->where('id = ? AND level_ix > ?', $id, $level_ix)
 
// 使用数组提供多个参数占位符的值
$select->where('id = ? AND level_ix > ?', array($id, $level_ix))
 
// 使用命名参数
$select->where('id = :id AND level_ix > :level_ix', array(
    'id' => $id, 'level_ix' => $level_ix
))
 
// 使用名值对
$select->where(array('id' => $id, 'level_ix' => $level_ix));

注意：在使用命名参数时，where() 的第二个参数必须是一个名值对数组。其中键名是参数名。

在查询条件中，还可以使用“[]”来指定需要转义的字段名，例如：

$select->where('[id] = 1');
$select->where('[posts.id'] = 1');

除了字符串和数组，$cond 参数还可以是 QDB_Expr 对象，例如：

$expr = new QDB_Expr('[hits] < AVG([hits])');
$select->where($expr);

如果没有在字段名中指定表名称或者别名，则假定所有字段都是第一个通过 from() 指定的表。

更复杂的查询条件，可以使用 QDB_Cond 对象来构造。

添加一个 WHERE 查询条件，与其他 WHERE 条件之间以 OR 布尔运算符连接

参数规范参考 where() 方法。

添加关联

关联会在指定查询条件和进行递归查询时起作用。

添加一个 JOIN 数据表和字段到查询中

$table 和 $cols 参数的规则同 from()，$cond 参数的规则同 where()。

添加一个 INNER JOIN 数据表和字段到查询中

$table 和 $cols 参数的规则同 from()，$cond 参数的规则同 where()。

添加一个 LEFT JOIN 数据表和字段到查询中

$table 和 $cols 参数的规则同 from()，$cond 参数的规则同 where()。

添加一个 RIGHT JOIN 数据表和字段到查询中

$table 和 $cols 参数的规则同 from()，$cond 参数的规则同 where()。

添加一个 FULL OUTER JOIN 数据表和字段到查询中

$table 和 $cols 参数的规则同 from()，$cond 参数的规则同 where()。

添加一个 CROSS JOIN 数据表和字段到查询中

$table 和 $cols 参数的规则同 from()。

添加一个 NATURAL JOIN 数据表和字段到查询中

添加一个 UNION 查询

$select 可以是一个字符串或一个 QDB_Select 对象，或者包含上述两者的数组。

指定 GROUP BY 子句

$expr 可以是一个字符串或一个 QDB_Expr 对象，或者包含上述两者的数组。

如果需要在表达式中使用转义后的字段名，可以采用如下模式：

$select->group('SUM([hits])');

所有被 [ 和 ] 包括的字段名将自动进行转义。如果有需要，还可以进一步指定字段所属的表或表别名。

$select->group('SUM([mytable.hits])');

添加一个 HAVING 条件，与其他 HAVING 条件之间以 AND 布尔运算符连接

参数规范参考 where() 方法。

添加一个 HAVING 条件，与其他 HAVING 条件之间以 OR 布尔运算符连接

参数规范参考 where() 方法。

添加排序

$expr 可以是字符串或者 QDB_Expr 对象，例如：

$select->order('title');
$select->order('users.username DESC');
$select->order(new QDB_Expr('SUM(hits) ASC');

指示仅查询第一个符合条件的记录

指示查询所有符合条件的记录

限制查询结果总数

限定查询结果总数

设置分页查询

limitPage() 是用于分页查询的主要方法。 使用时通常只需要指定 $page 和 $page_size 参数。

$page 参数指定要查询哪一页的数据，$page_size 指定了页大小。 默认情况下，$page 为 1 时表示要查询第 1 页。

如果希望用 $page = 0 来表示查询第一页，应该指定 $base 参数为 0。

获得分页信息

要使用该方法，必须先用 limitPage() 指定有效的分页参数。

该方法返回一个数组，包含下列信息：

record_count: 符合查询条件的记录数 page_count: 按照页大小计算出来的总页数 first: 第一页的索引，等同于 limitPage() 的 $base 参数，默认为 1 last: 最后一页的索引 current: 当前页的索引 next: 下一页的索引 prev: 上一页的索引 page_size: 页大小 page_base: 页码基数（也就是第一页的索引值，默认为 1）

获得这个数组后，就可以通过 WebControls 或者其他途径构造分页导航条等用户界面内容。

在查询时，将分页信息存入 $return 参数

fetchPagination() 方法可以让开发者更连贯的操作 QDB_Select 对象。

例如：

$pagination = null; $posts = Post::find('is_published = ?', true)
->all()
->limitPage($page, $page_size)
->fetchPagination($pagination)
->query();

上述代码执行后，$pagination 将包含查询的分页信息。

是否构造一个 FOR UPDATE 查询

如果查询出记录后马上就要更新并写回数据库，则可以调用 forUpdate() 方法来指示这种情况。 此时数据库会尝试对查询出来的记录加锁，避免在数据更新回数据库之前被其他查询改变。

统计符合条件的记录数

$field 参数指定用于统计的字段或表达式。

统计符合条件的记录数，并立即返回结果

统计平均值

统计平均值，并立即返回结果

统计最大值

统计最大值，并立即返回结果

统计最小值

统计最小值，并立即返回结果

统计合计

统计合计，并立即返回结果

指示将查询结果封装为特定的 ActiveRecord 对象

通常对于从 ActiveRecord 发起的查询不需要再调用该方法，QeePHP 会确保此类查询都返回对象。 但如果是从表数据入口发起的查询，并且希望返回对象，就应该调用这个方法指定一个类名称。

类名称所指定的 ActiveRecord 继承类应该是一个适合返回结果数据结构的对象，否则会导致构造对象失败。

指示将查询结果返回为数组

指示不管查询是由什么来源发起的，都将查询结果以数组方式返回。

指示将查询结果作为 QDB_ActiveRecord_Association_Coll 集合返回

设置一个或多个字段的映射名，如果 $mapping_to 为 NULL，则取消对指定字段的映射

映射名是指可以在查询参数中使用映射名作为字段名。 QDB_Select 会负责在生成查询时将映射名转换为实际的字段名。

例如：

$select->columnMapping('title', 'post_title')
       ->where(array('post_title' => $title));
// 生成的查询条件是 `title` = {$title} 而不是 `post_title` = {$title}

设置递归关联查询的层数（默认为1层）

假设 A 关联到 B，B 关联到 C，而 C 关联到 D。则通过 recursion 参数， 我们可以指定从 A 出发的查询要到达哪一个关联层次才停止。

默认的 $recursion = 1，表示从 A 出发的查询只查询到 B 的数据就停止。

注意：对于来自 ActiveRecord 的查询，无需指定该参数。 因为可以利用 ActiveRecord 的延迟加载能力自动查询更深层次的数据。

指定使用递归查询时，需要查询哪个关联的 target_key 字段

获得用于构造查询的指定部分内容

重置整个查询对象或指定部分

执行查询并返回指定数量的结果

返回符合主键的一个结果

仅返回一个结果

执行查询并返回所有结果，等同于 ->all()->query()

执行查询

$included_links 用于指定查询时要包含的关联。

默认情况下，QDB_Select 对象会以数组形式返回查询结果。 在这种模式下，关联的数据会被立即查询出来，并嵌入查询结果中。

如果指定 QDB_Select 以 ActiveRecord 对象返回查询结果，则只有 $included_links 指定的关联会被立即查询。 否则在第一次访问返回的 ActiveRecord 对象的聚合属性时，才会进行关联对象的查询。

执行查询，返回结果句柄

获得查询字符串

魔法方法

查询，并返回数组结果

查询，并返回对象或对象集合

构造 DISTINCT 子句

构造查询字段子句

构造集合查询字段

构造 FROM 子句

构造 UNION 查询

构造 WHERE 子句

构造 GROUP 子句

构造 HAVING 子句

构造 ORDER 子句

构造 FOR UPDATE 子句

添加一个 JOIN

添加到内部的数据表->字段名映射数组

添加查询条件的内容方法

添加一个集合查询

获得当前表的名称

回调函数，用于分析查询中包含的关联表名称