APPEND
APPEND = 0 : integer
Indicates that the operation should append to the list
Extends the base Query class to provide new methods related to association loading, automatic fields selection, automatic type casting and to wrap results into a specific iterator that will be responsible for hydrating results if required.
$_repository : \Cake\Datasource\RepositoryInterface
Instance of a table object this query is bound to
$_results : \Cake\Datasource\ResultSetInterface|null
A ResultSet.
When set, query execution will be bypassed.
$_cache : \Cake\Datasource\QueryCacher|null
A query cacher instance if this query has caching enabled.
$_connection : \Cake\Database\Connection
Connection instance to be used to execute this query.
$_iterator : \Cake\Database\StatementInterface|null
Statement object resulting from executing this query.
$_valueBinder : \Cake\Database\ValueBinder|null
The object responsible for generating query placeholders and temporarily store values associated to each of those.
$_functionsBuilder : \Cake\Database\FunctionsBuilder|null
Instance of functions builder object used for generating arbitrary SQL functions.
$_selectTypeMap : \Cake\Database\TypeMap
The Type map for fields in the select clause
$_typeMap : \Cake\Database\TypeMap
$_eagerLoader : \Cake\ORM\EagerLoader
Instance of a class responsible for storing association containments and for eager loading them when this query is executed
repository(\Cake\Datasource\RepositoryInterface|null $table = null) : \Cake\Datasource\RepositoryInterface|$this
Returns the default table object that will be used by this query, that is, the table that will appear in the from clause.
When called with a Table argument, the default table object will be set and this query object will be returned for chaining.
| \Cake\Datasource\RepositoryInterface|null | $table | The default table object to use |
getRepository() : \Cake\Datasource\RepositoryInterface
Returns the default table object that will be used by this query, that is, the table that will appear in the from clause.
setResult(\Cake\Datasource\ResultSetInterface $results) : $this
Set the result set for a query.
Setting the resultset of a query will make execute() a no-op. Instead of executing the SQL query and fetching results, the ResultSet provided to this method will be returned.
This method is most useful when combined with results stored in a persistent cache.
| \Cake\Datasource\ResultSetInterface | $results | The results this query should return. |
getIterator() : \Cake\Database\StatementInterface|null
Executes this query and returns a results iterator. This function is required for implementing the IteratorAggregate interface and allows the query to be iterated without having to call execute() manually, thus making it look like a result set instead of the query itself.
aliasField(string $field, string|null $alias = null) : array
Returns a key => value array representing a single aliased field that can be passed directly to the select() method.
The key will contain the alias and the value the actual field name.
If the field is already aliased, then it will not be changed. If no $alias is passed, the default table for this query will be used.
| string | $field | The field to alias |
| string|null | $alias | the alias used to prefix the field |
all() : \Cake\Datasource\ResultSetInterface
Fetch the results for this query.
Will return either the results set through setResult(), or execute this query and return the ResultSetDecorator object ready for streaming of results.
ResultSetDecorator is a traversable object that implements the methods found on Cake\Collection\Collection.
if this method is called on a non-select Query.
mapReduce(callable|null $mapper = null, callable|null $reducer = null, boolean $overwrite = false) : $this|array
Register a new MapReduce routine to be executed on top of the database results Both the mapper and caller callable should be invokable objects.
The MapReduce routing will only be run when the query is executed and the first result is attempted to be fetched.
If the first argument is set to null, it will return the list of previously registered map reduce routines. This is deprecated as of 3.6.0 - use getMapReducers() instead.
If the third argument is set to true, it will erase previous map reducers and replace it with the arguments passed.
| callable|null | $mapper | The mapper callable. |
| callable|null | $reducer | The reducing function. |
| boolean | $overwrite | Set to true to overwrite existing map + reduce functions. |
formatResults(callable|null $formatter = null, boolean|integer $mode) : $this|array
Registers a new formatter callback function that is to be executed when trying to fetch the results from the database.
Formatting callbacks will get a first parameter, an object implementing
\Cake\Collection\CollectionInterface, that can be traversed and modified at will.
Callbacks are required to return an iterator object, which will be used as
the return value for this query's result. Formatter functions are applied
after all the MapReduce routines for this query have been executed.
If the first argument is set to null, it will return the list of previously registered format routines. This is deprecated as of 3.6.0 - use getResultFormatters() instead.
If the second argument is set to true, it will erase previous formatters and replace them with the passed first argument.
// Return all results from the table indexed by id
$query->select(['id', 'name'])->formatResults(function ($results) {
return $results->indexBy('id');
});
// Add a new column to the 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;
});
});| callable|null | $formatter | The formatting callable. |
| boolean|integer | $mode | Whether or not to overwrite, append or prepend the formatter. |
first() : \Cake\Datasource\EntityInterface|array|null
Returns the first result out of executing this query, if the query has not been executed before, it will set the limit clause to 1 for performance reasons.
$singleUser = $query->select(['id', 'username'])->first();The first result from the ResultSet.
firstOrFail() : \Cake\Datasource\EntityInterface|array
Get the first result from the executing query or raise an exception.
When there is no first record.
The first result from the ResultSet.
getOptions() : array
Returns an array with the custom options that were applied to this query and that were not already processed by another method in this class.
$query->applyOptions(['doABarrelRoll' => true, 'fields' => ['id', 'name']);
$query->getOptions(); // Returns ['doABarrelRoll' => true]applyOptions(array $options) : $this
Populates or adds parts to current query clauses using an array.
Populates or adds parts to current query clauses using an array. This is handy for passing all query clauses at once. The option array accepts:
$query->applyOptions([
'fields' => ['id', 'name'],
'conditions' => [
'created >=' => '2013-01-01'
],
'limit' => 10
]);Is equivalent to:
$query
->select(['id', 'name'])
->where(['created >=' => '2013-01-01'])
->limit(10)| array | $options | list of query clauses to apply new parts to. |
__construct(\Cake\Database\Connection $connection, \Cake\ORM\Table $table)
Constructor
| \Cake\Database\Connection | $connection | The connection object |
| \Cake\ORM\Table | $table | The table this query is starting on |
setConnection(\Cake\Database\Connection $connection) : $this
Sets the connection instance to be used for executing and transforming this query.
| \Cake\Database\Connection | $connection | Connection instance |
getConnection() : \Cake\Database\Connection
Gets the connection instance to be used for executing and transforming this query.
connection(\Cake\Database\Connection|null $connection = null) : $this|\Cake\Database\Connection
Sets the connection instance to be used for executing and transforming this query When called with a null argument, it will return the current connection instance.
| \Cake\Database\Connection|null | $connection | Connection instance |
execute() : \Cake\Database\StatementInterface
Compiles the SQL representation of this query and executes it using the configured connection object. Returns the resulting statement object.
Executing a query internally executes several steps, the first one is letting the connection transform this object to fit its particular dialect, this might result in generating a different Query object that will be the one to actually be executed. Immediately after, literal values are passed to the connection so they are bound to the query in a safe way. Finally, the resulting statement is decorated with custom objects to execute callbacks for each row retrieved if necessary.
Resulting statement is traversable, so it can be used in any loop as you would with an array.
This method can be overridden in query subclasses to decorate behavior around query execution.
rowCountAndClose() : integer
Executes the SQL of this query and immediately closes the statement before returning the row count of records changed.
This method can be used with UPDATE and DELETE queries, but is not recommended for SELECT queries and is not used to count records.
$rowCount = $query->update('articles')
->set(['published'=>true])
->where(['published'=>false])
->rowCountAndClose();The above example will change the published column to true for all false records, and return the number of records that were updated.
sql(\Cake\Database\ValueBinder $binder = null) : string
Returns the SQL representation of this object.
This function will compile this query to make it compatible with the SQL dialect that is used by the connection, This process might add, remove or alter any query part or internal expression to make it executable in the target platform.
The resulting query may have placeholders that will be replaced with the actual values when the query is executed, hence it is most suitable to use with prepared statements.
| \Cake\Database\ValueBinder | $binder |
traverse(callable $visitor, array<mixed,string> $parts = array()) : $this
Will iterate over every specified part. Traversing functions can aggregate results using variables in the closure or instance variables. This function is commonly used as a way for traversing all query parts that are going to be used for constructing a query.
The callback will receive 2 parameters, the first one is the value of the query part that is being iterated and the second the name of such part.
$query->select(['title'])->from('articles')->traverse(function ($value, $clause) {
if ($clause === 'select') {
var_dump($value);
}
}, ['select', 'from']);| callable | $visitor | A function or callable to be executed for each part |
| array<mixed,string> | $parts | The query clauses to traverse |
select(array|\Cake\Database\ExpressionInterface|callable|string|\Cake\ORM\Table|\Cake\ORM\Association $fields = array(), boolean $overwrite = false) : $this
Adds new fields to be returned by a `SELECT` statement when this query is executed. Fields can be passed as an array of strings, array of expression objects, a single expression or a single string.
If an array is passed, keys will be used to alias fields using the value as the real field to be aliased. It is possible to alias strings, Expression objects or even other Query objects.
If a callable function is passed, the returning array of the function will be used as the list of fields.
By default this function will append any passed argument to the list of fields to be selected, unless the second argument is set to 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('*')];
})By default no fields are selected, if you have an instance of Cake\ORM\Query and try to append
fields you should also call Cake\ORM\Query::enableAutoFields() to select the default fields
from the table.
If you pass an instance of a Cake\ORM\Table or Cake\ORM\Association class,
all the fields in the schema of the table or the association will be added to
the select clause.
| array|\Cake\Database\ExpressionInterface|callable|string|\Cake\ORM\Table|\Cake\ORM\Association | $fields | fields to be added to the list. |
| boolean | $overwrite | whether to reset fields with passed list or not |
distinct(array|\Cake\Database\ExpressionInterface|string|boolean $on = array(), boolean $overwrite = false) : $this
Adds a `DISTINCT` clause to the query to remove duplicates from the result set.
This clause can only be used for select statements.
If you wish to filter duplicates based of those rows sharing a particular field or set of fields, you may pass an array of fields to filter on. Beware that this option might not be fully supported in all database systems.
// 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);| array|\Cake\Database\ExpressionInterface|string|boolean | $on | Enable/disable distinct class or list of fields to be filtered on |
| boolean | $overwrite | whether to reset fields with passed list or not |
modifier(array|\Cake\Database\ExpressionInterface|string $modifiers, boolean $overwrite = false) : $this
Adds a single or multiple `SELECT` modifiers to be used in the `SELECT`.
By default this function will append any passed argument to the list of modifiers to be applied, unless the second argument is set to 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| array|\Cake\Database\ExpressionInterface|string | $modifiers | modifiers to be applied to the query |
| boolean | $overwrite | whether to reset order with field list or not |
from(array|string $tables = array(), boolean $overwrite = false) : $this|array
Adds a single or multiple tables to be used in the FROM clause for this query.
Tables can be passed as an array of strings, array of expression objects, a single expression or a single string.
If an array is passed, keys will be used to alias tables using the value as the real field to be aliased. It is possible to alias strings, ExpressionInterface objects or even other Query objects.
By default this function will append any passed argument to the list of tables to be selected from, unless the second argument is set to true.
This method can be used for select, update and delete statements.
$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 | tables to be added to the list. This argument, can be passed as an array of strings, array of expression objects, or a single string. See the examples above for the valid call types. |
| boolean | $overwrite | whether to reset tables with passed list or not |
join(array|string|null $tables = null, array $types = array(), boolean $overwrite = false) : $this|array
Adds a single or multiple tables to be used as JOIN clauses to this query.
Tables can be passed as an array of strings, an array describing the join parts, an array with multiple join descriptions, or a single string.
By default this function will append any passed argument to the list of tables to be joined, unless the third argument is set to true.
When no join type is specified an INNER JOIN is used by default:
$query->join(['authors']) will produce INNER JOIN authors ON 1 = 1
It is also possible to alias joins using the array key:
$query->join(['a' => 'authors']) will produce INNER JOIN authors a ON 1 = 1
A join can be fully described and aliased using the array notation:
$query->join([
'a' => [
'table' => 'authors',
'type' => 'LEFT',
'conditions' => 'a.id = b.author_id'
]
]);
// Produces LEFT JOIN authors a ON a.id = b.author_idYou can even specify multiple joins in an array, including the full description:
$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"Conditions can be expressed, as in the examples above, using a string for comparing columns, or string with already quoted literal values. Additionally it is possible to use conditions expressed in arrays or expression objects.
When using arrays for expressing conditions, it is often desirable to convert the literal values to the correct database representation. This is achieved using the second parameter of this function.
$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'])When creating aliased joins using the array notation, you can override previous join definitions by using the same alias in consequent calls to this function or you can replace all previously defined joins with another list if the third parameter for this function is set to 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|null | $tables | list of tables to be joined in the query |
| array | $types | associative array of type names used to bind values to query |
| boolean | $overwrite | whether to reset joins with passed list or not |
leftJoin(string|array $table, string|array|\Cake\Database\ExpressionInterface $conditions = array(), array $types = array()) : $this
Adds a single `LEFT JOIN` clause to the query.
This is a shorthand method for building joins via join().
The table name can be passed as a string, or as an array in case it needs to be aliased:
// 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');Conditions can be passed as strings, arrays, or expression objects. When
using arrays it is possible to combine them with the $types parameter
in order to define how to convert the values:
$query->leftJoin(['a' => 'articles'], [
'a.posted >=' => new DateTime('-3 days'),
'a.published' => true,
'a.author_id = authors.id'
], ['a.posted' => 'datetime', 'a.published' => 'boolean']);See join() for further details on conditions and types.
| string|array | $table | The table to join with |
| string|array|\Cake\Database\ExpressionInterface | $conditions | The conditions to use for joining. |
| array | $types | a list of types associated to the conditions used for converting values to the corresponding database representation. |
rightJoin(string|array $table, string|array|\Cake\Database\ExpressionInterface $conditions = array(), array $types = array()) : $this
Adds a single `RIGHT JOIN` clause to the query.
This is a shorthand method for building joins via join().
The arguments of this method are identical to the leftJoin() shorthand, please refer
to that methods description for further details.
| string|array | $table | The table to join with |
| string|array|\Cake\Database\ExpressionInterface | $conditions | The conditions to use for joining. |
| array | $types | a list of types associated to the conditions used for converting values to the corresponding database representation. |
innerJoin(string|array $table, string|array|\Cake\Database\ExpressionInterface $conditions = array(), array $types = array()) : $this
Adds a single `INNER JOIN` clause to the query.
This is a shorthand method for building joins via join().
The arguments of this method are identical to the leftJoin() shorthand, please refer
to that methods description for further details.
| string|array | $table | The table to join with |
| string|array|\Cake\Database\ExpressionInterface | $conditions | The conditions to use for joining. |
| array | $types | a list of types associated to the conditions used for converting values to the corresponding database representation. |
where(string|array|\Cake\Database\ExpressionInterface|callable|null $conditions = null, array $types = array(), boolean $overwrite = false) : $this
Adds a condition or set of conditions to be used in the WHERE clause for this query. Conditions can be expressed as an array of fields as keys with comparison operators in it, the values for the array will be used for comparing the field to such literal. Finally, conditions can be expressed as a single string or an array of strings.
When using arrays, each entry will be joined to the rest of the conditions using
an AND operator. Consecutive calls to this function will also join the new
conditions specified using the AND operator. Additionally, values can be
expressed using expression objects which can include other query objects.
Any conditions created with this methods can be used with any SELECT, UPDATE
and DELETE type of queries.
$query->where([
'posted >=' => new DateTime('3 days ago'),
'title LIKE' => 'Hello W%',
'author_id' => 1,
], ['posted' => 'datetime']);The previous example produces:
WHERE posted >= 2012-01-27 AND title LIKE 'Hello W%' AND author_id = 1
Second parameter is used to specify what type is expected for each passed key. Valid types can be used from the mapped with Database\Type class.
$query->where([
'author_id !=' => 1,
'OR' => ['published' => true, 'posted <' => new DateTime('now')],
'NOT' => ['title' => 'Hello']
], ['published' => boolean, 'posted' => 'datetime']The previous example produces:
WHERE author_id = 1 AND (published = 1 OR posted < '2012-02-01') AND NOT (title = 'Hello')
You can nest conditions using conjunctions as much as you like. Sometimes, you may want to define 2 different options for the same key, in that case, you can wrap each condition inside a new array:
$query->where(['OR' => [['published' => false], ['published' => true]])
Would result in:
WHERE (published = false) OR (published = true)
Keep in mind that every time you call where() with the third param set to false
(default), it will join the passed conditions to the previous stored list using
the AND operator. Also, using the same array key twice in consecutive calls to
this method will not override the previous value.
$exp = $query->newExpr()->add(['id !=' => 100, 'author_id' != 1])->tieWith('OR');
$query->where(['published' => true], ['published' => 'boolean'])->where($exp);The previous example produces:
WHERE (id != 100 OR author_id != 1) AND published = 1
Other Query objects that be used as conditions for any field.
You can use callable functions to construct complex expressions, functions
receive as first argument a new QueryExpression object and this query instance
as second argument. Functions must return an expression object, that will be
added the list of conditions for the query using the AND operator.
$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']);The previous example produces:
WHERE articles.author_id = authors.id AND modified IS NULL
Please note that when using the array notation or the expression objects, all values will be correctly quoted and transformed to the correspondent database data type automatically for you, thus securing your application from SQL injections. The keys however, are not treated as unsafe input, and should be sanitized/whitelisted.
If you use string conditions make sure that your values are correctly quoted. The safest thing you can do is to never use string conditions.
| string|array|\Cake\Database\ExpressionInterface|callable|null | $conditions | The conditions to filter on. |
| array | $types | associative array of type names used to bind values to query |
| boolean | $overwrite | whether to reset conditions with passed list or not |
whereNotNull(array|string|\Cake\Database\ExpressionInterface $fields) : $this
Convenience method that adds a NOT NULL condition to the query
| array|string|\Cake\Database\ExpressionInterface | $fields | A single field or expressions or a list of them that should be not null |
whereNull(array|string|\Cake\Database\ExpressionInterface $fields) : $this
Convenience method that adds a IS NULL condition to the query
| array|string|\Cake\Database\ExpressionInterface | $fields | A single field or expressions or a list of them that should be null |
whereInList(string $field, array $values, array $options = array()) : $this
Adds an IN condition or set of conditions to be used in the WHERE clause for this query.
This method does allow empty inputs in contrast to where() if you set 'allowEmpty' to true. Be careful about using it without proper sanity checks.
Options:
types - Associative array of type names used to bind values to queryallowEmpty - Allow empty array.| string | $field | Field |
| array | $values | Array of values |
| array | $options | Options |
whereNotInList(string $field, array $values, array $options = array()) : $this
Adds a NOT IN condition or set of conditions to be used in the WHERE clause for this query.
This method does allow empty inputs in contrast to where() if you set 'allowEmpty' to true. Be careful about using it without proper sanity checks.
| string | $field | Field |
| array | $values | Array of values |
| array | $options | Options |
andWhere(string|array|\Cake\Database\ExpressionInterface|callable $conditions, array $types = array()) : $this
Connects any previously defined set of conditions to the provided list using the AND operator. This function accepts the conditions list in the same format as the method `where` does, hence you can use arrays, expression objects callback functions or strings.
It is important to notice that when calling this function, any previous set of conditions defined for this query will be treated as a single argument for the AND operator. This function will not only operate the most recently defined condition, but all the conditions as a whole.
When using an array for defining conditions, creating constraints form each
array entry will use the same logic as with the where() function. This means
that each array entry will be joined to the other using the AND operator, unless
you nest the conditions in the array using other operator.
$query->where(['title' => 'Hello World')->andWhere(['author_id' => 1]);Will produce:
WHERE title = 'Hello World' AND author_id = 1
$query
->where(['OR' => ['published' => false, 'published is NULL']])
->andWhere(['author_id' => 1, 'comments_count >' => 10])Produces:
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]);
});Generates the following conditions:
WHERE (title = 'Foo') AND (author_id = 1 OR author_id = 2)
| string|array|\Cake\Database\ExpressionInterface|callable | $conditions | The conditions to add with AND. |
| array | $types | associative array of type names used to bind values to query |
orWhere(string|array|\Cake\Database\ExpressionInterface|callable $conditions, array $types = array()) : $this
Connects any previously defined set of conditions to the provided list using the OR operator. This function accepts the conditions list in the same format as the method `where` does, hence you can use arrays, expression objects callback functions or strings.
It is important to notice that when calling this function, any previous set of conditions defined for this query will be treated as a single argument for the OR operator. This function will not only operate the most recently defined condition, but all the conditions as a whole.
When using an array for defining conditions, creating constraints form each
array entry will use the same logic as with the where() function. This means
that each array entry will be joined to the other using the OR operator, unless
you nest the conditions in the array using other operator.
$query->where(['title' => 'Hello World')->orWhere(['title' => 'Foo']);Will produce:
WHERE title = 'Hello World' OR title = 'Foo'
$query
->where(['OR' => ['published' => false, 'published is NULL']])
->orWhere(['author_id' => 1, 'comments_count >' => 10])Produces:
WHERE (published = 0 OR published IS NULL) OR (author_id = 1 AND comments_count > 10)
$query
->where(['title' => 'Foo'])
->orWhere(function ($exp, $query) {
return $exp
->or_(['author_id' => 1])
->add(['author_id' => 2]);
});Generates the following conditions:
WHERE (title = 'Foo') OR (author_id = 1 OR author_id = 2)
| string|array|\Cake\Database\ExpressionInterface|callable | $conditions | The conditions to add with OR. |
| array | $types | associative array of type names used to bind values to query |
order(array|\Cake\Database\ExpressionInterface|callable|string $fields, boolean $overwrite = false) : $this
Adds a single or multiple fields to be used in the ORDER clause for this query.
Fields can be passed as an array of strings, array of expression objects, a single expression or a single string.
If an array is passed, keys will be used as the field itself and the value will represent the order in which such field should be ordered. When called multiple times with the same fields as key, the last order definition will prevail over the others.
By default this function will append any passed argument to the list of fields to be selected, unless the second argument is set to true.
$query->order(['title' => 'DESC', 'author_id' => 'ASC']);Produces:
ORDER BY title DESC, author_id ASC
$query->order(['title' => 'DESC NULLS FIRST'])->order('author_id');Will generate:
ORDER BY title DESC NULLS FIRST, author_id
$expression = $query->newExpr()->add(['id % 2 = 0']);
$query->order($expression)->order(['title' => 'ASC']);and
$query->order(function ($exp, $query) {
return [$exp->add(['id % 2 = 0']), 'title' => 'ASC'];
});Will both become:
ORDER BY (id %2 = 0), title ASC
Order fields/directions are not sanitized by the query builder.
You should use a whitelist of fields/directions when passing
in user-supplied data to order().
If you need to set complex expressions as order conditions, you
should use orderAsc() or orderDesc().
| array|\Cake\Database\ExpressionInterface|callable|string | $fields | fields to be added to the list |
| boolean | $overwrite | whether to reset order with field list or not |
orderAsc(string|\Cake\Database\Expression\QueryExpression $field, boolean $overwrite = false) : $this
Add an ORDER BY clause with an ASC direction.
This method allows you to set complex expressions as order conditions unlike order()
Order fields are not suitable for use with user supplied data as they are not sanitized by the query builder.
| string|\Cake\Database\Expression\QueryExpression | $field | The field to order on. |
| boolean | $overwrite | Whether or not to reset the order clauses. |
orderDesc(string|\Cake\Database\Expression\QueryExpression $field, boolean $overwrite = false) : $this
Add an ORDER BY clause with a DESC direction.
This method allows you to set complex expressions as order conditions unlike order()
Order fields are not suitable for use with user supplied data as they are not sanitized by the query builder.
| string|\Cake\Database\Expression\QueryExpression | $field | The field to order on. |
| boolean | $overwrite | Whether or not to reset the order clauses. |
group(array|\Cake\Database\ExpressionInterface|string $fields, boolean $overwrite = false) : $this
Adds a single or multiple fields to be used in the GROUP BY clause for this query.
Fields can be passed as an array of strings, array of expression objects, a single expression or a single string.
By default this function will append any passed argument to the list of fields to be grouped, unless the second argument is set to true.
// Produces GROUP BY id, title
$query->group(['id', 'title']);
// Produces GROUP BY title
$query->group('title');Group fields are not suitable for use with user supplied data as they are not sanitized by the query builder.
| array|\Cake\Database\ExpressionInterface|string | $fields | fields to be added to the list |
| boolean | $overwrite | whether to reset fields with passed list or not |
having(string|array|\Cake\Database\ExpressionInterface|callable|null $conditions = null, array $types = array(), boolean $overwrite = false) : $this
Adds a condition or set of conditions to be used in the `HAVING` clause for this query. This method operates in exactly the same way as the method `where()` does. Please refer to its documentation for an insight on how to using each parameter.
Having fields are not suitable for use with user supplied data as they are not sanitized by the query builder.
| string|array|\Cake\Database\ExpressionInterface|callable|null | $conditions | The having conditions. |
| array | $types | associative array of type names used to bind values to query |
| boolean | $overwrite | whether to reset conditions with passed list or not |
andHaving(string|array|\Cake\Database\ExpressionInterface|callable $conditions, array $types = array()) : $this
Connects any previously defined set of conditions to the provided list using the AND operator in the HAVING clause. This method operates in exactly the same way as the method `andWhere()` does. Please refer to its documentation for an insight on how to using each parameter.
Having fields are not suitable for use with user supplied data as they are not sanitized by the query builder.
| string|array|\Cake\Database\ExpressionInterface|callable | $conditions | The AND conditions for HAVING. |
| array | $types | associative array of type names used to bind values to query |
orHaving(string|array|\Cake\Database\ExpressionInterface|callable $conditions, array $types = array()) : $this
Connects any previously defined set of conditions to the provided list using the OR operator in the HAVING clause. This method operates in exactly the same way as the method `orWhere()` does. Please refer to its documentation for an insight on how to using each parameter.
Having fields are not suitable for use with user supplied data as they are not sanitized by the query builder.
| string|array|\Cake\Database\ExpressionInterface|callable | $conditions | The OR conditions for HAVING. |
| array | $types | associative array of type names used to bind values to query. |
page(integer $num, integer|null $limit = null) : $this
Set the page of results you want.
This method provides an easier to use interface to set the limit + offset
in the record set you want as results. If empty the limit will default to
the existing limit clause, and if that too is empty, then 25 will be used.
Pages must start at 1.
| integer | $num | The page number you want. |
| integer|null | $limit | The number of rows you want in the page. If null the current limit clause will be used. |
If page number < 1.
limit(integer|\Cake\Database\ExpressionInterface $num) : $this
Sets the number of records that should be retrieved from database, accepts an integer or an expression object that evaluates to an integer.
In some databases, this operation might not be supported or will require the query to be transformed in order to limit the result set size.
$query->limit(10) // generates LIMIT 10
$query->limit($query->newExpr()->add(['1 + 1'])); // LIMIT (1 + 1)| integer|\Cake\Database\ExpressionInterface | $num | number of records to be returned |
offset(integer|\Cake\Database\ExpressionInterface $num) : $this
Sets the number of records that should be skipped from the original result set This is commonly used for paginating large results. Accepts an integer or an expression object that evaluates to an integer.
In some databases, this operation might not be supported or will require the query to be transformed in order to limit the result set size.
$query->offset(10) // generates OFFSET 10
$query->offset($query->newExpr()->add(['1 + 1'])); // OFFSET (1 + 1)| integer|\Cake\Database\ExpressionInterface | $num | number of records to be skipped |
union(string|\Cake\Database\Query $query, boolean $overwrite = false) : $this
Adds a complete query to be used in conjunction with an UNION operator with this query. This is used to combine the result set of this query with the one that will be returned by the passed query. You can add as many queries as you required by calling multiple times this method with different queries.
By default, the UNION operator will remove duplicate rows, if you wish to include every row for all queries, use unionAll().
$union = (new Query($conn))->select(['id', 'title'])->from(['a' => 'articles']);
$query->select(['id', 'name'])->from(['d' => 'things'])->union($union);Will produce:
SELECT id, name FROM things d UNION SELECT id, title FROM articles a
| string|\Cake\Database\Query | $query | full SQL query to be used in UNION operator |
| boolean | $overwrite | whether to reset the list of queries to be operated or not |
unionAll(string|\Cake\Database\Query $query, boolean $overwrite = false) : $this
Adds a complete query to be used in conjunction with the UNION ALL operator with this query. This is used to combine the result set of this query with the one that will be returned by the passed query. You can add as many queries as you required by calling multiple times this method with different queries.
Unlike UNION, UNION ALL will not remove duplicate rows.
$union = (new Query($conn))->select(['id', 'title'])->from(['a' => 'articles']);
$query->select(['id', 'name'])->from(['d' => 'things'])->unionAll($union);Will produce:
SELECT id, name FROM things d UNION ALL SELECT id, title FROM articles a
| string|\Cake\Database\Query | $query | full SQL query to be used in UNION operator |
| boolean | $overwrite | whether to reset the list of queries to be operated or not |
insert(array $columns, array $types = array()) : $this
Create an insert query.
This changes the query type to be 'insert'. Note calling this method will reset any data previously set with Query::values()
Can be combined with the where() method to create delete queries.
| array | $columns | The columns to insert into. |
| array | $types | A map between columns & their datatypes. |
identifier(string $identifier) : \Cake\Database\ExpressionInterface
Creates an expression that refers to an identifier. Identifiers are used to refer to field names and allow the SQL compiler to apply quotes or escape the identifier.
The value is used as is, and you might be required to use aliases or include the table reference in the identifier. Do not use this method to inject SQL methods or logical statements.
$query->newExp()->lte('count', $query->identifier('total'));| string | $identifier | The identifier for an expression |
values(array|\Cake\Database\Query $data) : $this
Set the values for an insert query.
Multi inserts can be performed by calling values() more than one time, or by providing an array of value sets. Additionally $data can be a Query instance to insert data from another SELECT statement.
| array|\Cake\Database\Query | $data | The data to insert. |
if you try to set values before declaring columns. Or if you try to set values on non-insert queries.
set(string|array|callable|\Cake\Database\Expression\QueryExpression $key, mixed $value = null, array $types = array()) : $this
Set one or many fields to update.
Passing a string:
$query->update('articles')->set('title', 'The Title');Passing an array:
$query->update('articles')->set(['title' => 'The Title'], ['title' => 'string']);Passing a callable:
$query->update('articles')->set(function ($exp) {
return $exp->eq('title', 'The title', 'string');
});| string|array|callable|\Cake\Database\Expression\QueryExpression | $key | The column name or array of keys
|
| mixed | $value | The value to update $key to. Can be null if $key is an array or QueryExpression. When $key is an array, this parameter will be used as $types instead. |
| array | $types | The column types to treat data as. |
epilog(string|\Cake\Database\Expression\QueryExpression|null $expression = null) : $this
A string or expression that will be appended to the generated query
$query->select('id')->where(['author_id' => 1])->epilog('FOR UPDATE');
$query
->insert('articles', ['title'])
->values(['author_id' => 1])
->epilog('RETURNING id');Epliog content is raw SQL and not suitable for use with user supplied data.
| string|\Cake\Database\Expression\QueryExpression|null | $expression | The expression to be appended |
newExpr(mixed $rawExpression = null) : \Cake\Database\Expression\QueryExpression
Returns a new QueryExpression object. This is a handy function when building complex queries using a fluent interface. You can also override this function in subclasses to use a more specialized QueryExpression class if required.
You can optionally pass a single raw SQL string or an array or expressions in any format accepted by \Cake\Database\Expression\QueryExpression:
$expression = $query->newExpr(); // Returns an empty expression object
$expression = $query->newExpr('Table.column = Table2.column'); // Return a raw SQL expression| mixed | $rawExpression | A string, array or anything you want wrapped in an expression object |
func() : \Cake\Database\FunctionsBuilder
Returns an instance of a functions builder object that can be used for generating arbitrary SQL functions.
$query->func()->count('*');
$query->func()->dateDiff(['2012-01-05', '2012-01-02'])clause(string $name) : mixed
Returns any data that was stored in the specified clause. This is useful for modifying any internal part of the query and it is used by the SQL dialects to transform the query accordingly before it is executed. The valid clauses that can be retrieved are: delete, update, set, insert, values, select, distinct, from, join, set, where, group, having, order, limit, offset and union.
The return value for each of those parts may vary. Some clauses use QueryExpression to internally store their state, some use arrays and others may use booleans or integers. This is summary of the return types for each clause.
| string | $name | name of the clause to be returned |
When the named clause does not exist.
decorateResults(callable|null $callback, boolean $overwrite = false) : $this
Registers a callback to be executed for each result that is fetched from the result set, the callback function will receive as first parameter an array with the raw data from the database for every row that is fetched and must return the row with any possible modifications.
Callbacks will be executed lazily, if only 3 rows are fetched for database it will called 3 times, event though there might be more rows to be fetched in the cursor.
Callbacks are stacked in the order they are registered, if you wish to reset the stack the call this function with the second parameter set to true.
If you wish to remove all decorators from the stack, set the first parameter to null and the second to true.
$query->decorateResults(function ($row) {
$row['order_total'] = $row['subtotal'] + ($row['subtotal'] * $row['tax']);
return $row;
});| callable|null | $callback | The callback to invoke when results are fetched. |
| boolean | $overwrite | Whether or not this should append or replace all existing decorators. |
traverseExpressions(callable $callback) : $this|null
This function works similar to the traverse() function, with the difference that it does a full depth traversal of the entire expression tree. This will execute the provided callback function for each ExpressionInterface object that is stored inside this query at any nesting depth in any part of the query.
Callback will receive as first parameter the currently visited expression.
| callable | $callback | the function to be executed for each ExpressionInterface found inside this query. |
bind(string|integer $param, mixed $value, string|integer $type = 'string') : $this
Associates a query placeholder to a value and a type.
If type is expressed as "atype[]" (note braces) then it will cause the placeholder to be re-written dynamically so if the value is an array, it will create as many placeholders as values are in it. For example:
$query->bind(':id', [1, 2, 3], 'int[]');Will create 3 int placeholders. When using named placeholders, this method
requires that the placeholders include : e.g. :value.
| string|integer | $param | placeholder to be replaced with quoted version of $value |
| mixed | $value | The value to be bound |
| string|integer | $type | the mapped type name, used for casting when sending to database |
getValueBinder() : \Cake\Database\ValueBinder
Returns the currently used ValueBinder instance.
A ValueBinder is responsible for generating query placeholders and temporarily associate values to those placeholders so that they can be passed correctly to the statement object.
setValueBinder(\Cake\Database\ValueBinder|boolean $binder) : $this
Overwrite the current value binder
A ValueBinder is responsible for generating query placeholders and temporarily associate values to those placeholders so that they can be passed correctly to the statement object.
| \Cake\Database\ValueBinder|boolean | $binder | The binder or false to disable binding. |
valueBinder(\Cake\Database\ValueBinder|false|null $binder = null) : $this|\Cake\Database\ValueBinder
Returns the currently used ValueBinder instance. If a value is passed, it will be set as the new instance to be used.
A ValueBinder is responsible for generating query placeholders and temporarily associate values to those placeholders so that they can be passed correctly to the statement object.
| \Cake\Database\ValueBinder|false|null | $binder | new instance to be set. If no value is passed the default one will be returned |
enableBufferedResults(boolean $enable = true) : $this
Enables/Disables buffered results.
When enabled the results returned by this Query will be buffered. This enables you to iterate a result set multiple times, or both cache and iterate it.
When disabled it will consume less memory as fetched results are not remembered for future iterations.
| boolean | $enable | Whether or not to enable buffering |
isBufferedResultsEnabled() : boolean
Returns whether buffered results are enabled/disabled.
When enabled the results returned by this Query will be buffered. This enables you to iterate a result set multiple times, or both cache and iterate it.
When disabled it will consume less memory as fetched results are not remembered for future iterations.
bufferResults(boolean|null $enable = null) : boolean|$this
Enable/Disable buffered results.
When enabled the results returned by this Query will be buffered. This enables you to iterate a result set multiple times, or both cache and iterate it.
When disabled it will consume less memory as fetched results are not remembered for future iterations.
If called with no arguments, it will return whether or not buffering is enabled.
| boolean|null | $enable | Whether or not to enable buffering |
setSelectTypeMap(\Cake\Database\TypeMap $typeMap) : $this
Sets the TypeMap class where the types for each of the fields in the select clause are stored.
| \Cake\Database\TypeMap | $typeMap | The map object to use |
getSelectTypeMap() : \Cake\Database\TypeMap
Gets the TypeMap class where the types for each of the fields in the select clause are stored.
selectTypeMap(\Cake\Database\TypeMap|null $typeMap = null) : $this|\Cake\Database\TypeMap
Sets the TypeMap class where the types for each of the fields in the select clause are stored.
When called with no arguments, the current TypeMap object is returned.
| \Cake\Database\TypeMap|null | $typeMap | The map object to use |
setTypeMap(array|\Cake\Database\TypeMap $typeMap) : $this
Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.
| array|\Cake\Database\TypeMap | $typeMap | Creates a TypeMap if array, otherwise sets the given TypeMap |
getTypeMap() : \Cake\Database\TypeMap
Returns the existing type map.
typeMap(array|\Cake\Database\TypeMap|null $typeMap = null) : $this|\Cake\Database\TypeMap
Creates a new TypeMap if $typeMap is an array, otherwise returns the existing type map or exchanges it for the given one.
| array|\Cake\Database\TypeMap|null | $typeMap | Creates a TypeMap if array, otherwise sets the given TypeMap |
selectAllExcept(\Cake\ORM\Table|\Cake\ORM\Association $table, array $excludedFields, boolean $overwrite = false) : \Cake\ORM\Query
All the fields associated with the passed table except the excluded fields will be added to the select clause of the query. Passed excluded fields should not be aliased.
After the first call to this method, a second call cannot be used to remove fields that have already been added to the query by the first. If you need to change the list after the first call, pass overwrite boolean true which will reset the select clause removing all previous additions.
| \Cake\ORM\Table|\Cake\ORM\Association | $table | The table to use to get an array of columns |
| array | $excludedFields | The un-aliased column names you do not want selected from $table |
| boolean | $overwrite | Whether to reset/remove previous selected fields |
If Association|Table is not passed in first argument
addDefaultTypes(\Cake\ORM\Table $table) : $this
Hints this object to associate the correct types when casting conditions for the database. This is done by extracting the field types from the schema associated to the passed table object. This prevents the user from repeating themselves when specifying conditions.
This method returns the same query object for chaining.
| \Cake\ORM\Table | $table | The table to pull types from |
setEagerLoader(\Cake\ORM\EagerLoader $instance) : $this
Sets the instance of the eager loader class to use for loading associations and storing containments.
| \Cake\ORM\EagerLoader | $instance | The eager loader to use. |
getEagerLoader() : \Cake\ORM\EagerLoader
Returns the currently configured instance.
eagerLoader(\Cake\ORM\EagerLoader|null $instance = null) : \Cake\ORM\EagerLoader|$this
Sets the instance of the eager loader class to use for loading associations and storing containments. If called with no arguments, it will return the currently configured instance.
| \Cake\ORM\EagerLoader|null | $instance | The eager loader to use. Pass null to get the current eagerloader. |
contain(array|string|null $associations = null, callable|boolean $override = false) : array|$this
Sets the list of associations that should be eagerly loaded along with this query. The list of associated tables passed must have been previously set as associations using the Table API.
// Bring articles' author information
$query->contain('Author');
// Also bring the category and tags associated to each article
$query->contain(['Category', 'Tag']);Associations can be arbitrarily nested using dot notation or nested arrays, this allows this object to calculate joins or any additional queries that must be executed to bring the required associated data.
// 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');It is possible to control the conditions and fields selected for each of the contained associations:
$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]);
}]);Each association might define special options when eager loaded, the allowed options that can be set per association are:
foreignKey: Used to set a different field to match both tables, if set to false
no join conditions will be generated automatically. false can only be used on
joinable associations and cannot be used with hasMany or belongsToMany associations.fields: An array with the fields that should be fetched from the association.finder: The finder to use when loading associated records. Either the name of the
finder as a string, or an array to define options to pass to the finder.queryBuilder: Equivalent to passing a callable instead of an options array.// Set options for the hasMany articles that will be eagerly loaded for an author
$query->contain([
'Articles' => [
'fields' => ['title', 'author_id']
]
]);Finders can be configured to use options.
// Retrieve translations for the articles, but only those for the `en` and `es` locales
$query->contain([
'Articles' => [
'finder' => [
'translations' => [
'locales' => ['en', 'es']
]
]
]
]);When containing associations, it is important to include foreign key columns. Failing to do so will trigger exceptions.
// 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
}
]);If called with no arguments, this function will return an array with with the list of previously configured associations to be contained in the result. This getter part is deprecated as of 3.6.0. Use getContain() instead.
If called with an empty first argument and $override is set to true, the
previous list will be emptied.
| array|string|null | $associations | List of table aliases to be queried. |
| callable|boolean | $override | The query builder for the association, or if associations is an array, a bool on whether to override previous list with the one passed defaults to merging previous list with the new one. |
matching(string $assoc, callable|null $builder = null) : $this
Adds filtering conditions to this query to only bring rows that have a relation to another from an associated table, based on conditions in the associated table.
This function will add entries in the contain graph.
// Bring only articles that were tagged with 'cake'
$query->matching('Tags', function ($q) {
return $q->where(['name' => 'cake']);
);It is possible to filter by deep associations by using dot notation:
// Bring only articles that were commented by 'markstory'
$query->matching('Comments.Users', function ($q) {
return $q->where(['username' => 'markstory']);
);As this function will create INNER JOIN, you might want to consider
calling distinct on this query as you might get duplicate rows if
your conditions don't filter them already. This might be the case, for example,
of the same user commenting more than once in the same article.
// Bring unique articles that were commented by 'markstory'
$query->distinct(['Articles.id'])
->matching('Comments.Users', function ($q) {
return $q->where(['username' => 'markstory']);
);Please note that the query passed to the closure will only accept calling
select, where, andWhere and orWhere on it. If you wish to
add more complex clauses you can do it directly in the main query.
| string | $assoc | The association to filter by |
| callable|null | $builder | a function that will receive a pre-made query object that can be used to add custom conditions or selecting some fields |
leftJoinWith(string $assoc, callable|null $builder = null) : $this
Creates a LEFT JOIN with the passed association table while preserving the foreign key matching and the custom conditions that were originally set for it.
This function will add entries in the contain graph.
// Get the count of articles per user
$usersQuery
->select(['total_articles' => $query->func()->count('Articles.id')])
->leftJoinWith('Articles')
->group(['Users.id'])
->enableAutoFields(true);You can also customize the conditions passed to the 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]);
})
->group(['Users.id'])
->enableAutoFields(true);This will create the following 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.idIt is possible to left join deep associations by using dot notation
// 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']);
)
->group(['Users.id']);Please note that the query passed to the closure will only accept calling
select, where, andWhere and orWhere on it. If you wish to
add more complex clauses you can do it directly in the main query.
| string | $assoc | The association to join with |
| callable|null | $builder | a function that will receive a pre-made query object that can be used to add custom conditions or selecting some fields |
innerJoinWith(string $assoc, callable|null $builder = null) : $this
Creates an INNER JOIN with the passed association table while preserving the foreign key matching and the custom conditions that were originally set for it.
This function will add entries in the contain graph.
// Bring only articles that were tagged with 'cake'
$query->innerJoinWith('Tags', function ($q) {
return $q->where(['name' => 'cake']);
);This will create the following 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.idThis function works the same as matching() with the difference that it
will select no fields from the association.
| string | $assoc | The association to join with |
| callable|null | $builder | a function that will receive a pre-made query object that can be used to add custom conditions or selecting some fields |
notMatching(string $assoc, callable|null $builder = null) : $this
Adds filtering conditions to this query to only bring rows that have no match to another from an associated table, based on conditions in the associated table.
This function will add entries in the contain graph.
// Bring only articles that were not tagged with 'cake'
$query->notMatching('Tags', function ($q) {
return $q->where(['name' => 'cake']);
);It is possible to filter by deep associations by using dot notation:
// Bring only articles that weren't commented by 'markstory'
$query->notMatching('Comments.Users', function ($q) {
return $q->where(['username' => 'markstory']);
);As this function will create a LEFT JOIN, you might want to consider
calling distinct on this query as you might get duplicate rows if
your conditions don't filter them already. This might be the case, for example,
of the same article having multiple comments.
// Bring unique articles that were commented by 'markstory'
$query->distinct(['Articles.id'])
->notMatching('Comments.Users', function ($q) {
return $q->where(['username' => 'markstory']);
);Please note that the query passed to the closure will only accept calling
select, where, andWhere and orWhere on it. If you wish to
add more complex clauses you can do it directly in the main query.
| string | $assoc | The association to filter by |
| callable|null | $builder | a function that will receive a pre-made query object that can be used to add custom conditions or selecting some fields |
cleanCopy() : \Cake\ORM\Query
Creates a copy of this current query, triggers beforeFind and resets some state.
The following state will be cleared:
This method creates query clones that are useful when working with subqueries.
counter(callable|null $counter) : $this
Registers a callable function that will be executed when the `count` method in this query is called. The return value for the function will be set as the return value of the `count` method.
This is particularly useful when you need to optimize a query for returning the count, for example removing unnecessary joins, removing group by or just return an estimated number of rows.
The callback will receive as first argument a clone of this query and not this query itself.
If the first param is a null value, the built-in counter function will be called instead
| callable|null | $counter | The counter value |
hydrate(boolean|null $enable = null) : boolean|$this
Toggle hydrating entities.
If set to false array results will be returned.
| boolean|null | $enable | Use a boolean to set the hydration mode. Null will fetch the current hydration mode. |
A boolean when reading, and $this when setting the mode.
find(string $finder, array $options = array()) : $this
Apply custom finds to against an existing query object.
Allows custom find methods to be combined and applied to each other.
$repository->find('all')->find('recent');The above is an example of stacking multiple finder methods onto a single query.
| string | $finder | The finder method to use. |
| array | $options | The options for the finder. |
Returns a modified query.
jsonSerialize() : \Cake\Datasource\ResultSetInterface
Executes the query and converts the result set into JSON.
Part of JsonSerializable interface.
The data to convert to JSON.
enableAutoFields(boolean $value = true) : $this
Sets whether or not the ORM should automatically append fields.
By default calling select() will disable auto-fields. You can re-enable auto-fields with this method.
| boolean | $value | Set true to enable, false to disable. |
autoFields(boolean|null $value = null) : boolean|$this
Get/Set whether or not the ORM should automatically append fields.
By default calling select() will disable auto-fields. You can re-enable auto-fields with this method.
| boolean|null | $value | The value to set or null to read the current value. |
Either the current value or the query object.
nest(mixed $k, mixed $p, mixed $n = 'children') : \Cake\Collection\CollectionInterface
Creates a tree structure by nesting the values of column $p into that with the same value for $k using $n as the nesting key.
| mixed | $k | |
| mixed | $p | |
| mixed | $n |
zipWith(mixed $collections, callable $callable) : \Cake\Collection\CollectionInterface
Returns each of the results out of calling $c with the first rows of the query and each of the items, then the second rows and so on.
| mixed | $collections | |
| callable | $callable |
_execute() : \Cake\ORM\ResultSet
Executes this query and returns a ResultSet object containing the results.
This will also setup the correct statement class in order to eager load deep associations.
_decorateResults(\Traversable $result) : \Cake\Datasource\ResultSetInterface
Decorates the results iterator with MapReduce routines and formatters
| \Traversable | $result | Original results |
_makeJoin(string|array $table, string|array|\Cake\Database\ExpressionInterface $conditions, string $type) : array
Returns an array that can be passed to the join method describing a single join clause
| string|array | $table | The table to join with |
| string|array|\Cake\Database\ExpressionInterface | $conditions | The conditions to use for joining. |
| string | $type | the join type to use |
_decorateStatement(\Cake\Database\StatementInterface $statement) : \Cake\Database\Statement\CallbackStatement
Auxiliary function used to wrap the original statement from the driver with any registered callbacks.
| \Cake\Database\StatementInterface | $statement | to be decorated |
_conjugate(string $part, string|null|array|\Cake\Database\ExpressionInterface|callable $append, string $conjunction, array $types) : void
Helper function used to build conditions by composing QueryExpression objects.
| string | $part | Name of the query part to append the new part to |
| string|null|array|\Cake\Database\ExpressionInterface|callable | $append | Expression or builder function to append. |
| string | $conjunction | type of conjunction to be used to operate part |
| array | $types | associative array of type names used to bind values to query |
_addAssociationsToTypeMap(\Cake\ORM\Table $table, \Cake\Database\TypeMap $typeMap, array $associations) : void
Used to recursively add contained association column types to the query.
| \Cake\ORM\Table | $table | The table instance to pluck associations from. |
| \Cake\Database\TypeMap | $typeMap | The typemap to check for columns in. This typemap is indirectly mutated via Cake\ORM\Query::addDefaultTypes() |
| array | $associations | The nested tree of associations to walk. |
_transformQuery() : void
Applies some defaults to the query object before it is executed.
Specifically add the FROM clause, adds default table fields if none are
specified and applies the joins required to eager load associations defined
using contain
It also sets the default types for the columns in the select clause