类 SelectQuery

处理清除迭代器并克隆所有表达式和值绑定器。

返回值

构造函数。

参数

返回一个数组，可用于描述此对象的内部状态。

返回值

返回此查询的字符串表示形式（完整的 SQL 语句）。

返回值

用于通过组合 QueryExpression 对象构建条件的辅助函数。

参数

返回值

将查询标记为已更改，从内存缓存中删除任何预处理信息。

返回值

traverseExpressions() 使用的查询部分遍历方法

参数

返回值

返回一个数组，该数组可以传递给 join 方法，描述一个单一的 join 子句

参数

返回值

执行查询并返回装饰后的结果集。

结果被缓存，直到查询被修改并标记为脏数据。

返回值

抛出

使用 HAVING 子句中的 AND 运算符将任何先前定义的条件集连接到提供的列表。 此方法的操作方式与方法 andWhere() 完全相同。 请参考其文档以了解如何使用每个参数。

Having 字段不适合与用户提供的数据一起使用，因为它们不会被查询构建器清理。

参数

返回值

另请参阅

使用 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)

参数

返回值

另请参阅

将查询占位符与值和类型关联。

$query->bind(':id', 1, 'integer');

参数

返回值

返回存储在指定子句中的任何数据。 这对于修改查询的任何内部部分很有用，并且 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: 数组
• set: 数组
• where: QueryExpression，当未设置时，返回 null。
• group: 数组
• having: QueryExpression，当未设置时，返回 null。
• order: OrderByExpression，当未设置时，返回 null。
• limit: integer 或 QueryExpression，当未设置时，返回 null。
• offset: integer 或 QueryExpression，当未设置时，返回 null。
• union: 数组
• intersect: 数组

参数

返回值

抛出

一个字符串或表达式，将作为注释附加到生成的查询中。

示例

$query->select('id')->where(['author_id' => 1])->comment('Filter for admin user');

注释内容是原始 SQL，不适合与用户提供的数据一起使用。

参数

返回值

注册一个回调函数，该函数将为从结果集中获取的每个结果执行，回调函数将接收一个包含从数据库获取的原始数据的数组作为第一个参数，并且必须返回可能进行了任何修改的行。

回调函数将被延迟执行，如果仅为数据库获取 3 行，则将调用该函数 3 次，即使游标中可能还有更多行要获取。

回调函数按注册顺序堆叠，如果您希望重置堆栈，请使用第二个参数设置为 true 调用此函数。

如果您希望从堆栈中删除所有装饰器，请将第一个参数设置为 null，并将第二个参数设置为 true。

示例

$query->decorateResults(function ($row) {
  $row['order_total'] = $row['subtotal'] + ($row['subtotal'] * $row['tax']);
   return $row;
});

参数

返回值

禁用缓冲结果。

禁用缓冲将减少内存消耗，因为获取的结果不会被记住以供将来迭代。

返回值

禁用结果转换。

禁用后，字段将按从数据库驱动程序接收的方式返回（在大多数环境中意味着它们作为字符串返回），这可以提高大型数据集的性能。

返回值

向查询添加 DISTINCT 子句以从结果集中删除重复项。 此子句只能用于 select 语句。

如果您希望根据共享特定字段或一组字段的这些行来过滤重复项，您可以传递一个要过滤的字段数组。注意，此选项可能不是所有数据库系统都完全支持的。

示例

// Filters products with the same name and city
$query->select(['name', 'city'])->from('products')->distinct();

// Filters products in the same city
$query->distinct(['city']);
$query->distinct('city');

// Filter products with the same name
$query->distinct(['name'], true);
$query->distinct('name', true);

参数

返回值

启用缓冲结果。

启用后，此查询返回的结果将被缓冲。这使您能够多次迭代结果集，或者同时缓存和迭代它。

禁用后，将减少内存消耗，因为获取的结果不会被记住以供将来迭代。

返回值

启用结果转换。

启用后，此查询返回的结果中的字段将被强制转换为它们相应的 PHP 数据类型。

