类 SelectQuery

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

处理克隆渴望加载器。

返回

构造函数

参数

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

返回

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

返回

用于递归地将包含的关联列类型添加到查询中。

参数

返回

检查是否有任何设置的字段用于选择，否则添加默认表的全部字段。

返回

设置选择子句中字段转换的默认类型

返回

帮助函数，用于通过组合 QueryExpression 对象来构建条件。

参数

返回

使用映射-归约例程和格式化器装饰结果迭代器

参数

返回

将查询标记为脏，从内存缓存中删除任何预处理的信息，例如以前的结果

返回

执行此查询并返回包含结果的迭代器。

返回

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

参数

返回

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

参数

返回

执行并返回查询的 COUNT(*)。

返回

在查询对象执行之前应用一些默认值。

具体添加 FROM 子句，如果未指定则添加默认表字段，并应用急切加载使用 contain 定义的关联所需的连接

它还为 select 子句中的列设置默认类型

返回

另请参见

提示此对象在为数据库转换条件时关联正确的类型。 这是通过从与传递的表对象关联的模式中提取字段类型来完成的。 这可以防止用户在指定条件时重复自己。

此方法返回相同的查询对象以进行链接。

参数

返回

返回一个键 => 值数组，表示一个单独的别名字段，可以直接传递给 select() 方法。 键将包含别名，值将包含实际字段名称。

如果该字段已具有别名，则不会更改它。 如果未传递 $alias，则将使用此查询的默认表。

参数

返回

对提供的列表中的每个字段运行 aliasField() 并将结果放在一个单独的数组中返回。

参数

返回

获取此查询的结果。

将返回通过 setResult() 设置的结果集，或者执行此查询并返回 ResultSetDecorator 对象，该对象已准备好进行结果流式传输。

ResultSetDecorator 是一个可遍历对象，它实现了 Cake\Collection\Collection 上找到的方法。

返回

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

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

参数

返回

另请参见

使用 AND 运算符将任何先前定义的条件集连接到提供的列表。 {@see \Cake\Database\Query::andWhere()}

重要的是要注意，在调用此函数时，为该查询定义的任何先前条件集将被视为 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)

参数

返回

使用数组填充或添加当前查询子句的部分。 这对于一次传递所有查询子句非常方便。

该方法接受以下与查询子句相关的选项

• fields: 映射到 select 方法
• conditions: 映射到 where 方法
• limit: 映射到 limit 方法
• order: 映射到 order 方法
• offset: 映射到 offset 方法
• group: 映射到 group 方法
• having: 映射到 having 方法
• contain: 映射到急切加载的 contain 选项
• join: 映射到 join 方法
• page: 映射到 page 方法

所有其他选项都不会影响查询，但将被存储为自定义选项，可以通过 getOptions() 读取。 此外，它们会自动传递给 Model.beforeFind。

示例

$query->applyOptions([
  'fields' => ['id', 'name'],
  'conditions' => [
    'created >=' => '2013-01-01'
  ],
  'limit' => 10,
]);

等同于

$query
  ->select(['id', 'name'])
  ->where(['created >=' => '2013-01-01'])
  ->limit(10)

自定义选项可以通过 getOptions() 读取

$query->applyOptions([
  'fields' => ['id', 'name'],
  'custom' => 'value',
]);

这里 $options 将保存 ['custom' => 'value']（fields 选项将应用于查询，而不是存储，因为它是一个与查询子句相关的选项）

$options = $query->getOptions();

参数

返回

另请参见

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

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

参数

返回

为此查询启用结果缓存。

如果查询启用了缓存，它在执行时将执行以下操作

• 检查 $key 的缓存。 如果有结果，将不会执行任何 SQL。 相反，将返回缓存的结果。
• 当缓存数据陈旧/丢失时，结果集将被缓存为查询执行。

用法

// Simple string key + config
$query->cache('my_key', 'db_results');

// Function to generate key.
$query->cache(function ($q) {
  $key = serialize($q->clause('select'));
  $key .= serialize($q->clause('where'));
  return md5($key);
});

// Using a pre-built cache engine.
$query->cache('my_key', $engine);

// Disable caching
$query->cache(false);

参数

返回

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

参数

返回

抛出

创建当前查询的副本，触发 beforeFind 并重置一些状态。

以下状态将被清除

• autoFields
• limit
• offset
• map/reduce 函数
• 结果格式化程序
• order
• 包含

此方法创建查询克隆，在处理子查询时很有用。

返回

