类 UpdateQuery
此类用于为关系数据库生成 UPDATE 查询。
常量
属性摘要
-
$_connection 受保护
Cake\Database\Connection
用于执行此查询的连接实例。
-
$_dirty 受保护
布尔值
指示此查询的内部状态是否已更改,这用于丢弃内部缓存的对象,例如转换后的查询或对已执行语句的引用。
-
Cake\Database\FunctionsBuilder|null
用于生成任意 SQL 函数的函数构建器对象的实例。
-
$_parts 受保护
array<string, mixed>
将用于构建此查询的 SQL 部分列表。
-
$_statement 受保护
Cake\Database\StatementInterface|null
-
$_type 受保护
字符串
此查询的类型。
-
$_typeMap 受保护
Cake\Database\TypeMap|null
-
$_valueBinder 受保护
Cake\Database\ValueBinder|null
负责生成查询占位符并临时存储与每个占位符相关联的值的对象。
-
$connectionRole 受保护
字符串
连接角色 ('read' 或 'write')
方法摘要
-
__clone() 公共
处理清除迭代器并克隆所有表达式和值绑定器。
-
__construct() 公共
构造函数。
-
__debugInfo() 公共
返回一个可以用于描述此对象内部状态的数组。
-
__toString() 公共
返回此查询的字符串表示形式(完整的 SQL 语句)。
-
_conjugate() 受保护
用于通过组合 QueryExpression 对象构建条件的辅助函数。
-
_dirty() 受保护
将查询标记为脏,从内存缓存中删除任何预处理信息。
-
_expressionsVisitor() 受保护
traverseExpressions() 使用的查询部分遍历方法
-
_makeJoin() 受保护
返回一个可以传递到 join 方法的数组,该数组描述单个连接子句
-
andWhere() 公共
使用 AND 运算符将任何先前定义的条件集连接到提供的列表。此函数以与方法
where
相同的格式接受条件列表,因此您可以使用数组、表达式对象回调函数或字符串。 -
bind() 公共
将查询占位符与值和类型关联。
-
clause() 公共
返回存储在指定子句中的任何数据。这对于修改查询的任何内部部分很有用,并且 SQL 方言使用它在查询执行之前相应地转换查询。可以检索的有效子句是:delete、update、set、insert、values、select、distinct、from、join、set、where、group、having、order、limit、offset、union 和 intersect。
-
comment() 公共
一个字符串或表达式,它将被追加到生成的查询中作为注释
-
epilog() 公共
一个字符串或表达式,它将被追加到生成的查询中
-
execute() 公共
编译此查询的 SQL 表示形式,并使用配置的连接对象执行它。返回结果语句对象。
-
expr() 公共
返回一个新的 QueryExpression 对象。当使用流畅的接口构建复杂查询时,这是一个方便的函数。您也可以在子类中覆盖此函数,以在需要时使用更专业的 QueryExpression 类。
-
from() 公共
添加一个或多个表,这些表将在此查询的 FROM 子句中使用。表可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。
-
func() 公共
返回函数构建器对象的实例,该实例可用于生成任意 SQL 函数。
-
getConnection() 公共
获取用于执行和转换此查询的连接实例。
-
getConnectionRole() 公共
返回连接角色 ('read' 或 'write')
-
getDefaultTypes() 公共
获取当前类型映射的默认类型。
-
getTypeMap() 公共
返回现有的类型映射。
-
getValueBinder() 公共
返回当前使用的 ValueBinder 实例。
-
identifier() 公共
创建一个引用标识符的表达式。标识符用于引用字段名称,并允许 SQL 编译器应用引号或转义标识符。
-
innerJoin() 公共
向查询添加单个
INNER JOIN
子句。 -
join() 公共
添加一个或多个表,这些表将用作此查询的 JOIN 子句。表可以作为字符串数组、描述连接部分的数组、包含多个连接描述的数组或单个字符串传递。
-
leftJoin() 公共
向查询添加单个
LEFT JOIN
子句。 -
limit() 公共
设置应从数据库中检索的记录数,接受一个整数或一个表达式对象,该对象计算为整数。在某些数据库中,此操作可能不受支持,或者需要转换查询才能限制结果集大小。
-
modifier() 公共
添加一个或多个
SELECT
修饰符,这些修饰符将用于SELECT
中。 -
newExpr() 公共
返回一个新的 QueryExpression 对象。当使用流畅的接口构建复杂查询时,这是一个方便的函数。您也可以在子类中覆盖此函数,以在需要时使用更专业的 QueryExpression 类。
-
offset() 公共
设置应从原始结果集中跳过的记录数。这通常用于对大型结果进行分页。接受一个整数或一个表达式对象,该对象计算为整数。
-
order() 公共 已弃用
添加一个或多个字段,这些字段将在此查询的 ORDER 子句中使用。字段可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。
-
orderAsc() 公共 已弃用
添加一个带有 ASC 方向的 ORDER BY 子句。
-
orderBy() 公共
添加一个或多个字段,这些字段将在此查询的 ORDER 子句中使用。字段可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。
-
orderByAsc() 公共
添加一个带有 ASC 方向的 ORDER BY 子句。
-
orderByDesc() 公共
添加一个带有 DESC 方向的 ORDER BY 子句。
-
orderDesc() 公共 已弃用
添加一个带有 DESC 方向的 ORDER BY 子句。
-
page() 公共
设置所需的页面结果。
-
removeJoin() 公共
删除已定义的连接。
-
rightJoin() 公共
向查询添加单个
RIGHT JOIN
子句。 -
rowCountAndClose() public
执行此查询的 SQL 语句,并在返回更改的记录行数之前立即关闭语句。
-
set() public
设置一个或多个要更新的字段。
-
setConnection() public
设置用于执行和转换此查询的连接实例。
-
setDefaultTypes() public
覆盖实现对象中字段的默认类型映射。
-
setTypeMap() public
如果 $typeMap 是数组,则创建新的 TypeMap,否则将其替换为给定的 TypeMap。
-
setValueBinder() public
覆盖当前的值绑定器
-
sql() public
返回此对象的 SQL 表示形式。
-
traverse() public
将遍历每个指定的部件。遍历函数可以使用闭包中的变量或实例变量来聚合结果。此函数通常用作遍历将用于构建查询的所有查询部件的方法。
-
traverseExpressions() public
此函数的工作原理类似于 traverse() 函数,不同之处在于它对整个表达式树进行全深度遍历。这将对存储在此查询中的每个 ExpressionInterface 对象执行提供的回调函数,无论其在查询的任何部分中嵌套到任何深度。
-
traverseParts() public
将遍历提供的部件。
-
type() public
返回此查询的类型(select、insert、update、delete)
-
update() public
创建一个更新查询。
-
where() public
添加将用于此查询 WHERE 子句的条件或条件集。条件可以表示为以字段为键的数组,其中包含比较运算符,数组的值将用于将字段与该字面量进行比较。最后,条件可以表示为单个字符串或字符串数组。
-
whereInList() public
添加将用于此查询 WHERE 子句的 IN 条件或条件集。
-
whereNotInList() public
添加将用于此查询 WHERE 子句的 NOT IN 条件或条件集。
-
whereNotInListOrNull() public
添加将用于此查询 WHERE 子句的 NOT IN 条件或条件集。这也允许该字段使用 IS NULL 条件为 null,因为 null 值会导致 NOT IN 条件始终失败。
-
whereNotNull() public
为查询添加 NOT NULL 条件的便捷方法
-
whereNull() public
为查询添加 IS NULL 条件的便捷方法
-
with() public
向查询添加新的公用表表达式 (CTE)。
方法详情
__construct() ¶ public
__construct(Cake\Database\Connection $connection)
构造函数。
参数
-
Cake\Database\Connection
$connection 要用于转换和执行此查询的连接对象
__debugInfo() ¶ public
__debugInfo(): array<string, mixed>
返回一个可以用于描述此对象内部状态的数组。
返回值
array<string, mixed>
_conjugate() ¶ protected
_conjugate(string $part, Cake\Database\ExpressionInterfaceClosure|array|string|null $append, string $conjunction, array<string, string> $types): void
用于通过组合 QueryExpression 对象构建条件的辅助函数。
参数
-
string
$part 要将新部件追加到的查询部件名称
-
Cake\Database\ExpressionInterfaceClosure|array|string|null
$append 要追加的表达式或构建函数。
-
string
$conjunction 用于操作部件的连接类型
-
array<string, string>
$types 用于将值绑定到查询的类型名称的关联数组
返回值
void
_expressionsVisitor() ¶ protected
_expressionsVisitor(mixed $expression, Closure $callback): void
traverseExpressions() 使用的查询部分遍历方法
参数
-
mixed
$expression 查询表达式或表达式数组。
-
Closure
$callback 将对在此查询中找到的每个 ExpressionInterface 执行的回调函数。
返回值
void
_makeJoin() ¶ protected
_makeJoin(array<string, mixed>|string $table, Cake\Database\ExpressionInterfaceClosure|array|string $conditions, string $type): array
返回一个可以传递到 join 方法的数组,该数组描述单个连接子句
参数
-
array<string, mixed>|string
$table 要连接的表
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions 用于连接的条件。
-
string
$type 要使用的连接类型
返回值
array
andWhere() ¶ public
andWhere(Cake\Database\ExpressionInterfaceClosure|array|string $conditions, array<string, string> $types = []): $this
使用 AND 运算符将任何先前定义的条件集连接到提供的列表。此函数以与方法 where
相同的格式接受条件列表,因此您可以使用数组、表达式对象回调函数或字符串。
重要的是要注意,调用此函数时,为该查询定义的任何先前条件集都将被视为 AND 运算符的单个参数。此函数不仅会对最近定义的条件进行操作,还会对所有条件作为一个整体进行操作。
当使用数组定义条件时,为每个数组条目创建约束将使用与 where()
函数相同的逻辑。这意味着每个数组条目都将使用 AND 运算符连接到其他条目,除非您使用其他运算符在数组中嵌套条件。
示例
$query->where(['title' => 'Hello World')->andWhere(['author_id' => 1]);
将产生
WHERE title = 'Hello World' AND author_id = 1
$query
->where(['OR' => ['published' => false, 'published is NULL']])
->andWhere(['author_id' => 1, 'comments_count >' => 10])
生成
WHERE (published = 0 OR published IS NULL) AND author_id = 1 AND comments_count > 10
$query
->where(['title' => 'Foo'])
->andWhere(function ($exp, $query) {
return $exp
->or(['author_id' => 1])
->add(['author_id' => 2]);
});
生成以下条件
WHERE (title = 'Foo') AND (author_id = 1 OR author_id = 2)
参数
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions 要使用 AND 添加的条件。
-
array<string, string>
$types optional 用于将值绑定到查询的类型名称的关联数组
返回值
$this
另请参阅
\Cake\Database\TypeFactory
bind() ¶ public
bind(string|int $param, mixed $value, string|int|null $type = null): $this
将查询占位符与值和类型关联。
$query->bind(':id', 1, 'integer');
参数
-
string|int
$param 要替换为 $value 的带引号版本的占位符
-
mixed
$value 要绑定的值
-
string|int|null
$type optional 映射的类型名称,用于在发送到数据库时进行转换
返回值
$this
clause() ¶ public
clause(string $name): mixed
返回存储在指定子句中的任何数据。这对于修改查询的任何内部部分很有用,并且 SQL 方言使用它在查询执行之前相应地转换查询。可以检索的有效子句是:delete、update、set、insert、values、select、distinct、from、join、set、where、group、having、order、limit、offset、union 和 intersect。
这些部件的每个部件的返回值可能会有所不同。一些子句使用 QueryExpression 来内部存储其状态,一些子句使用数组,另一些子句可能使用布尔值或整数。这是每个子句的返回值类型的摘要。
- update: string 要更新的表的名称
- set: QueryExpression
- insert: array,将返回包含表 + 列的数组。
- values: ValuesExpression
- select: array,当未设置字段时将返回空数组
- distinct: boolean
- from: 表的数组
- join: array
- set: array
- where: QueryExpression,当未设置时返回 null
- group: array
- having: QueryExpression,当未设置时返回 null
- order: OrderByExpression,当未设置时返回 null
- limit: integer 或 QueryExpression,当未设置时为 null
- offset: integer 或 QueryExpression,当未设置时为 null
- union: array
- intersect: array
参数
-
string
$name 要返回的子句的名称
返回值
mixed
抛出
InvalidArgumentException
当命名子句不存在时。
comment() ¶ public
comment(string|null $expression = null): $this
一个字符串或表达式,它将被追加到生成的查询中作为注释
示例
$query->select('id')->where(['author_id' => 1])->comment('Filter for admin user');
注释内容是原始 SQL,不适合与用户提供的数据一起使用。
参数
-
string|null
$expression optional 要添加的注释
返回值
$this
epilog() ¶ public
epilog(Cake\Database\ExpressionInterface|string|null $expression = null): $this
一个字符串或表达式,它将被追加到生成的查询中
示例
$query->select('id')->where(['author_id' => 1])->epilog('FOR UPDATE');
$query
->insert('articles', ['title'])
->values(['author_id' => 1])
->epilog('RETURNING id');
Epliog 内容是原始 SQL,不适合与用户提供的数据一起使用。
参数
-
Cake\Database\ExpressionInterface|string|null
$expression optional 要追加的表达式
返回值
$this
execute() ¶ public
execute(): Cake\Database\StatementInterface
编译此查询的 SQL 表示形式,并使用配置的连接对象执行它。返回结果语句对象。
内部执行查询会执行多个步骤,第一个步骤是让连接转换此对象以适合其特定的方言,这可能会导致生成不同的 Query 对象,该对象将是实际执行的对象。紧随其后的是将字面量值传递给连接,以便以安全的方式将其绑定到查询。最后,结果语句用自定义对象修饰,以根据需要为检索的每一行执行回调函数。
结果语句是可遍历的,因此可以在任何循环中使用它,就像使用数组一样。
此方法可以在查询子类中被覆盖,以修饰围绕查询执行的行为。
返回值
Cake\Database\StatementInterface
expr() ¶ public
expr(Cake\Database\ExpressionInterface|array|string|null $rawExpression = null): Cake\Database\Expression\QueryExpression
返回一个新的 QueryExpression 对象。当使用流畅的接口构建复杂查询时,这是一个方便的函数。您也可以在子类中覆盖此函数,以在需要时使用更专业的 QueryExpression 类。
您可以选择传递单个原始 SQL 字符串或一个数组,或者以 \Cake\Database\Expression\QueryExpression 接受的任何格式传递表达式。
$expression = $query->expr(); // Returns an empty expression object
$expression = $query->expr('Table.column = Table2.column'); // Return a raw SQL expression
参数
-
Cake\Database\ExpressionInterface|array|string|null
$rawExpression 可选 字符串、数组或您想要包装在表达式对象中的任何内容
返回值
Cake\Database\Expression\QueryExpression
from() ¶ public
from(array|string $tables = [], bool $overwrite = false): $this
添加一个或多个表,这些表将在此查询的 FROM 子句中使用。表可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。
如果传递的是数组,则键将用于使用值作为要别名的真实字段来别名表。可以别名字符串、ExpressionInterface 对象甚至其他 Query 对象。
默认情况下,此函数会将任何传递的参数追加到要从中选择的表列表中,除非第二个参数设置为 true。
此方法可用于 select、update 和 delete 语句。
示例
$query->from(['p' => 'posts']); // Produces FROM posts p
$query->from('authors'); // Appends authors: FROM posts p, authors
$query->from(['products'], true); // Resets the list: FROM products
$query->from(['sub' => $countQuery]); // FROM (SELECT ...) sub
参数
-
array|string
$tables 可选 要添加到列表中的表。此参数可以作为字符串数组、表达式对象数组或单个字符串传递。有关有效的调用类型,请参阅上面的示例。
-
bool
$overwrite 可选 是否使用传递的列表重置表
返回值
$this
func() ¶ public
func(): Cake\Database\FunctionsBuilder
返回函数构建器对象的实例,该实例可用于生成任意 SQL 函数。
示例
$query->func()->count('*');
$query->func()->dateDiff(['2012-01-05', '2012-01-02'])
返回值
Cake\Database\FunctionsBuilder
getConnection() ¶ public
getConnection(): Cake\Database\Connection
获取用于执行和转换此查询的连接实例。
返回值
Cake\Database\Connection
getDefaultTypes() ¶ public
getDefaultTypes(): array<int|string, string>
获取当前类型映射的默认类型。
返回值
array<int|string, string>
getValueBinder() ¶ public
getValueBinder(): Cake\Database\ValueBinder
返回当前使用的 ValueBinder 实例。
ValueBinder 负责生成查询占位符并将值临时与这些占位符关联,以便能够正确地将它们传递给语句对象。
返回值
Cake\Database\ValueBinder
identifier() ¶ public
identifier(string $identifier): Cake\Database\ExpressionInterface
创建一个引用标识符的表达式。标识符用于引用字段名称,并允许 SQL 编译器应用引号或转义标识符。
该值按原样使用,您可能需要在标识符中使用别名或包含表引用。不要使用此方法注入 SQL 方法或逻辑语句。
示例
$query->newExpr()->lte('count', $query->identifier('total'));
参数
-
string
$identifier 表达式的标识符
返回值
Cake\Database\ExpressionInterface
innerJoin() ¶ public
innerJoin(array<string, mixed>|string $table, Cake\Database\ExpressionInterfaceClosure|array|string $conditions = [], array<string, string> $types = []): $this
向查询添加单个 INNER JOIN
子句。
这是通过 join()
构建连接的简写方法。
此方法的参数与 leftJoin()
简写相同,有关更多详细信息,请参阅该方法的描述。
参数
-
array<string, mixed>|string
$table 要连接的表
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions 可选 用于连接的条件。
-
array<string, string>
$types optional 与用于将值转换为相应数据库表示的条件关联的类型列表。
返回值
$this
join() ¶ public
join(array<string, mixed>|string $tables, array<string, string> $types = [], bool $overwrite = false): $this
添加一个或多个表,这些表将用作此查询的 JOIN 子句。表可以作为字符串数组、描述连接部分的数组、包含多个连接描述的数组或单个字符串传递。
默认情况下,此函数会将任何传递的参数追加到要连接的表列表中,除非第三个参数设置为 true。
当未指定连接类型时,默认情况下使用 INNER JOIN
:$query->join(['authors'])
将产生 INNER JOIN authors ON 1 = 1
也可以使用数组键来别名连接:$query->join(['a' => 'authors'])
将产生 INNER JOIN authors a ON 1 = 1
可以使用数组符号来完全描述和别名连接
$query->join([
'a' => [
'table' => 'authors',
'type' => 'LEFT',
'conditions' => 'a.id = b.author_id'
]
]);
// Produces LEFT JOIN authors a ON a.id = b.author_id
您甚至可以在数组中指定多个连接,包括完整描述
$query->join([
'a' => [
'table' => 'authors',
'type' => 'LEFT',
'conditions' => 'a.id = b.author_id'
],
'p' => [
'table' => 'publishers',
'type' => 'INNER',
'conditions' => 'p.id = b.publisher_id AND p.name = "Cake Software Foundation"'
]
]);
// LEFT JOIN authors a ON a.id = b.author_id
// INNER JOIN publishers p ON p.id = b.publisher_id AND p.name = "Cake Software Foundation"
使用条件和类型
条件可以用字符串来表达,如上面的示例所示,用于比较列,或者使用已经引用的文字值的字符串。此外,可以使用数组或表达式对象中表达的条件。
使用数组来表达条件时,通常希望将文字值转换为正确的数据库表示形式。这是通过此函数的第二个参数实现的。
$query->join(['a' => [
'table' => 'articles',
'conditions' => [
'a.posted >=' => new DateTime('-3 days'),
'a.published' => true,
'a.author_id = authors.id'
]
]], ['a.posted' => 'datetime', 'a.published' => 'boolean'])
覆盖连接
使用数组符号创建别名连接时,可以通过在对该函数的后续调用中使用相同的别名来覆盖先前的连接定义,或者如果该函数的第三个参数设置为 true,则可以使用另一个列表替换所有先前定义的连接。
$query->join(['alias' => 'table']); // joins table with as alias
$query->join(['alias' => 'another_table']); // joins another_table with as alias
$query->join(['something' => 'different_table'], [], true); // resets joins list
参数
-
array<string, mixed>|string
$tables 查询中要连接的表列表
-
array<string, string>
$types optional 用于将值绑定到查询的类型名称的关联数组
-
bool
$overwrite 可选 是否使用传递的列表重置连接
返回值
$this
另请参阅
leftJoin() ¶ public
leftJoin(array<string, mixed>|string $table, Cake\Database\ExpressionInterfaceClosure|array|string $conditions = [], array $types = []): $this
向查询添加单个 LEFT JOIN
子句。
这是通过 join()
构建连接的简写方法。
表名可以作为字符串传递,或者在需要别名的情况下作为数组传递
// LEFT JOIN authors ON authors.id = posts.author_id
$query->leftJoin('authors', 'authors.id = posts.author_id');
// LEFT JOIN authors a ON a.id = posts.author_id
$query->leftJoin(['a' => 'authors'], 'a.id = posts.author_id');
条件可以作为字符串、数组或表达式对象传递。使用数组时,可以将它们与 $types
参数结合起来,以定义如何转换值
$query->leftJoin(['a' => 'articles'], [
'a.posted >=' => new DateTime('-3 days'),
'a.published' => true,
'a.author_id = authors.id'
], ['a.posted' => 'datetime', 'a.published' => 'boolean']);
有关条件和类型的更多详细信息,请参阅 join()
。
参数
-
array<string, mixed>|string
$table 要连接的表
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions 可选 用于连接的条件。
-
array
$types 可选 与用于将值转换为相应数据库表示的条件关联的类型列表。
返回值
$this
limit() ¶ public
limit(Cake\Database\ExpressionInterface|int|null $limit): $this
设置应从数据库中检索的记录数,接受一个整数或一个表达式对象,该对象计算为整数。在某些数据库中,此操作可能不受支持,或者需要转换查询才能限制结果集大小。
示例
$query->limit(10) // generates LIMIT 10
$query->limit($query->newExpr()->add(['1 + 1'])); // LIMIT (1 + 1)
参数
-
Cake\Database\ExpressionInterface|int|null
$limit 要返回的记录数
返回值
$this
modifier() ¶ public
modifier(Cake\Database\ExpressionInterface|array|string $modifiers, bool $overwrite = false): $this
添加一个或多个 SELECT
修饰符,这些修饰符将用于 SELECT
中。
默认情况下,此函数会将任何传递的参数追加到要应用的修饰符列表中,除非第二个参数设置为 true。
示例
// Ignore cache query in MySQL
$query->select(['name', 'city'])->from('products')->modifier('SQL_NO_CACHE');
// It will produce the SQL: SELECT SQL_NO_CACHE name, city FROM products
// Or with multiple modifiers
$query->select(['name', 'city'])->from('products')->modifier(['HIGH_PRIORITY', 'SQL_NO_CACHE']);
// It will produce the SQL: SELECT HIGH_PRIORITY SQL_NO_CACHE name, city FROM products
参数
-
Cake\Database\ExpressionInterface|array|string
$modifiers 要应用于查询的修饰符
-
bool
$overwrite 可选 是否使用字段列表重置顺序
返回值
$this
newExpr() ¶ public
newExpr(Cake\Database\ExpressionInterface|array|string|null $rawExpression = null): Cake\Database\Expression\QueryExpression
返回一个新的 QueryExpression 对象。当使用流畅的接口构建复杂查询时,这是一个方便的函数。您也可以在子类中覆盖此函数,以在需要时使用更专业的 QueryExpression 类。
您可以选择传递单个原始 SQL 字符串或一个数组,或者以 \Cake\Database\Expression\QueryExpression 接受的任何格式传递表达式。
$expression = $query->expr(); // Returns an empty expression object
$expression = $query->expr('Table.column = Table2.column'); // Return a raw SQL expression
参数
-
Cake\Database\ExpressionInterface|array|string|null
$rawExpression 可选 字符串、数组或您想要包装在表达式对象中的任何内容
返回值
Cake\Database\Expression\QueryExpression
offset() ¶ public
offset(Cake\Database\ExpressionInterface|int|null $offset): $this
设置应从原始结果集中跳过的记录数。这通常用于对大型结果进行分页。接受一个整数或一个表达式对象,该对象计算为整数。
在某些数据库中,此操作可能不受支持,或者需要转换查询才能限制结果集的大小。
示例
$query->offset(10) // generates OFFSET 10
$query->offset($query->newExpr()->add(['1 + 1'])); // OFFSET (1 + 1)
参数
-
Cake\Database\ExpressionInterface|int|null
$offset 要跳过的记录数
返回值
$this
order() ¶ public
order(Cake\Database\ExpressionInterfaceClosure|array|string $fields, bool $overwrite = false): $this
添加一个或多个字段,这些字段将在此查询的 ORDER 子句中使用。字段可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。
如果传递的是数组,则键将用作字段本身,而值将表示该字段应排序的顺序。当使用相同的字段作为键多次调用时,最后一个排序定义将优先于其他排序定义。
默认情况下,此函数会将任何传递的参数追加到要选择的字段列表中,除非第二个参数设置为 true。
示例
$query->orderBy(['title' => 'DESC', 'author_id' => 'ASC']);
生成
ORDER BY title DESC, author_id ASC
$query
->orderBy(['title' => $query->newExpr('DESC NULLS FIRST')])
->orderBy('author_id');
将生成
ORDER BY title DESC NULLS FIRST, author_id
$expression = $query->newExpr()->add(['id % 2 = 0']);
$query->orderBy($expression)->orderBy(['title' => 'ASC']);
和
$query->orderBy(function ($exp, $query) {
return [$exp->add(['id % 2 = 0']), 'title' => 'ASC'];
});
都将变为
ORDER BY (id %2 = 0), title ASC
排序字段/方向不受查询构建器的清理。在将用户提供的數據傳遞給 order()
時,您應該使用允許的字段/方向清單。
如果您需要將複雜的表達式設置為排序條件,則應使用 orderByAsc()
或 orderByDesc()
。
参数
-
Cake\Database\ExpressionInterfaceClosure|array|string
$fields 要添加到列表中的字段
-
bool
$overwrite 可选 是否使用字段列表重置顺序
返回值
$this
orderAsc() ¶ public
orderAsc(Cake\Database\ExpressionInterfaceClosure|string $field, bool $overwrite = false): $this
添加一个带有 ASC 方向的 ORDER BY 子句。
此方法允许您设置复杂的表达式作为排序条件,这与 order() 不同
排序字段不适合与用户提供的數據一起使用,因为它们不受查询构建器的清理。
参数
-
Cake\Database\ExpressionInterfaceClosure|string
$field 要排序的字段。
-
bool
$overwrite 可选 是否重置排序子句。
返回值
$this
orderBy() ¶ public
orderBy(Cake\Database\ExpressionInterfaceClosure|array|string $fields, bool $overwrite = false): $this
添加一个或多个字段,这些字段将在此查询的 ORDER 子句中使用。字段可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。
如果传递的是数组,则键将用作字段本身,而值将表示该字段应排序的顺序。当使用相同的字段作为键多次调用时,最后一个排序定义将优先于其他排序定义。
默认情况下,此函数会将任何传递的参数追加到要选择的字段列表中,除非第二个参数设置为 true。
示例
$query->orderBy(['title' => 'DESC', 'author_id' => 'ASC']);
生成
ORDER BY title DESC, author_id ASC
$query
->orderBy(['title' => $query->newExpr('DESC NULLS FIRST')])
->orderBy('author_id');
将生成
ORDER BY title DESC NULLS FIRST, author_id
$expression = $query->newExpr()->add(['id % 2 = 0']);
$query->orderBy($expression)->orderBy(['title' => 'ASC']);
和
$query->orderBy(function ($exp, $query) {
return [$exp->add(['id % 2 = 0']), 'title' => 'ASC'];
});
都将变为
ORDER BY (id %2 = 0), title ASC
排序字段/方向不受查询构建器的清理。在将用户提供的數據傳遞給 order()
時,您應該使用允許的字段/方向清單。
如果您需要將複雜的表達式設置為排序條件,則應使用 orderByAsc()
或 orderByDesc()
。
参数
-
Cake\Database\ExpressionInterfaceClosure|array|string
$fields 要添加到列表中的字段
-
bool
$overwrite 可选 是否使用字段列表重置顺序
返回值
$this
orderByAsc() ¶ public
orderByAsc(Cake\Database\ExpressionInterfaceClosure|string $field, bool $overwrite = false): $this
添加一个带有 ASC 方向的 ORDER BY 子句。
此方法允许您设置复杂的表达式作为排序条件,这与 order() 不同
排序字段不适合与用户提供的數據一起使用,因为它们不受查询构建器的清理。
参数
-
Cake\Database\ExpressionInterfaceClosure|string
$field 要排序的字段。
-
bool
$overwrite 可选 是否重置排序子句。
返回值
$this
orderByDesc() ¶ public
orderByDesc(Cake\Database\ExpressionInterfaceClosure|string $field, bool $overwrite = false): $this
添加一个带有 DESC 方向的 ORDER BY 子句。
此方法允许您设置复杂的表达式作为排序条件,这与 order() 不同
排序字段不适合与用户提供的數據一起使用,因为它们不受查询构建器的清理。
参数
-
Cake\Database\ExpressionInterfaceClosure|string
$field 要排序的字段。
-
bool
$overwrite 可选 是否重置排序子句。
返回值
$this
orderDesc() ¶ public
orderDesc(Cake\Database\ExpressionInterfaceClosure|string $field, bool $overwrite = false): $this
添加一个带有 DESC 方向的 ORDER BY 子句。
此方法允许您设置复杂的表达式作为排序条件,这与 order() 不同
排序字段不适合与用户提供的數據一起使用,因为它们不受查询构建器的清理。
参数
-
Cake\Database\ExpressionInterfaceClosure|string
$field 要排序的字段。
-
bool
$overwrite 可选 是否重置排序子句。
返回值
$this
page() ¶ public
page(int $num, int|null $limit = null): $this
设置所需的页面结果。
此方法提供了一个更易于使用的界面来设置您想要的记录集中要作为结果的 limit + offset。如果为空,limit 将默认为现有的 limit 子句,如果该子句也为空,则使用 25
。
页码必须从 1 开始。
参数
-
int
$num 您想要的页码。
-
int|null
$limit 可选 您想要在页面中显示的行数。如果为 null,将使用当前的 limit 子句。
返回值
$this
抛出
InvalidArgumentException
如果页码 < 1。
removeJoin() ¶ public
removeJoin(string $name): $this
删除已定义的连接。
当您重新定义连接或希望重新排列连接子句时很有用。
参数
-
string
$name 要删除的连接的别名/名称。
返回值
$this
rightJoin() ¶ public
rightJoin(array<string, mixed>|string $table, Cake\Database\ExpressionInterfaceClosure|array|string $conditions = [], array $types = []): $this
向查询添加单个 RIGHT JOIN
子句。
这是通过 join()
构建连接的简写方法。
此方法的参数与 leftJoin()
的简写相同,请参阅该方法的描述以获取更多详细信息。
参数
-
array<string, mixed>|string
$table 要连接的表
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions 可选 用于连接的条件。
-
array
$types 可选 与用于将值转换为相应数据库表示的条件关联的类型列表。
返回值
$this
rowCountAndClose() ¶ public
rowCountAndClose(): int
执行此查询的 SQL 语句,并在返回更改的记录行数之前立即关闭语句。
此方法可用于 UPDATE 和 DELETE 查询,但不建议用于 SELECT 查询,也不用于统计记录数。
示例
$rowCount = $query->update('articles')
->set(['published'=>true])
->where(['published'=>false])
->rowCountAndClose();
上面的示例将所有设置为 false 的 published 列更改为 true,并返回已更新的记录数。
返回值
int
set() ¶ public
set(Cake\Database\Expression\QueryExpressionClosure|array|string $key, mixed $value = null, array<string, string>|string $types = []): $this
设置一个或多个要更新的字段。
示例
传递字符串
$query->update('articles')->set('title', 'The Title');
传递数组
$query->update('articles')->set(['title' => 'The Title'], ['title' => 'string']);
传递回调函数
$query->update('articles')->set(function (ExpressionInterface $exp) {
return $exp->eq('title', 'The title', 'string');
});
参数
-
Cake\Database\Expression\QueryExpressionClosure|array|string
$key 要设置的列名或键数组
- 要设置的值。这也可以是一个包含 SQL 片段的 QueryExpression。它也可以是一个 Closure,它需要返回一个表达式对象。
-
mixed
$value 可选 将 $key 更新为的值。如果 $key 是数组或 QueryExpression,则可以为 null。当 $key 是数组时,此参数将用作 $types。
-
array<string, string>|string
$types 可选 用于处理数据的列类型。
返回值
$this
setConnection() ¶ public
setConnection(Cake\Database\Connection $connection): $this
设置用于执行和转换此查询的连接实例。
参数
-
Cake\Database\Connection
$connection 连接实例
返回值
$this
setDefaultTypes() ¶ public
setDefaultTypes(array<int|string, string> $types): $this
覆盖实现对象中字段的默认类型映射。
如果您需要设置在查询中的多个函数/表达式之间共享的类型映射,此方法很有用。
要添加默认值而不覆盖现有值,请使用 getTypeMap()->addDefaults()
参数
-
array<int|string, string>
$types 要设置的类型数组。
返回值
$this
另请参阅
setTypeMap() ¶ public
setTypeMap(Cake\Database\TypeMap|array $typeMap): $this
如果 $typeMap 是数组,则创建新的 TypeMap,否则将其替换为给定的 TypeMap。
参数
-
Cake\Database\TypeMap|array
$typeMap 如果为数组,则创建一个 TypeMap,否则设置给定的 TypeMap
返回值
$this
setValueBinder() ¶ public
setValueBinder(Cake\Database\ValueBinder|null $binder): $this
覆盖当前的值绑定器
ValueBinder 负责生成查询占位符并将值临时与这些占位符关联,以便能够正确地将它们传递给语句对象。
参数
-
Cake\Database\ValueBinder|null
$binder 绑定器或 null 用于禁用绑定。
返回值
$this
sql() ¶ public
sql(Cake\Database\ValueBinder|null $binder = null): string
返回此对象的 SQL 表示形式。
此函数将编译此查询,使其与连接使用的 SQL 方言兼容。此过程可能会添加、删除或更改任何查询部分或内部表达式,使其在目标平台上可执行。
生成的查询可能包含占位符,这些占位符将在执行查询时替换为实际值,因此最适合与预处理语句一起使用。
参数
-
Cake\Database\ValueBinder|null
$binder 可选 生成参数占位符的值绑定器
返回值
字符串
traverse() ¶ public
traverse(Closure $callback): $this
将遍历每个指定的部件。遍历函数可以使用闭包中的变量或实例变量来聚合结果。此函数通常用作遍历将用于构建查询的所有查询部件的方法。
回调函数将接收两个参数,第一个是正在迭代的查询部分的值,第二个是该部分的名称。
示例
$query->select(['title'])->from('articles')->traverse(function ($value, $clause) {
if ($clause === 'select') {
var_dump($value);
}
});
参数
-
Closure
$callback 为每个部分执行的回调函数
返回值
$this
traverseExpressions() ¶ public
traverseExpressions(Closure $callback): $this
此函数的工作原理类似于 traverse() 函数,不同之处在于它对整个表达式树进行全深度遍历。这将对存储在此查询中的每个 ExpressionInterface 对象执行提供的回调函数,无论其在查询的任何部分中嵌套到任何深度。
回调函数将以当前访问的表达式作为第一个参数接收。
参数
-
Closure
$callback 为在此查询中找到的每个 ExpressionInterface 执行的函数。
返回值
$this
traverseParts() ¶ public
traverseParts(Closure $visitor, list<string> $parts): $this
将遍历提供的部件。
遍历函数可以使用闭包中的变量或实例变量聚合结果。此方法可用于遍历查询部分的子集以渲染 SQL 查询。
回调函数将接收两个参数,第一个是正在迭代的查询部分的值,第二个是该部分的名称。
示例
$query->select(['title'])->from('articles')->traverse(function ($value, $clause) {
if ($clause === 'select') {
var_dump($value);
}
}, ['select', 'from']);
参数
-
Closure
$visitor 为每个部分执行的回调函数
-
list<string>
$parts 要遍历的查询部分列表
返回值
$this
update() ¶ public
update(Cake\Database\ExpressionInterface|string $table): $this
创建一个更新查询。
可以与 set() 和 where() 方法结合使用以创建 update 查询。
参数
-
Cake\Database\ExpressionInterface|string
$table 要更新的表。
返回值
$this
where() ¶ public
where(Cake\Database\ExpressionInterfaceClosure|array|string|null $conditions = null, array<string, string> $types = [], bool $overwrite = false): $this
添加将用于此查询 WHERE 子句的条件或条件集。条件可以表示为以字段为键的数组,其中包含比较运算符,数组的值将用于将字段与该字面量进行比较。最后,条件可以表示为单个字符串或字符串数组。
使用数组时,每个条目将使用 AND
运算符与其余条件连接起来。对该函数的连续调用也将使用 AND 运算符连接指定的新的条件。此外,值可以使用表达式对象表示,这些对象可以包含其他查询对象。
使用此方法创建的任何条件都可以在任何 SELECT
、UPDATE
和 DELETE
类型查询中使用。
使用运算符的条件
$query->where([
'posted >=' => new DateTime('3 days ago'),
'title LIKE' => 'Hello W%',
'author_id' => 1,
], ['posted' => 'datetime']);
前面的示例产生
WHERE posted >= 2012-01-27 AND title LIKE 'Hello W%' AND author_id = 1
第二个参数用于指定每个传递键的预期类型。有效类型可以使用与 Database\Type 类映射的类型。
使用连接嵌套条件
$query->where([
'author_id !=' => 1,
'OR' => ['published' => true, 'posted <' => new DateTime('now')],
'NOT' => ['title' => 'Hello']
], ['published' => boolean, 'posted' => 'datetime']
前面的示例产生
WHERE author_id = 1 AND (published = 1 OR posted < '2012-02-01') AND NOT (title = 'Hello')
您可以根据需要使用连接来嵌套条件。有时,您可能希望为同一个键定义两个不同的选项,在这种情况下,您可以将每个条件包装在一个新的数组中
$query->where(['OR' => [['published' => false], ['published' => true]])
将导致
WHERE (published = false) OR (published = true)
请记住,每次调用 where() 并将第三个参数设置为 false(默认值)时,它都会使用 AND
运算符将传递的条件与先前存储的列表连接起来。此外,在对该方法的连续调用中两次使用相同的数组键将不会覆盖先前的值。
使用表达式对象
$exp = $query->newExpr()->add(['id !=' => 100, 'author_id' != 1])->tieWith('OR');
$query->where(['published' => true], ['published' => 'boolean'])->where($exp);
前面的示例产生
WHERE (id != 100 OR author_id != 1) AND published = 1
其他查询对象可用作任何字段的条件。
分步骤添加条件
您可以使用回调函数来构造复杂的表达式,函数接收一个新的 QueryExpression 对象作为第一个参数,接收此查询实例作为第二个参数。函数必须返回一个表达式对象,该对象将使用 AND
运算符添加到查询条件列表中。
$query
->where(['title !=' => 'Hello World'])
->where(function ($exp, $query) {
$or = $exp->or(['id' => 1]);
$and = $exp->and(['id >' => 2, 'id <' => 10]);
return $or->add($and);
});
- 前面的示例产生
WHERE title != 'Hello World' AND (id = 1 OR (id > 2 AND id < 10))
作为字符串的条件
$query->where(['articles.author_id = authors.id', 'modified IS NULL']);
前面的示例产生
WHERE articles.author_id = authors.id AND modified IS NULL
请注意,使用数组表示法或表达式对象时,所有值都将被正确地引用并自动转换为相应的数据库数据类型,从而保护您的应用程序免受 SQL 注入攻击。但是,键不会被视为不安全的输入,应进行验证/清理。
如果使用字符串条件,请确保正确引用您的值。您可以做的最安全的事情是永远不要使用字符串条件。
使用可空值
使用可能为 null 的值时,可以使用 'IS' 关键字让 ORM 根据值的类型生成正确的 SQL。
$query->where([
'posted >=' => new DateTime('3 days ago'),
'category_id IS' => $category,
]);
如果 $category 为 null
- 它实际上会将其转换为 category_id IS NULL
- 如果它为 4
,它会将其转换为 category_id = 4
参数
-
Cake\Database\ExpressionInterfaceClosure|array|string|null
$conditions 可选 要过滤的条件。
-
array<string, string>
$types optional 用于将值绑定到查询的类型名称的关联数组
-
bool
$overwrite 可选 是否用传递的列表重置条件
返回值
$this
另请参阅
\Cake\Database\Expression\QueryExpression
whereInList() ¶ public
whereInList(string $field, array $values, array<string, mixed> $options = []): $this
添加将用于此查询 WHERE 子句的 IN 条件或条件集。
与 where() 相比,此方法允许空输入,前提是您将 'allowEmpty' 设置为 true。在没有进行适当的完整性检查的情况下,请谨慎使用它。
选项
types
- 用于将值绑定到查询的类型名称的关联数组allowEmpty
- 允许空数组。
参数
-
string
$field 字段
-
array
$values 值数组
-
array<string, mixed>
$options 可选 选项
返回值
$this
whereNotInList() ¶ public
whereNotInList(string $field, array $values, array<string, mixed> $options = []): $this
添加将用于此查询 WHERE 子句的 NOT IN 条件或条件集。
与 where() 相比,此方法允许空输入,前提是您将 'allowEmpty' 设置为 true。在没有进行适当的完整性检查的情况下,请谨慎使用它。
参数
-
string
$field 字段
-
array
$values 值数组
-
array<string, mixed>
$options 可选 选项
返回值
$this
whereNotInListOrNull() ¶ public
whereNotInListOrNull(string $field, array $values, array<string, mixed> $options = []): $this
添加将用于此查询 WHERE 子句的 NOT IN 条件或条件集。这也允许该字段使用 IS NULL 条件为 null,因为 null 值会导致 NOT IN 条件始终失败。
与 where() 相比,此方法允许空输入,前提是您将 'allowEmpty' 设置为 true。在没有进行适当的完整性检查的情况下,请谨慎使用它。
参数
-
string
$field 字段
-
array
$values 值数组
-
array<string, mixed>
$options 可选 选项
返回值
$this
whereNotNull() ¶ public
whereNotNull(Cake\Database\ExpressionInterface|array|string $fields): $this
为查询添加 NOT NULL 条件的便捷方法
参数
-
Cake\Database\ExpressionInterface|array|string
$fields 一个或多个字段或表达式,它们应该不为空。
返回值
$this
whereNull() ¶ public
whereNull(Cake\Database\ExpressionInterface|array|string $fields): $this
为查询添加 IS NULL 条件的便捷方法
参数
-
Cake\Database\ExpressionInterface|array|string
$fields 一个或多个字段或表达式,它们应该为空。
返回值
$this
with() ¶ public
with(Cake\Database\Expression\CommonTableExpressionClosure $cte, bool $overwrite = false): $this
向查询添加新的公用表表达式 (CTE)。
示例
通用表表达式可以作为预先构建的表达式对象传递
$cte = new \Cake\Database\Expression\CommonTableExpression(
'cte',
$connection
->selectQuery('*')
->from('articles')
);
$query->with($cte);
或者从闭包返回,闭包将接收一个新的通用表表达式对象作为第一个参数,接收一个新的空白 select 查询对象作为第二个参数
$query->with(function (
\Cake\Database\Expression\CommonTableExpression $cte,
\Cake\Database\Query $query
) {
$cteQuery = $query
->select('*')
->from('articles');
return $cte
->name('cte')
->query($cteQuery);
});
参数
-
Cake\Database\Expression\CommonTableExpressionClosure
$cte 要添加的 CTE。
-
bool
$overwrite 可选 是否重置 CTE 列表。
返回值
$this