返回值

一个字符串或表达式，将附加到生成的查询中。

示例

$query->select('id')->where(['author_id' => 1])->epilog('FOR UPDATE');
$query
 ->insert('articles', ['title'])
 ->values(['author_id' => 1])
 ->epilog('RETURNING id');

Epliog 内容是原始 SQL，不适合与用户提供的数据一起使用。

参数

返回值

编译此查询的 SQL 表示形式，并使用配置的连接对象执行它。 返回生成的状态对象。

在内部执行查询会执行几个步骤，第一个是让连接转换此对象以适应其特定方言，这可能会导致生成一个不同的查询对象，该对象将是实际执行的对象。紧随其后的是将字面量值传递给连接，以便以安全的方式将其绑定到查询。最后，使用自定义对象装饰生成的语句，以便根据需要为检索的每一行执行回调函数。

生成的语句是可遍历的，因此它可以在任何循环中使用，就像使用数组一样。

此方法可以在查询子类中被覆盖，以装饰查询执行周围的行为。

返回值

返回一个新的 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

参数

返回值

添加一个或多个表，用于此查询的 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

参数

返回值

返回一个函数生成器对象实例，可用于生成任意 SQL 函数。

示例

$query->func()->count('*');
$query->func()->dateDiff(['2012-01-05', '2012-01-02'])

返回值

获取用于执行和转换此查询的连接实例。

返回值

返回连接角色（'read' 或 'write'）。

返回值

获取当前类型映射的默认类型。

返回值

执行此查询并返回结果迭代器。此函数是实现 IteratorAggregate 接口所必需的，允许在不手动调用 all() 的情况下迭代查询，从而使其看起来像结果集而不是查询本身。

返回值

获取结果装饰器。

返回值

获取 TypeMap 类，其中存储 select 子句中每个字段的类型。

返回值

返回现有的类型映射。

返回值

返回当前使用的 ValueBinder 实例。

ValueBinder 负责生成查询占位符，并临时将值与这些占位符关联，以便它们能够正确地传递给语句对象。

返回值

添加一个或多个字段用于此查询的 GROUP BY 子句。字段可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。

默认情况下，此函数将任何传递的参数追加到要分组的字段列表中，除非第二个参数设置为 true。

示例

// Produces GROUP BY id, title
$query->groupBy(['id', 'title']);

// Produces GROUP BY title
$query->groupBy('title');

分组字段不适合用于用户提供的数据，因为它们不会被查询构建器进行清理。

参数

返回值

添加一个或多个字段用于此查询的 GROUP BY 子句。字段可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。

默认情况下，此函数将任何传递的参数追加到要分组的字段列表中，除非第二个参数设置为 true。

示例

// Produces GROUP BY id, title
$query->groupBy(['id', 'title']);

// Produces GROUP BY title
$query->groupBy('title');

分组字段不适合用于用户提供的数据，因为它们不会被查询构建器进行清理。

参数

返回值

添加一个或多个条件用于此查询的 HAVING 子句。此方法的操作方式与 where() 方法完全相同。请参阅其文档以了解如何使用每个参数。

Having 字段不适合与用户提供的数据一起使用，因为它们不会被查询构建器清理。

参数

返回值

另请参阅

创建一个引用标识符的表达式。标识符用于引用字段名称，并允许 SQL 编译器应用引号或转义标识符。

该值按原样使用，您可能需要在标识符中使用别名或包含表引用。请勿使用此方法注入 SQL 方法或逻辑语句。

示例

$query->newExpr()->lte('count', $query->identifier('total'));

参数

返回值

向查询添加一个 INNER JOIN 子句。

这是通过 join() 构建联接的简写方法。

此方法的参数与 leftJoin() 简写相同，有关更多详细信息，请参阅该方法的描述。

参数

返回值

添加一个完整查询，用于与此查询的 INTERSECT 运算符结合使用。这用于将此查询返回的结果集与传递的查询返回的结果集结合起来。您可以通过多次使用不同的查询调用此方法来添加任意数量的查询。