从当前查询中清除包含的关联。

返回

从当前查询对象中清除内部结果缓存和内部计数值。

返回

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

示例

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

注释内容是原始 SQL，不适合用于用户提供的數據。

参数

返回

设置应该与该查询一起急切加载的关联列表。 传递的关联表列表必须使用 Table API 之前已设置为关联。

示例

// Bring articles' author information
$query->contain('Author');

// Also bring the category and tags associated to each article
$query->contain(['Category', 'Tag']);

可以使用点符号或嵌套数组任意嵌套关联，这允许此对象计算连接或必须执行的任何其他查询以获取所需的关联数据。

示例

// Eager load the product info, and for each product load other 2 associations
$query->contain(['Product' => ['Manufacturer', 'Distributor']);

// Which is equivalent to calling
$query->contain(['Products.Manufactures', 'Products.Distributors']);

// For an author query, load his region, state and country
$query->contain('Regions.States.Countries');

可以控制每个包含关联的条件和选定的字段

示例

$query->contain(['Tags' => function ($q) {
    return $q->where(['Tags.is_popular' => true]);
}]);

$query->contain(['Products.Manufactures' => function ($q) {
    return $q->select(['name'])->where(['Manufactures.active' => true]);
}]);

每个关联在渴望加载时可能会定义特殊选项，允许针对每个关联设置的选项是

• foreignKey：用于设置不同的字段以匹配两个表，如果设置为 false，将不会自动生成连接条件。false 只能用于可连接的关联，不能与 hasMany 或 belongsToMany 关联一起使用。
• fields：包含应从关联中获取的字段的数组。
• finder：在加载关联记录时使用的查找器。查找器的名称作为一个字符串，或者一个数组定义要传递给查找器的选项。
• queryBuilder：等同于传递回调而不是选项数组。

示例

// Set options for the hasMany articles that will be eagerly loaded for an author
$query->contain([
    'Articles' => [
        'fields' => ['title', 'author_id']
    ]
]);

查找器可以配置为使用选项。

// Retrieve translations for the articles, but only those for the `en` and `es` locales
$query->contain([
    'Articles' => [
        'finder' => [
            'translations' => [
                'locales' => ['en', 'es']
            ]
        ]
    ]
]);

包含关联时，务必包含外键列。否则将触发异常。

// Use a query builder to add conditions to the containment
$query->contain('Authors', function ($q) {
    return $q->where(...); // add conditions
});
// Use special join conditions for multiple containments in the same method call
$query->contain([
    'Authors' => [
        'foreignKey' => false,
        'queryBuilder' => function ($q) {
            return $q->where(...); // Add full filtering conditions
        }
    ],
    'Tags' => function ($q) {
        return $q->where(...); // add conditions
    }
]);

如果使用空第一个参数调用，并且 $override 设置为 true，则先前列表将被清空。

参数

返回

返回查询的总结果数。

返回查询的 COUNT(*)。如果查询未被修改，并且计数已执行，则返回缓存的值

返回

注册一个回调，它将在该查询中的 count 方法被调用时执行。 函数的返回值将被设置为 count 方法的返回值。

这在需要优化查询以返回计数时特别有用，例如删除不必要的连接，删除分组或只返回估计的行数。

回调将以该查询的克隆作为第一个参数接收，而不是该查询本身。

如果第一个参数为空值，则将调用内置计数函数

参数

返回

注册一个回调，该回调将在从结果集中获取每个结果时执行，回调函数将接收第一个参数，该参数是一个数组，其中包含来自数据库的原始数据，用于获取的每一行，并且必须返回该行，并带有任何可能的修改。

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

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

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

示例

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

参数

返回

禁用自动将表的别名添加到 SELECT 子句的字段中。

返回

禁用自动追加字段。

返回

禁用缓冲结果。

禁用缓冲将减少内存消耗，因为获取的结果不会为将来的迭代而保留。

返回

禁用水化实体。

禁用水化将导致查询返回数组结果而不是实体。

返回

禁用结果转换。

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

返回

在查询中添加 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);

参数

返回

将查询实例设置为急切加载的查询。 如果没有传递参数，则返回当前配置的查询 _eagerLoaded 值。

参数

返回

设置 ORM 是否应该自动追加字段。

默认情况下，调用 select() 将禁用自动字段。可以使用此方法重新启用自动字段。

参数

返回

启用缓冲结果。

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

禁用后，它将减少内存消耗，因为获取的结果不会为将来的迭代而保留。

返回

切换水化实体。

如果设置为 false，则查询将返回数组结果。

参数

返回

启用结果转换。

启用后，此查询返回的结果中的字段将转换为相应的 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

参数

返回

对现有的查询对象应用自定义查找。

允许自定义查找方法相互组合并应用于彼此。

$repository->find('all')->find('recent');

以上是一个将多个查找器方法堆叠到单个查询中的示例。

参数

返回

返回执行此查询的第一个结果，如果该查询之前没有执行过，则出于性能原因，它会将 limit 子句设置为 1。

示例

$singleUser = $query->select(['id', 'username'])->first();

返回

从执行查询中获取第一个结果或引发异常。

返回

抛出

注册一个新的格式化回调函数，该函数将在尝试从数据库中获取结果时执行。

如果第二个参数设置为 true，它将擦除以前的格式化器并用传递的第一个参数替换它们。

回调需要返回一个迭代器对象，该对象将用作此查询结果的返回值。格式化器函数在执行此查询的所有 MapReduce 例程之后应用。

格式化回调将接收两个参数，第一个参数是一个实现 \Cake\Collection\CollectionInterface 的对象，可以随意遍历和修改。第二个参数是正在应用格式化器回调的查询实例。

通常，格式化器回调接收到的查询实例与回调所附加的相同查询实例相同，但在关联联接中除外，在这种情况下，回调将在关联源端查询上调用，并且它将接收该查询实例而不是最初附加回调的实例 - 请参见下面的示例！

示例

返回表中按 id 索引的所有结果

$query->select(['id', 'name'])->formatResults(function ($results) {
    return $results->indexBy('id');
});

向 ResultSet 添加新列

$query->select(['name', 'birth_date'])->formatResults(function ($results) {
    return $results->map(function ($row) {
        $row['age'] = $row['birth_date']->diff(new DateTime)->y;

return $row;
    });
});

根据查询的 hydration 配置向结果添加新列

$query->formatResults(function ($results, $query) {
    return $results->map(function ($row) use ($query) {
        $data = [
            'bar' => 'baz',
        ];

if ($query->isHydrationEnabled()) {
            $row['foo'] = new Foo($data)
        } else {
            $row['foo'] = $data;
        }

return $row;
    });
});

通过继承 contain 回调的查询参数，保留对联接关联的关联目标查询实例的访问权限

// Assuming a `Articles belongsTo Authors` association that uses the join strategy

$articlesQuery->contain('Authors', function ($authorsQuery) {
    return $authorsQuery->formatResults(function ($results, $query) use ($authorsQuery) {
        // Here `$authorsQuery` will always be the instance
        // where the callback was attached to.

// The instance passed to the callback in the second
        // argument (`$query`), will be the one where the
        // callback is actually being applied to, in this
        // example that would be `$articlesQuery`.

// ...

return $results;
    });
});

参数

返回

抛出

添加一个或多个表，这些表将在此查询的 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 接口所必需的，它允许迭代查询，而无需手动调用 execute()，从而使查询看起来像结果集而不是查询本身。

返回

返回先前注册的映射缩减例程的列表。

返回

返回一个包含应用于此查询的自定义选项的数组，这些选项尚未由该类的其他方法处理。