默认情况下，INTERSECT 运算符将删除重复行，如果您希望为所有查询包含所有行，请使用 intersectAll()。

示例

$intersect = (new SelectQuery($conn))->select(['id', 'title'])->from(['a' => 'articles']);
$query->select(['id', 'name'])->from(['d' => 'things'])->intersect($intersect);

将产生

SELECT id, name FROM things d INTERSECT SELECT id, title FROM articles a

参数

返回值

添加一个完整查询，用于与此查询的 INTERSECT ALL 运算符结合使用。这用于将此查询返回的结果集与传递的查询返回的结果集结合起来。您可以通过多次使用不同的查询调用此方法来添加任意数量的查询。

与 INTERSECT 不同，INTERSECT ALL 不会删除重复行。

$intersect = (new SelectQuery($conn))->select(['id', 'title'])->from(['a' => 'articles']);
$query->select(['id', 'name'])->from(['d' => 'things'])->intersectAll($intersect);

将产生

SELECT id, name FROM things d INTERSECT ALL SELECT id, title FROM articles a

参数

返回值

返回是否启用/禁用缓冲结果。

启用后，此查询返回的结果将被缓冲。这使您能够多次迭代结果集，或者同时缓存和迭代它。

禁用后，将减少内存消耗，因为获取的结果不会被记住以供将来迭代。

返回值

返回是否启用/禁用结果转换。

启用后，此 Query 返回的结果中的字段将被转换为相应的 PHP 数据类型。

禁用后，字段将按从数据库驱动程序接收的方式返回（在大多数环境中意味着它们作为字符串返回），这可以提高大型数据集的性能。

返回值

添加一个或多个表作为 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

参数

返回值

另请参阅

向查询添加一个 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()。

参数

返回值

设置应从数据库中检索的记录数量，接受一个整数或一个计算结果为整数的表达式对象。在某些数据库中，此操作可能不受支持，或者需要转换查询以限制结果集大小。

示例

$query->limit(10) // generates LIMIT 10
$query->limit($query->newExpr()->add(['1 + 1'])); // LIMIT (1 + 1)

参数

返回值

添加一个或多个 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

参数

返回值

返回一个新的 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

参数

返回值

设置应从原始结果集中跳过的记录数量，这通常用于对大型结果进行分页。接受一个整数或一个计算结果为整数的表达式对象。

在某些数据库中，此操作可能不受支持，或者需要转换查询才能限制结果集的大小。

示例

$query->offset(10) // generates OFFSET 10
$query->offset($query->newExpr()->add(['1 + 1'])); // OFFSET (1 + 1)

参数

返回值

添加一个或多个字段用于此查询的 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()。

参数

返回值

添加一个具有 ASC 方向的 ORDER BY 子句。

此方法允许您设置复杂的表达式作为排序条件，不像 order() 方法。

排序字段不适合与用户提供的数据一起使用，因为它们没有经过查询构建器的清理。

参数

返回值

添加一个或多个字段用于此查询的 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()。

参数

返回值

添加一个具有 ASC 方向的 ORDER BY 子句。

此方法允许您设置复杂的表达式作为排序条件，不像 order() 方法。

排序字段不适合与用户提供的数据一起使用，因为它们没有经过查询构建器的清理。

参数

返回值

添加一个具有 DESC 方向的 ORDER BY 子句。

此方法允许您设置复杂的表达式作为排序条件，不像 order() 方法。

排序字段不适合与用户提供的数据一起使用，因为它们没有经过查询构建器的清理。

参数

返回值

添加一个具有 DESC 方向的 ORDER BY 子句。

此方法允许您设置复杂的表达式作为排序条件，不像 order() 方法。

排序字段不适合与用户提供的数据一起使用，因为它们没有经过查询构建器的清理。

参数

返回值

设置您想要的结果页。

此方法提供了一个更易于使用的接口来设置您想要作为结果的记录集中 limit + offset 的值。如果为空，limit 将默认为现有的 limit 子句，如果该子句也为空，则将使用 25。