示例

 $query->applyOptions(['doABarrelRoll' => true, 'fields' => ['id', 'name']);
 $query->getOptions(); // Returns ['doABarrelRoll' => true]

返回

另请参见

返回此查询将使用的默认存储库对象，即将在 from 子句中出现的表。

返回

获取结果装饰器。

返回

返回先前注册的格式例程的列表。

返回

获取 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() 简写相同，请参考该方法的描述以了解更详细的信息。

参数

返回

使用传递的关联表创建 INNER JOIN，同时保留最初为其设置的外键匹配和自定义条件。

此函数将添加 contain 图表中的条目。

示例

// Bring only articles that were tagged with 'cake'
$query->innerJoinWith('Tags', function ($q) {
    return $q->where(['name' => 'cake']);
});

这将创建以下 SQL

SELECT Articles.*
FROM articles Articles
INNER JOIN tags Tags ON Tags.name = 'cake'
INNER JOIN articles_tags ArticlesTags ON ArticlesTags.tag_id = Tags.id
  AND ArticlesTags.articles_id = Articles.id

此函数与 matching() 的工作原理相同，区别在于它不会从关联中选择任何字段。

参数

返回

另请参见

添加一个完整的查询，该查询将与该查询的 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

参数

返回

获取 ORM 是否应该自动追加字段。

默认情况下，调用 select() 将禁用自动字段。您可以使用 enableAutoFields() 重新启用自动字段。

返回

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

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

禁用后，它将减少内存消耗，因为获取的结果不会为将来的迭代而保留。

返回

返回当前配置的查询 _eagerLoaded 值

返回

返回当前的水合模式。

返回

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

启用后，此查询返回的结果中的字段将转换为相应的 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

参数

返回

另请参见

执行查询并将结果集转换为 JSON。

JsonSerializable 接口的一部分。

返回

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

参数

返回

使用传递的关联表创建一个 LEFT JOIN，同时保留外键匹配以及最初为其设置的自定义条件。

此函数将添加 contain 图表中的条目。

示例

// Get the count of articles per user
$usersQuery
    ->select(['total_articles' => $query->func()->count('Articles.id')])
    ->leftJoinWith('Articles')
    ->groupBy(['Users.id'])
    ->enableAutoFields();

您还可以自定义传递给 LEFT JOIN 的条件

// Get the count of articles per user with at least 5 votes
$usersQuery
    ->select(['total_articles' => $query->func()->count('Articles.id')])
    ->leftJoinWith('Articles', function ($q) {
        return $q->where(['Articles.votes >=' => 5]);
    })
    ->groupBy(['Users.id'])
    ->enableAutoFields();

这将创建以下 SQL

SELECT COUNT(Articles.id) AS total_articles, Users.*
FROM users Users
LEFT JOIN articles Articles ON Articles.user_id = Users.id AND Articles.votes >= 5
GROUP BY USers.id

可以使用点表示法对深度关联进行左连接

示例

// Total comments in articles by 'markstory'
$query
    ->select(['total_comments' => $query->func()->count('Comments.id')])
    ->leftJoinWith('Comments.Users', function ($q) {
        return $q->where(['username' => 'markstory']);
    })
   ->groupBy(['Users.id']);

请注意，传递给闭包的查询只接受在其上调用 select、where、andWhere 和 orWhere。如果要添加更复杂的子句，可以在主查询中直接进行。

参数

返回

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

示例

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

参数

返回

注册一个新的 MapReduce 例程，该例程将在数据库结果之上执行。

MapReduce 路由只会在执行查询并尝试获取第一个结果时运行。

如果第三个参数设置为 true，它将擦除之前的 map reducers 并将其替换为传递的参数。

参数

返回

另请参见

向此查询添加过滤条件，以仅获取与关联表中的另一行具有关系的行，这些关系基于关联表中的条件。

此函数将添加 contain 图表中的条目。

示例

// Bring only articles that were tagged with 'cake'
$query->matching('Tags', function ($q) {
    return $q->where(['name' => 'cake']);
});

可以使用点表示法对深度关联进行筛选

示例

// Bring only articles that were commented by 'markstory'
$query->matching('Comments.Users', function ($q) {
    return $q->where(['username' => 'markstory']);
});

由于此函数将创建 INNER JOIN，因此您可能需要考虑在此查询上调用 distinct，因为如果您的条件没有筛选它们，您可能会获得重复的行。例如，这可能是同一个用户在同一篇文章中评论多次的情况。

示例

// Bring unique articles that were commented by 'markstory'
$query->distinct(['Articles.id'])
    ->matching('Comments.Users', function ($q) {
        return $q->where(['username' => 'markstory']);
    });

请注意，传递给闭包的查询只接受在其上调用 select、where、andWhere 和 orWhere。如果要添加更复杂的子句，可以在主查询中直接进行。

参数

返回

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

参数

返回

向此查询添加过滤条件，以仅获取与关联表中的另一行没有匹配的行，这些关系基于关联表中的条件。

此函数将添加 contain 图表中的条目。

示例

// Bring only articles that were not tagged with 'cake'
$query->notMatching('Tags', function ($q) {
    return $q->where(['name' => 'cake']);
});

可以使用点表示法对深度关联进行筛选

示例

// Bring only articles that weren't commented by 'markstory'
$query->notMatching('Comments.Users', function ($q) {
    return $q->where(['username' => 'markstory']);
});

由于此函数将创建 LEFT JOIN，因此您可能需要考虑在此查询上调用 distinct，因为如果您的条件没有筛选它们，您可能会获得重复的行。例如，这可能是同一篇文章有多个评论的情况。

示例

// Bring unique articles that were commented by 'markstory'
$query->distinct(['Articles.id'])
    ->notMatching('Comments.Users', function ($q) {
        return $q->where(['username' => 'markstory']);
    });

请注意，传递给闭包的查询只接受在其上调用 select、where、andWhere 和 orWhere。如果要添加更复杂的子句，可以在主查询中直接进行。

参数

返回

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

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

示例

 $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']);

将变成

ORDER BY (id %2 = 0), title ASC

如果需要将复杂表达式设置为排序条件，则应使用 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']);

将变成

ORDER BY (id %2 = 0), title ASC

如果需要将复杂表达式设置为排序条件，则应使用 orderByAsc() 或 orderByDesc()。

参数

返回

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

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

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

参数

返回

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

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

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

参数

返回

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

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

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

参数

返回

设置所需的页面结果。

此方法提供了一个更易于使用的接口来设置您希望作为结果的记录集中限制 + 偏移量。如果为空，则限制将默认为现有的限制子句，如果该子句也为空，则使用 25。

页面必须从 1 开始。

参数

返回

抛出

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

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

参数

返回

获取结果集工厂。

返回

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

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

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

参数

返回

执行此查询的 SQL，并在返回已更改记录的行数之前立即关闭语句。

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

示例

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

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

返回

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

如果传递的是数组，则键将用于使用值作为要别名的真实字段来别名字段。可以别名字符串、Expression 对象，甚至其他 Query 对象。

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

默认情况下，此函数会将任何传递的参数追加到要选择的字段列表中，除非第二个参数设置为 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->count('*')];
})

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

如果您传递的是 Cake\ORM\Table 或 Cake\ORM\Association 类的实例，则表或关联的模式中的所有字段都将添加到 select 子句中。

参数

返回

除排除字段外，与传递的表关联的所有字段都将添加到查询的 select 子句中。传递的排除字段不应别名。在第一次调用此方法后，第二次调用不能用于删除已通过第一次调用添加到查询中的字段。如果您需要在第一次调用后更改列表，请传递覆盖布尔值 true，它将重置 select 子句，删除所有先前的添加。

参数

返回

行为与 select() 完全相同，除了将字段添加到选定字段列表中，并且不会禁用自动选择关联的字段。

使用此方法来代替调用 select() 然后 enableAutoFields() 来重新启用自动字段。

参数

返回

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

参数

返回

设置连接角色。

参数

返回

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

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

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

参数

返回

另请参见

设置要用于加载关联和存储包含的渴望加载器类的实例。

参数

返回

设置将由此查询使用并构成 FROM 子句的默认 Table 对象。

参数

返回

为查询设置结果集。

设置查询的结果集将使 execute() 成为一个无操作函数。它不会执行 SQL 查询并获取结果，而是返回为此方法提供的结果集。

此方法在与存储在持久缓存中的结果结合使用时最有用。

参数

返回

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

参数

返回

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

参数

返回

覆盖当前值绑定器。

ValueBinder 负责生成查询占位符，并将值暂时关联到这些占位符，以便可以将它们正确传递到语句对象。

参数

返回

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

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

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

参数

返回

在执行查询后，返回结果的数组表示形式。

返回

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

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

示例

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

参数

返回

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

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

参数

返回

将迭代提供的部分。

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

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

示例

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

参数

返回

在查询的存储库对象上触发 beforeFind 事件。

只会触发一次，并且只针对选择查询。

返回

返回此查询的类型（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

参数

返回

将连接角色设置为读取。

返回

将连接角色设置为写入。

返回

添加一个条件或一组条件，用于此查询的 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')

您可以使用连接随意嵌套条件。有时，您可能希望为同一个键定义 2 个不同的选项，在这种情况下，您可以将每个条件包装在一个新数组中

$query->where(['OR' => [['published' => false], ['published' => true]])

请记住，每次使用第三个参数设置为 false（默认值）调用 where() 时，它将使用 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 注入。如果您使用字符串条件，请确保您的值已正确引用。最安全的方法是永远不要使用字符串条件。

参数

返回

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

与 where() 不同，此方法允许空输入，前提是您将 'allowEmpty' 设置为 true。在没有适当的完整性检查的情况下使用它要小心。

选项

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

参数

返回

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

与 where() 不同，此方法允许空输入，前提是您将 'allowEmpty' 设置为 true。在没有适当的完整性检查的情况下使用它要小心。

参数

返回

添加一个 NOT IN 条件或一组条件，用于此查询的 WHERE 子句中。这还允许字段为 null，并使用 IS 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);
});

参数

返回