页面必须从 1 开始。

参数

返回值

抛出

如果已定义，则删除联接。

当您重新定义连接或想要重新排序连接子句时很有用。

参数

返回值

向查询添加一个 RIGHT JOIN 子句。

这是通过 join() 构建联接的简写方法。

此方法的参数与 leftJoin() 简写相同，请参考该方法的描述以了解更多详细信息。

参数

返回值

执行此查询的 SQL 并立即关闭语句，然后返回更改的记录行数。

此方法可用于 UPDATE 和 DELETE 查询，但不建议用于 SELECT 查询，也不用于计数记录。

示例

$rowCount = $query->update('articles')
                ->set(['published'=>true])
                ->where(['published'=>false])
                ->rowCountAndClose();

上面的示例将所有 false 记录的 published 列更改为 true，并返回已更新的记录数。

返回值

添加要在此查询执行时由 SELECT 语句返回的新字段。字段可以作为字符串数组、表达式对象数组、单个表达式或单个字符串传递。

如果传递一个数组，键将用于使用值作为要别名的实际字段来为字段设置别名。可以为字符串、表达式对象甚至其他查询对象设置别名。

如果传递一个回调函数，则该函数返回的数组将用作字段列表。

默认情况下，此函数将任何传递的参数追加到要选择的字段列表中，除非第二个参数设置为 true。

示例

$query->select(['id', 'title']); // Produces SELECT id, title
$query->select(['author' => 'author_id']); // Appends author: SELECT id, title, author_id as author
$query->select('id', true); // Resets the list: SELECT id
$query->select(['total' => $countQuery]); // SELECT id, (SELECT ...) AS total
$query->select(function ($query) {
    return ['article_id', 'total' => $query->func()->count('*')];
})

默认情况下不选择任何字段，如果您有一个 Cake\ORM\Query 实例并尝试追加字段，您还应该调用 Cake\ORM\Query::enableAutoFields() 以从表中选择默认字段。

参数

返回值

设置用于执行和转换此查询的连接实例。

参数

返回值

设置连接角色。

参数

返回值

覆盖实现对象中字段的默认类型映射。

如果您需要设置跨多个函数/表达式在查询中共享的类型映射，此方法很有用。

要添加默认值而不覆盖现有值，请使用 getTypeMap()->addDefaults()

参数

返回值

另请参阅

设置 TypeMap 类，其中存储 select 子句中每个字段的类型。

参数

返回值

如果 $typeMap 是一个数组，则创建一个新的 TypeMap，否则将其交换为给定的 TypeMap。

参数

返回值

覆盖当前的值绑定器

ValueBinder 负责生成查询占位符，并临时将值与这些占位符关联，以便它们能够正确地传递给语句对象。

参数

返回值

返回此对象的 SQL 表示形式。

此函数将编译此查询以使其与连接使用的 SQL 方言兼容。此过程可能会添加、删除或更改任何查询部分或内部表达式，以使其在目标平台上可执行。

生成的查询可能包含占位符，这些占位符将在查询执行时被实际值替换，因此最适合与预处理语句一起使用。

参数

返回值

将遍历每个指定的部件。遍历函数可以使用闭包或实例变量中的变量聚合结果。此函数通常用作遍历所有将用于构建查询的查询部分的一种方式。

回调函数将接收两个参数，第一个是正在迭代的查询部分的值，第二个是该部分的名称。

示例

$query->select(['title'])->from('articles')->traverse(function ($value, $clause) {
    if ($clause === 'select') {
        var_dump($value);
    }
});

参数

返回值

此函数的工作方式类似于 traverse() 函数，不同之处在于它对整个表达式树进行了全深度遍历。这将为存储在此查询中的每个 ExpressionInterface 对象执行提供的回调函数，无论其嵌套深度如何，也不管查询的任何部分。

回调函数将接收当前访问的表达式作为第一个参数。

参数

返回值

将遍历提供的部分。

遍历函数可以使用闭包中的变量或实例变量来聚合结果。此方法可用于遍历查询部分的子集，以便呈现 SQL 查询。

回调函数将接收两个参数，第一个是正在迭代的查询部分的值，第二个是该部分的名称。

示例

$query->select(['title'])->from('articles')->traverse(function ($value, $clause) {
    if ($clause === 'select') {
        var_dump($value);
    }
}, ['select', 'from']);

参数

返回值

返回此查询的类型（select、insert、update、delete）。

返回值

添加一个完整查询，用于与此查询的 UNION 运算符结合使用。这用于将此查询返回的结果集与传递的查询返回的结果集结合起来。您可以通过多次使用不同的查询调用此方法来添加任意数量的查询。

默认情况下，UNION 运算符将删除重复行，如果您希望包含所有查询的每行，请使用 unionAll()。

示例

$union = (new SelectQuery($conn))->select(['id', 'title'])->from(['a' => 'articles']);
$query->select(['id', 'name'])->from(['d' => 'things'])->union($union);

将产生

SELECT id, name FROM things d UNION SELECT id, title FROM articles a

参数

返回值

添加一个完整查询，用于与此查询的 UNION ALL 运算符结合使用。这用于将此查询返回的结果集与传递的查询返回的结果集结合起来。您可以通过多次使用不同的查询调用此方法来添加任意数量的查询。

与 UNION 不同，UNION ALL 不会删除重复行。

$union = (new SelectQuery($conn))->select(['id', 'title'])->from(['a' => 'articles']);
$query->select(['id', 'name'])->from(['d' => 'things'])->unionAll($union);

将产生

SELECT id, name FROM things d UNION ALL SELECT id, title FROM articles a

参数

返回值

将连接角色设置为 read。

返回值

将连接角色设置为 write。

返回值

添加一个或多个条件用于此查询的 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 注入。但是，键不被视为不安全的输入，应进行验证/清理。

如果您使用字符串条件，请确保您的值被正确引用。您可以做的最安全的事情是永远不要使用字符串条件。

使用可为空值

当使用可以为空的值时，您可以使用 '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

参数

返回值

另请参阅

添加一个或多个 IN 条件用于此查询的 WHERE 子句。

与 where() 不同，此方法允许空输入，如果您将 'allowEmpty' 设置为 true。请注意，在没有适当的健全性检查的情况下使用它。

选项

• types - 用于将值绑定到查询的类型名称的关联数组
• allowEmpty - 允许空数组。

参数

返回值

添加一个或多个 NOT IN 条件用于此查询的 WHERE 子句。

与 where() 不同，此方法允许空输入，如果您将 'allowEmpty' 设置为 true。请注意，在没有适当的健全性检查的情况下使用它。

参数

返回值

添加一个或多个 NOT IN 条件用于此查询的 WHERE 子句。这也允许字段使用 IS NULL 条件为 null，因为 null 值会导致 NOT IN 条件始终失败。

与 where() 不同，此方法允许空输入，如果您将 'allowEmpty' 设置为 true。请注意，在没有适当的健全性检查的情况下使用它。

参数

返回值

便利方法，向查询添加 NOT NULL 条件

参数

返回值

便利方法，向查询添加 IS NULL 条件

参数

返回值

添加一个命名的窗口表达式。

您有责任按照数据库的要求添加窗口。

参数

返回值

向查询添加一个新的公用表表达式 (CTE)。

示例

通用表表达式可以作为预先构建的表达式对象传递

$cte = new \Cake\Database\Expression\CommonTableExpression(
    'cte',
    $connection
        ->selectQuery('*')
        ->from('articles')
);

$query->with($cte);

或者从闭包中返回，闭包将接收一个新的通用表表达式对象作为第一个参数，并接收一个新的空白选择查询对象作为第二个参数

$query->with(function (
    \Cake\Database\Expression\CommonTableExpression $cte,
    \Cake\Database\Query $query
 ) {
    $cteQuery = $query
        ->select('*')
        ->from('articles');

return $cte
        ->name('cte')
        ->query($cteQuery);
});

参数

返回值