Class SelectQuery
Extends the Cake\Database\Query\SelectQuery 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.
Constants
-
int
APPEND ¶0
Indicates that the operation should append to the list
-
string
JOIN_TYPE_INNER ¶'INNER'
-
string
JOIN_TYPE_LEFT ¶'LEFT'
-
string
JOIN_TYPE_RIGHT ¶'RIGHT'
-
bool
OVERWRITE ¶true
Indicates that the operation should overwrite the list
-
int
PREPEND ¶1
Indicates that the operation should prepend to the list
-
string
TYPE_DELETE ¶'delete'
-
string
TYPE_INSERT ¶'insert'
-
string
TYPE_SELECT ¶'select'
-
string
TYPE_UPDATE ¶'update'
Property Summary
-
$_autoFields protected
bool|null
Tracks whether the original query should include fields from the top level table.
-
$_beforeFindFired protected
bool
True if the beforeFind event has already been triggered for this query
-
$_cache protected
Cake\Datasource\QueryCacher|null
A query cacher instance if this query has caching enabled.
-
$_connection protected
Cake\Database\Connection
Connection instance to be used to execute this query.
-
$_counter protected
Closure|null
A callback used to calculate the total amount of records this query will match when not using
limit
-
$_dirty protected
bool
Indicates whether internal state of this query was changed, this is used to discard internal cached objects such as the transformed query or the reference to the executed statement.
-
$_eagerLoaded protected
bool
Whether the query is standalone or the product of an eager load operation.
-
$_eagerLoader protected
Cake\ORM\EagerLoader|null
Instance of a class responsible for storing association containments and for eager loading them when this query is executed
-
$_formatters protected
arrayClosure>
List of formatter classes or callbacks that will post-process the results when fetched
-
$_functionsBuilder protected
Cake\Database\FunctionsBuilder|null
Instance of functions builder object used for generating arbitrary SQL functions.
-
$_hasFields protected
bool|null
Whether the user select any fields before being executed, this is used to determined if any fields should be automatically be selected.
-
$_hydrate protected
bool
Whether to hydrate results into entity objects
-
$_mapReduce protected
array
List of map-reduce routines that should be applied over the query result
-
$_options protected
array
Holds any custom options passed using applyOptions that could not be processed by any method in this class.
-
$_parts protected
array<string, mixed>
List of SQL parts that will be used to build this query.
-
$_repository protected
Cake\ORM\Table
Instance of a repository/table object this query is bound to.
-
$_resultDecorators protected
listClosure>
A list of callbacks to be called to alter each row from resulting statement upon retrieval. Each one of the callback function will receive the row array as first argument.
-
$_results protected
iterable|null
A ResultSet.
-
$_resultsCount protected
int|null
The COUNT(*) for the query.
-
$_selectTypeMap protected
Cake\Database\TypeMap|null
The Type map for fields in the select clause
-
$_statement protected
Cake\Database\StatementInterface|null
-
$_type protected
string
Type of this query.
-
$_typeMap protected
Cake\Database\TypeMap|null
-
$_valueBinder protected
Cake\Database\ValueBinder|null
The object responsible for generating query placeholders and temporarily store values associated to each of those.
-
$aliasingEnabled protected
bool
Whether aliases are generated for fields.
-
$bufferedResults protected
bool
Boolean for tracking whether buffered results are enabled.
-
$connectionRole protected
string
Connection role ('read' or 'write')
-
$resultSetFactory protected
Cake\ORM\ResultSetFactoryCake\Datasource\EntityInterface|array>
Resultset factory
-
$typeCastEnabled protected
bool
Tracking flag to disable casting
Method Summary
-
__clone() public
Handles clearing iterator and cloning all expressions and value binders.
-
__construct() public
Constructor
-
__debugInfo() public
Returns an array that can be used to describe the internal state of this object.
-
__toString() public
Returns string representation of this query (complete SQL statement).
-
_addAssociationsToTypeMap() protected
Used to recursively add contained association column types to the query.
-
_addDefaultFields() protected
Inspects if there are any set fields for selecting, otherwise adds all the fields for the default table.
-
_addDefaultSelectTypes() protected
Sets the default types for converting the fields in the select clause
-
_conjugate() protected
Helper function used to build conditions by composing QueryExpression objects.
-
_decorateResults() protected
Decorates the results iterator with MapReduce routines and formatters
-
_dirty() protected
Marks a query as dirty, removing any preprocessed information from in memory caching such as previous results
-
_execute() protected
Executes this query and returns an iterable containing the results.
-
_expressionsVisitor() protected
Query parts traversal method used by traverseExpressions()
-
_makeJoin() protected
Returns an array that can be passed to the join method describing a single join clause
-
_performCount() protected
Performs and returns the COUNT(*) for the query.
-
_transformQuery() protected
Applies some defaults to the query object before it is executed.
-
addDefaultTypes() public
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.
-
aliasField() public
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.
-
aliasFields() public
Runs
aliasField()
for each field in the provided list and returns the result under a single array. -
all() public
Fetch the results for this query.
-
andHaving() public
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. -
andWhere() public @method
Connects any previously defined set of conditions to the provided list using the AND operator. {@see \Cake\Database\Query::andWhere()}
-
applyOptions() public
Populates or adds parts to current query clauses using an array. This is handy for passing all query clauses at once.
-
bind() public
Associates a query placeholder to a value and a type.
-
cache() public
Enable result caching for this query.
-
clause() public
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, union and intersect.
-
cleanCopy() public
Creates a copy of this current query, triggers beforeFind and resets some state.
-
clearContain() public
Clears the contained associations from the current query.
-
clearResult() public
Clears the internal result cache and the internal count value from the current query object.
-
comment() public
A string or expression that will be appended to the generated query as a comment
-
contain() public
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.
-
count() public
Returns the total amount of results for the query.
-
counter() public
Registers a callback 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 thecount
method. -
decorateResults() public
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.
-
disableAutoAliasing() public
Disable auto adding table's alias to the fields of SELECT clause.
-
disableAutoFields() public
Disables automatically appending fields.
-
disableBufferedResults() public
Disables buffered results.
-
disableHydration() public
Disable hydrating entities.
-
disableResultsCasting() public
Disables result casting.
-
distinct() public
Adds a
DISTINCT
clause to the query to remove duplicates from the result set. This clause can only be used for select statements. -
eagerLoaded() public
Sets the query instance to be an eager loaded query. If no argument is passed, the current configured query
_eagerLoaded
value is returned. -
enableAutoFields() public
Sets whether the ORM should automatically append fields.
-
enableBufferedResults() public
Enables buffered results.
-
enableHydration() public
Toggle hydrating entities.
-
enableResultsCasting() public
Enables result casting.
-
epilog() public
A string or expression that will be appended to the generated query
-
execute() public
Compiles the SQL representation of this query and executes it using the configured connection object. Returns the resulting statement object.
-
expr() public
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.
-
find() public
Apply custom finds to against an existing query object.
-
first() public
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.
-
firstOrFail() public
Get the first result from the executing query or raise an exception.
-
formatResults() public
Registers a new formatter callback function that is to be executed when trying to fetch the results from the database.
-
from() public
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.
-
func() public
Returns an instance of a functions builder object that can be used for generating arbitrary SQL functions.
-
getConnection() public
Gets the connection instance to be used for executing and transforming this query.
-
getConnectionRole() public
Returns the connection role ('read' or 'write')
-
getContain() public
-
getDefaultTypes() public
Gets default types of current type map.
-
getEagerLoader() public
Returns the currently configured instance.
-
getIterator() public
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.
-
getMapReducers() public
Returns the list of previously registered map reduce routines.
-
getOptions() public
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.
-
getRepository() public
Returns the default repository object that will be used by this query, that is, the table that will appear in the from clause.
-
getResultDecorators() public
Get result decorators.
-
getResultFormatters() public
Returns the list of previously registered format routines.
-
getSelectTypeMap() public
Gets the TypeMap class where the types for each of the fields in the select clause are stored.
-
getTypeMap() public
Returns the existing type map.
-
getValueBinder() public
Returns the currently used ValueBinder instance.
-
group() public deprecated
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.
-
groupBy() public
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.
-
having() public
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 methodwhere()
does. Please refer to its documentation for an insight on how to using each parameter. -
identifier() public
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.
-
innerJoin() public
Adds a single
INNER JOIN
clause to the query. -
innerJoinWith() public
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.
-
intersect() public
Adds a complete query to be used in conjunction with an INTERSECT 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.
-
intersectAll() public
Adds a complete query to be used in conjunction with the INTERSECT 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.
-
isAutoFieldsEnabled() public
Gets whether the ORM should automatically append fields.
-
isBufferedResultsEnabled() public
Returns whether buffered results are enabled/disabled.
-
isEagerLoaded() public
Returns the current configured query
_eagerLoaded
value -
isHydrationEnabled() public
Returns the current hydration mode.
-
isResultsCastingEnabled() public
Returns whether result casting is enabled/disabled.
-
join() public
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.
-
jsonSerialize() public
Executes the query and converts the result set into JSON.
-
leftJoin() public
Adds a single
LEFT JOIN
clause to the query. -
leftJoinWith() public
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.
-
limit() public
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.
-
mapReduce() public
Register a new MapReduce routine to be executed on top of the database results
-
matching() public
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.
-
modifier() public
Adds a single or multiple
SELECT
modifiers to be used in theSELECT
. -
newExpr() public
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.
-
notMatching() public
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.
-
offset() public
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.
-
order() public deprecated
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.
-
orderAsc() public deprecated
Add an ORDER BY clause with an ASC direction.
-
orderBy() public
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.
-
orderByAsc() public
Add an ORDER BY clause with an ASC direction.
-
orderByDesc() public
Add an ORDER BY clause with a DESC direction.
-
orderDesc() public deprecated
Add an ORDER BY clause with a DESC direction.
-
page() public
Set the page of results you want.
-
removeJoin() public
Remove a join if it has been defined.
-
resultSetFactory() public
Get resultset factory.
-
rightJoin() public
Adds a single
RIGHT JOIN
clause to the query. -
rowCountAndClose() public
Executes the SQL of this query and immediately closes the statement before returning the row count of records changed.
-
select() public
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. -
selectAllExcept() public
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.
-
selectAlso() public
Behaves the exact same as
select()
except adds the field to the list of fields selected and does not disable auto-selecting fields for Associations. -
setConnection() public
Sets the connection instance to be used for executing and transforming this query.
-
setConnectionRole() public
Sets the connection role.
-
setDefaultTypes() public
Overwrite the default type mappings for fields in the implementing object.
-
setEagerLoader() public
Sets the instance of the eager loader class to use for loading associations and storing containments.
-
setRepository() public
Set the default Table object that will be used by this query and form the
FROM
clause. -
setResult() public
Set the result set for a query.
-
setSelectTypeMap() public
Sets the TypeMap class where the types for each of the fields in the select clause are stored.
-
setTypeMap() public
Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.
-
setValueBinder() public
Overwrite the current value binder
-
sql() public
Returns the SQL representation of this object.
-
toArray() public
Returns an array representation of the results after executing the query.
-
traverse() public
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.
-
traverseExpressions() public
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.
-
traverseParts() public
Will iterate over the provided parts.
-
triggerBeforeFind() public
Trigger the beforeFind event on the query's repository object.
-
type() public
Returns the type of this query (select, insert, update, delete)
-
union() public
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.
-
unionAll() public
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.
-
useReadRole() public
Sets the connection role to read.
-
useWriteRole() public
Sets the connection role to write.
-
where() public
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.
-
whereInList() public
Adds an IN condition or set of conditions to be used in the WHERE clause for this query.
-
whereNotInList() public
Adds a NOT IN condition or set of conditions to be used in the WHERE clause for this query.
-
whereNotInListOrNull() public
Adds a NOT IN condition or set of conditions to be used in the WHERE clause for this query. This also allows the field to be null with a IS NULL condition since the null value would cause the NOT IN condition to always fail.
-
whereNotNull() public
Convenience method that adds a NOT NULL condition to the query
-
whereNull() public
Convenience method that adds a IS NULL condition to the query
-
window() public
Adds a named window expression.
-
with() public
Adds a new common table expression (CTE) to the query.
Method Detail
__clone() ¶ public
__clone(): void
Handles clearing iterator and cloning all expressions and value binders.
Handles cloning eager loaders.
Returns
void
__construct() ¶ public
__construct(Cake\ORM\Table $table)
Constructor
Parameters
-
Cake\ORM\Table
$table The table this query is starting on
__debugInfo() ¶ public
__debugInfo(): array<string, mixed>
Returns an array that can be used to describe the internal state of this object.
Returns
array<string, mixed>
__toString() ¶ public
__toString(): string
Returns string representation of this query (complete SQL statement).
Returns
string
_addAssociationsToTypeMap() ¶ protected
_addAssociationsToTypeMap(Cake\ORM\Table $table, Cake\Database\TypeMap $typeMap, array<string, array> $associations): void
Used to recursively add contained association column types to the query.
Parameters
-
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 {@link \Cake\ORM\Query\SelectQuery::addDefaultTypes()}
-
array<string, array>
$associations The nested tree of associations to walk.
Returns
void
_addDefaultFields() ¶ protected
_addDefaultFields(): void
Inspects if there are any set fields for selecting, otherwise adds all the fields for the default table.
Returns
void
_addDefaultSelectTypes() ¶ protected
_addDefaultSelectTypes(): void
Sets the default types for converting the fields in the select clause
Returns
void
_conjugate() ¶ protected
_conjugate(string $part, Cake\Database\ExpressionInterfaceClosure|array|string|null $append, string $conjunction, array<string, string> $types): void
Helper function used to build conditions by composing QueryExpression objects.
Parameters
-
string
$part Name of the query part to append the new part to
-
Cake\Database\ExpressionInterfaceClosure|array|string|null
$append Expression or builder function to append. to append.
-
string
$conjunction type of conjunction to be used to operate part
-
array<string, string>
$types Associative array of type names used to bind values to query
Returns
void
_decorateResults() ¶ protected
_decorateResults(iterable $result): Cake\Datasource\ResultSetInterfaceCake\Datasource\EntityInterface|mixed>
Decorates the results iterator with MapReduce routines and formatters
Parameters
-
iterable
$result Original results
Returns
Cake\Datasource\ResultSetInterfaceCake\Datasource\EntityInterface|mixed>
_dirty() ¶ protected
_dirty(): void
Marks a query as dirty, removing any preprocessed information from in memory caching such as previous results
Returns
void
_execute() ¶ protected
_execute(): iterable
Executes this query and returns an iterable containing the results.
Returns
iterable
_expressionsVisitor() ¶ protected
_expressionsVisitor(mixed $expression, Closure $callback): void
Query parts traversal method used by traverseExpressions()
Parameters
-
mixed
$expression Query expression or array of expressions.
-
Closure
$callback The callback to be executed for each ExpressionInterface found inside this query.
Returns
void
_makeJoin() ¶ protected
_makeJoin(array<string, mixed>|string $table, Cake\Database\ExpressionInterfaceClosure|array|string $conditions, string $type): array
Returns an array that can be passed to the join method describing a single join clause
Parameters
-
array<string, mixed>|string
$table The table to join with
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions The conditions to use for joining.
-
string
$type the join type to use
Returns
array
_performCount() ¶ protected
_performCount(): int
Performs and returns the COUNT(*) for the query.
Returns
int
_transformQuery() ¶ protected
_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
Returns
void
See Also
addDefaultTypes() ¶ public
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.
Parameters
-
Cake\ORM\Table
$table The table to pull types from
Returns
$this
aliasField() ¶ public
aliasField(string $field, string|null $alias = null): array<string, string>
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.
Parameters
-
string
$field The field to alias
-
string|null
$alias optional the alias used to prefix the field
Returns
array<string, string>
aliasFields() ¶ public
aliasFields(array $fields, string|null $defaultAlias = null): array<string, string>
Runs aliasField()
for each field in the provided list and returns
the result under a single array.
Parameters
-
array
$fields The fields to alias
-
string|null
$defaultAlias optional The default alias
Returns
array<string, string>
all() ¶ public
all(): Cake\Datasource\ResultSetInterface<mixed>
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.
Returns
Cake\Datasource\ResultSetInterface<mixed>
andHaving() ¶ public
andHaving(Cake\Database\ExpressionInterfaceClosure|array|string $conditions, array<string, string> $types = []): $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.
Parameters
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions The AND conditions for HAVING.
-
array<string, string>
$types optional Associative array of type names used to bind values to query
Returns
$this
See Also
andWhere() ¶ public @method
andWhere(Cake\Database\ExpressionInterfaceClosure|array|string $conditions, array $types = []): $this
Connects any previously defined set of conditions to the provided list using the AND operator. {@see \Cake\Database\Query::andWhere()}
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.
Examples:
$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)
Parameters
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions -
array
$types optional
Returns
$this
applyOptions() ¶ public
applyOptions(array<string, mixed> $options): $this
Populates or adds parts to current query clauses using an array. This is handy for passing all query clauses at once.
The method accepts the following query clause related options:
- fields: Maps to the select method
- conditions: Maps to the where method
- limit: Maps to the limit method
- order: Maps to the order method
- offset: Maps to the offset method
- group: Maps to the group method
- having: Maps to the having method
- contain: Maps to the contain options for eager loading
- join: Maps to the join method
- page: Maps to the page method
All other options will not affect the query, but will be stored
as custom options that can be read via getOptions()
. Furthermore
they are automatically passed to Model.beforeFind
.
Example:
$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)
Custom options can be read via getOptions()
:
$query->applyOptions([
'fields' => ['id', 'name'],
'custom' => 'value',
]);
Here $options
will hold ['custom' => 'value']
(the fields
option will be applied to the query instead of being stored, as
it's a query clause related option):
$options = $query->getOptions();
Parameters
-
array<string, mixed>
$options The options to be applied
Returns
$this
See Also
bind() ¶ public
bind(string|int $param, mixed $value, string|int|null $type = null): $this
Associates a query placeholder to a value and a type.
$query->bind(':id', 1, 'integer');
Parameters
-
string|int
$param placeholder to be replaced with quoted version of $value
-
mixed
$value The value to be bound
-
string|int|null
$type optional the mapped type name, used for casting when sending to database
Returns
$this
cache() ¶ public
cache(Closure|string|false $key, Psr\SimpleCache\CacheInterface|string $config = 'default'): $this
Enable result caching for this query.
If a query has caching enabled, it will do the following when executed:
- Check the cache for $key. If there are results no SQL will be executed. Instead the cached results will be returned.
- When the cached data is stale/missing the result set will be cached as the query is executed.
Usage
// 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);
Parameters
-
Closure|string|false
$key Either the cache key or a function to generate the cache key. When using a function, this query instance will be supplied as an argument.
-
Psr\SimpleCache\CacheInterface|string
$config optional Either the name of the cache config to use, or a cache engine instance.
Returns
$this
clause() ¶ public
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, union and intersect.
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.
- update: string The name of the table to update
- set: QueryExpression
- insert: array, will return an array containing the table + columns.
- values: ValuesExpression
- select: array, will return empty array when no fields are set
- distinct: boolean
- from: array of tables
- join: array
- set: array
- where: QueryExpression, returns null when not set
- group: array
- having: QueryExpression, returns null when not set
- order: OrderByExpression, returns null when not set
- limit: integer or QueryExpression, null when not set
- offset: integer or QueryExpression, null when not set
- union: array
- intersect: array
Parameters
-
string
$name name of the clause to be returned
Returns
mixed
Throws
InvalidArgumentException
When the named clause does not exist.
cleanCopy() ¶ public
cleanCopy(): static
Creates a copy of this current query, triggers beforeFind and resets some state.
The following state will be cleared:
- autoFields
- limit
- offset
- map/reduce functions
- result formatters
- order
- containments
This method creates query clones that are useful when working with subqueries.
Returns
static
clearContain() ¶ public
clearContain(): $this
Clears the contained associations from the current query.
Returns
$this
clearResult() ¶ public
clearResult(): $this
Clears the internal result cache and the internal count value from the current query object.
Returns
$this
comment() ¶ public
comment(string|null $expression = null): $this
A string or expression that will be appended to the generated query as a comment
Examples:
$query->select('id')->where(['author_id' => 1])->comment('Filter for admin user');
Comment content is raw SQL and not suitable for use with user supplied data.
Parameters
-
string|null
$expression optional The comment to be added
Returns
$this
contain() ¶ public
contain(array|string $associations, Closure|bool $override = false): $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.
Example:
// 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.
Example:
// 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:
Example:
$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 callback instead of an options array.
Example:
// 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 an empty first argument and $override
is set to true, the
previous list will be emptied.
Parameters
-
array|string
$associations List of table aliases to be queried.
-
Closure|bool
$override optional 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.
Returns
$this
count() ¶ public
count(): int
Returns the total amount of results for the query.
Returns the COUNT(*) for the query. If the query has not been modified, and the count has already been performed the cached value is returned
Returns
int
counter() ¶ public
counter(Closure|null $counter): $this
Registers a callback 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
Parameters
-
Closure|null
$counter The counter value
Returns
$this
decorateResults() ¶ public
decorateResults(Closure|null $callback, bool $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 be 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.
Example
$query->decorateResults(function ($row) {
$row['order_total'] = $row['subtotal'] + ($row['subtotal'] * $row['tax']);
return $row;
});
Parameters
-
Closure|null
$callback The callback to invoke when results are fetched.
-
bool
$overwrite optional Whether this should append or replace all existing decorators.
Returns
$this
disableAutoAliasing() ¶ public
disableAutoAliasing(): $this
Disable auto adding table's alias to the fields of SELECT clause.
Returns
$this
disableAutoFields() ¶ public
disableAutoFields(): $this
Disables automatically appending fields.
Returns
$this
disableBufferedResults() ¶ public
disableBufferedResults(): $this
Disables buffered results.
Disabling buffering will consume less memory as fetched results are not remembered for future iterations.
Returns
$this
disableHydration() ¶ public
disableHydration(): $this
Disable hydrating entities.
Disabling hydration will cause array results to be returned for the query instead of entities.
Returns
$this
disableResultsCasting() ¶ public
disableResultsCasting(): $this
Disables result casting.
When disabled, the fields will be returned as received from the database driver (which in most environments means they are being returned as strings), which can improve performance with larger datasets.
Returns
$this
distinct() ¶ public
distinct(Cake\Database\ExpressionInterface|array|string|bool $on = [], bool $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.
Examples:
// 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);
Parameters
-
Cake\Database\ExpressionInterface|array|string|bool
$on optional Enable/disable distinct class or list of fields to be filtered on
-
bool
$overwrite optional whether to reset fields with passed list or not
Returns
$this
eagerLoaded() ¶ public
eagerLoaded(bool $value): $this
Sets the query instance to be an eager loaded query. If no argument is
passed, the current configured query _eagerLoaded
value is returned.
Parameters
-
bool
$value Whether to eager load.
Returns
$this
enableAutoFields() ¶ public
enableAutoFields(bool $value = true): $this
Sets whether the ORM should automatically append fields.
By default calling select() will disable auto-fields. You can re-enable auto-fields with this method.
Parameters
-
bool
$value optional Set true to enable, false to disable.
Returns
$this
enableBufferedResults() ¶ public
enableBufferedResults(): $this
Enables 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.
Returns
$this
enableHydration() ¶ public
enableHydration(bool $enable = true): $this
Toggle hydrating entities.
If set to false array results will be returned for the query.
Parameters
-
bool
$enable optional Use a boolean to set the hydration mode.
Returns
$this
enableResultsCasting() ¶ public
enableResultsCasting(): $this
Enables result casting.
When enabled, the fields in the results returned by this Query will be cast to their corresponding PHP data type.
Returns
$this
epilog() ¶ public
epilog(Cake\Database\ExpressionInterface|string|null $expression = null): $this
A string or expression that will be appended to the generated query
Examples:
$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.
Parameters
-
Cake\Database\ExpressionInterface|string|null
$expression optional The expression to be appended
Returns
$this
execute() ¶ public
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.
Returns
Cake\Database\StatementInterface
expr() ¶ public
expr(Cake\Database\ExpressionInterface|array|string|null $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->expr(); // Returns an empty expression object
$expression = $query->expr('Table.column = Table2.column'); // Return a raw SQL expression
Parameters
-
Cake\Database\ExpressionInterface|array|string|null
$rawExpression optional A string, array or anything you want wrapped in an expression object
Returns
Cake\Database\Expression\QueryExpression
find() ¶ public
find(string $finder, mixed ...$args): static<TSubject>
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.
Parameters
-
string
$finder The finder method to use.
-
mixed
...$args Arguments that match up to finder-specific parameters
Returns
static<TSubject>
first() ¶ public
first(): mixed
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.
Example:
$singleUser = $query->select(['id', 'username'])->first();
Returns
mixed
firstOrFail() ¶ public
firstOrFail(): mixed
Get the first result from the executing query or raise an exception.
Returns
mixed
Throws
Cake\Datasource\Exception\RecordNotFoundException
When there is no first record.
formatResults() ¶ public
formatResults(Closure|null $formatter = null, int|bool $mode = self::APPEND): $this
Registers a new formatter callback function that is to be executed when trying to fetch the results from the database.
If the second argument is set to true, it will erase previous formatters and replace them with the passed first argument.
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.
Formatting callbacks will receive two arguments, the first one being an object
implementing \Cake\Collection\CollectionInterface
, that can be traversed and
modified at will. The second one being the query instance on which the formatter
callback is being applied.
Usually the query instance received by the formatter callback is the same query instance on which the callback was attached to, except for in a joined association, in that case the callback will be invoked on the association source side query, and it will receive that query instance instead of the one on which the callback was originally attached to - see the examples below!
Examples:
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;
});
});
Add a new column to the results with respect to the query's hydration configuration:
$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;
});
});
Retaining access to the association target query instance of joined associations, by inheriting the contain callback's query argument:
// 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;
});
});
Parameters
-
Closure|null
$formatter optional The formatting function
-
int|bool
$mode optional Whether to overwrite, append or prepend the formatter.
Returns
$this
Throws
InvalidArgumentException
from() ¶ public
from(array|string $tables = [], bool $overwrite = false): $this
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.
Examples:
$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
Parameters
-
array|string
$tables optional 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.
-
bool
$overwrite optional whether to reset tables with passed list or not
Returns
$this
func() ¶ public
func(): Cake\Database\FunctionsBuilder
Returns an instance of a functions builder object that can be used for generating arbitrary SQL functions.
Example:
$query->func()->count('*');
$query->func()->dateDiff(['2012-01-05', '2012-01-02'])
Returns
Cake\Database\FunctionsBuilder
getConnection() ¶ public
getConnection(): Cake\Database\Connection
Gets the connection instance to be used for executing and transforming this query.
Returns
Cake\Database\Connection
getConnectionRole() ¶ public
getConnectionRole(): string
Returns the connection role ('read' or 'write')
Returns
string
getDefaultTypes() ¶ public
getDefaultTypes(): array<int|string, string>
Gets default types of current type map.
Returns
array<int|string, string>
getEagerLoader() ¶ public
getEagerLoader(): Cake\ORM\EagerLoader
Returns the currently configured instance.
Returns
Cake\ORM\EagerLoader
getIterator() ¶ public
getIterator(): Cake\Datasource\ResultSetInterfaceCake\Datasource\EntityInterface|array>
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.
Returns
Cake\Datasource\ResultSetInterfaceCake\Datasource\EntityInterface|array>
getMapReducers() ¶ public
getMapReducers(): array
Returns the list of previously registered map reduce routines.
Returns
array
getOptions() ¶ public
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.
Example:
$query->applyOptions(['doABarrelRoll' => true, 'fields' => ['id', 'name']);
$query->getOptions(); // Returns ['doABarrelRoll' => true]
Returns
array
See Also
applyOptions()
getRepository() ¶ public
getRepository(): Cake\ORM\Table
Returns the default repository object that will be used by this query, that is, the table that will appear in the from clause.
Returns
Cake\ORM\Table
getResultFormatters() ¶ public
getResultFormatters(): arrayClosure>
Returns the list of previously registered format routines.
Returns
arrayClosure>
getSelectTypeMap() ¶ public
getSelectTypeMap(): Cake\Database\TypeMap
Gets the TypeMap class where the types for each of the fields in the select clause are stored.
Returns
Cake\Database\TypeMap
getTypeMap() ¶ public
getTypeMap(): Cake\Database\TypeMap
Returns the existing type map.
Returns
Cake\Database\TypeMap
getValueBinder() ¶ public
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.
Returns
Cake\Database\ValueBinder
group() ¶ public
group(Cake\Database\ExpressionInterface|array|string $fields, bool $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.
Examples:
// Produces GROUP BY id, title
$query->groupBy(['id', 'title']);
// Produces GROUP BY title
$query->groupBy('title');
Group fields are not suitable for use with user supplied data as they are not sanitized by the query builder.
Parameters
-
Cake\Database\ExpressionInterface|array|string
$fields fields to be added to the list
-
bool
$overwrite optional whether to reset fields with passed list or not
Returns
$this
groupBy() ¶ public
groupBy(Cake\Database\ExpressionInterface|array|string $fields, bool $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.
Examples:
// Produces GROUP BY id, title
$query->groupBy(['id', 'title']);
// Produces GROUP BY title
$query->groupBy('title');
Group fields are not suitable for use with user supplied data as they are not sanitized by the query builder.
Parameters
-
Cake\Database\ExpressionInterface|array|string
$fields fields to be added to the list
-
bool
$overwrite optional whether to reset fields with passed list or not
Returns
$this
having() ¶ public
having(Cake\Database\ExpressionInterfaceClosure|array|string|null $conditions = null, array<string, string> $types = [], bool $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.
Parameters
-
Cake\Database\ExpressionInterfaceClosure|array|string|null
$conditions optional The having conditions.
-
array<string, string>
$types optional Associative array of type names used to bind values to query
-
bool
$overwrite optional whether to reset conditions with passed list or not
Returns
$this
See Also
identifier() ¶ public
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.
Example
$query->newExpr()->lte('count', $query->identifier('total'));
Parameters
-
string
$identifier The identifier for an expression
Returns
Cake\Database\ExpressionInterface
innerJoin() ¶ public
innerJoin(array<string, mixed>|string $table, Cake\Database\ExpressionInterfaceClosure|array|string $conditions = [], array<string, string> $types = []): $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 method's description for further details.
Parameters
-
array<string, mixed>|string
$table The table to join with
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions optional The conditions to use for joining.
-
array<string, string>
$types optional a list of types associated to the conditions used for converting values to the corresponding database representation.
Returns
$this
innerJoinWith() ¶ public
innerJoinWith(string $assoc, Closure|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.
Example:
// 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.id
This function works the same as matching()
with the difference that it
will select no fields from the association.
Parameters
-
string
$assoc The association to join with
-
Closure|null
$builder optional a function that will receive a pre-made query object that can be used to add custom conditions or selecting some fields
Returns
$this
See Also
intersect() ¶ public
intersect(Cake\Database\Query|string $query, bool $overwrite = false): $this
Adds a complete query to be used in conjunction with an INTERSECT 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 INTERSECT operator will remove duplicate rows, if you wish to include every row for all queries, use intersectAll().
Examples
$intersect = (new SelectQuery($conn))->select(['id', 'title'])->from(['a' => 'articles']);
$query->select(['id', 'name'])->from(['d' => 'things'])->intersect($intersect);
Will produce:
SELECT id, name FROM things d INTERSECT SELECT id, title FROM articles a
Parameters
-
Cake\Database\Query|string
$query full SQL query to be used in INTERSECT operator
-
bool
$overwrite optional whether to reset the list of queries to be operated or not
Returns
$this
intersectAll() ¶ public
intersectAll(Cake\Database\Query|string $query, bool $overwrite = false): $this
Adds a complete query to be used in conjunction with the INTERSECT 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 INTERSECT, INTERSECT ALL will not remove duplicate rows.
$intersect = (new SelectQuery($conn))->select(['id', 'title'])->from(['a' => 'articles']);
$query->select(['id', 'name'])->from(['d' => 'things'])->intersectAll($intersect);
Will produce:
SELECT id, name FROM things d INTERSECT ALL SELECT id, title FROM articles a
Parameters
-
Cake\Database\Query|string
$query full SQL query to be used in INTERSECT operator
-
bool
$overwrite optional whether to reset the list of queries to be operated or not
Returns
$this
isAutoFieldsEnabled() ¶ public
isAutoFieldsEnabled(): bool|null
Gets whether the ORM should automatically append fields.
By default calling select() will disable auto-fields. You can re-enable auto-fields with enableAutoFields().
Returns
bool|null
isBufferedResultsEnabled() ¶ public
isBufferedResultsEnabled(): bool
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.
Returns
bool
isEagerLoaded() ¶ public
isEagerLoaded(): bool
Returns the current configured query _eagerLoaded
value
Returns
bool
isHydrationEnabled() ¶ public
isHydrationEnabled(): bool
Returns the current hydration mode.
Returns
bool
isResultsCastingEnabled() ¶ public
isResultsCastingEnabled(): bool
Returns whether result casting is enabled/disabled.
When enabled, the fields in the results returned by this Query will be casted to their corresponding PHP data type.
When disabled, the fields will be returned as received from the database driver (which in most environments means they are being returned as strings), which can improve performance with larger datasets.
Returns
bool
join() ¶ public
join(array<string, mixed>|string $tables, array<string, string> $types = [], bool $overwrite = false): $this
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_id
You 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"
Using conditions and types
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'])
Overwriting joins
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
Parameters
-
array<string, mixed>|string
$tables list of tables to be joined in the query
-
array<string, string>
$types optional Associative array of type names used to bind values to query
-
bool
$overwrite optional whether to reset joins with passed list or not
Returns
$this
See Also
jsonSerialize() ¶ public
jsonSerialize(): Cake\Datasource\ResultSetInterfaceCake\Datasource\EntityInterface|mixed>
Executes the query and converts the result set into JSON.
Part of JsonSerializable interface.
Returns
Cake\Datasource\ResultSetInterfaceCake\Datasource\EntityInterface|mixed>
leftJoin() ¶ public
leftJoin(array<string, mixed>|string $table, Cake\Database\ExpressionInterfaceClosure|array|string $conditions = [], array $types = []): $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.
Parameters
-
array<string, mixed>|string
$table The table to join with
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions optional The conditions to use for joining.
-
array
$types optional a list of types associated to the conditions used for converting values to the corresponding database representation.
Returns
$this
leftJoinWith() ¶ public
leftJoinWith(string $assoc, Closure|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.
Example:
// Get the count of articles per user
$usersQuery
->select(['total_articles' => $query->func()->count('Articles.id')])
->leftJoinWith('Articles')
->groupBy(['Users.id'])
->enableAutoFields();
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]);
})
->groupBy(['Users.id'])
->enableAutoFields();
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.id
It is possible to left join deep associations by using dot notation
Example:
// 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']);
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.
Parameters
-
string
$assoc The association to join with
-
Closure|null
$builder optional a function that will receive a pre-made query object that can be used to add custom conditions or selecting some fields
Returns
$this
limit() ¶ public
limit(int|null $limit): $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.
Examples
$query->limit(10) // generates LIMIT 10
$query->limit($query->newExpr()->add(['1 + 1'])); // LIMIT (1 + 1)
Parameters
-
int|null
$limit number of records to be returned
Returns
$this
mapReduce() ¶ public
mapReduce(Closure|null $mapper = null, Closure|null $reducer = null, bool $overwrite = false): $this
Register a new MapReduce routine to be executed on top of the database results
The MapReduce routing will only be run when the query is executed and the first result is attempted to be fetched.
If the third argument is set to true, it will erase previous map reducers and replace it with the arguments passed.
Parameters
-
Closure|null
$mapper optional The mapper function
-
Closure|null
$reducer optional The reducing function
-
bool
$overwrite optional Set to true to overwrite existing map + reduce functions.
Returns
$this
See Also
matching() ¶ public
matching(string $assoc, Closure|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.
Example:
// 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:
Example:
// 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.
Example:
// 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.
Parameters
-
string
$assoc The association to filter by
-
Closure|null
$builder optional a function that will receive a pre-made query object that can be used to add custom conditions or selecting some fields
Returns
$this
modifier() ¶ public
modifier(Cake\Database\ExpressionInterface|array|string $modifiers, bool $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.
Example:
// 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
Parameters
-
Cake\Database\ExpressionInterface|array|string
$modifiers modifiers to be applied to the query
-
bool
$overwrite optional whether to reset order with field list or not
Returns
$this
newExpr() ¶ public
newExpr(Cake\Database\ExpressionInterface|array|string|null $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->expr(); // Returns an empty expression object
$expression = $query->expr('Table.column = Table2.column'); // Return a raw SQL expression
Parameters
-
Cake\Database\ExpressionInterface|array|string|null
$rawExpression optional A string, array or anything you want wrapped in an expression object
Returns
Cake\Database\Expression\QueryExpression
notMatching() ¶ public
notMatching(string $assoc, Closure|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.
Example:
// 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:
Example:
// 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.
Example:
// 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.
Parameters
-
string
$assoc The association to filter by
-
Closure|null
$builder optional a function that will receive a pre-made query object that can be used to add custom conditions or selecting some fields
Returns
$this
offset() ¶ public
offset(int|null $offset): $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.
Examples
$query->offset(10) // generates OFFSET 10
$query->offset($query->newExpr()->add(['1 + 1'])); // OFFSET (1 + 1)
Parameters
-
int|null
$offset number of records to be skipped
Returns
$this
order() ¶ public
order(Closure|array|string $fields, bool $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.
Examples:
$query->orderBy(['title' => 'DESC', 'author_id' => 'ASC']);
Produces:
ORDER BY title DESC, author_id ASC
$query
->orderBy(['title' => $query->newExpr('DESC NULLS FIRST')])
->orderBy('author_id');
Will generate:
ORDER BY title DESC NULLS FIRST, author_id
$expression = $query->newExpr()->add(['id % 2 = 0']);
$query->orderBy($expression)->orderBy(['title' => 'ASC']);
Will become:
ORDER BY (id %2 = 0), title ASC
If you need to set complex expressions as order conditions, you
should use orderByAsc()
or orderByDesc()
.
Parameters
-
Closure|array|string
$fields fields to be added to the list
-
bool
$overwrite optional whether to reset order with field list or not
Returns
$this
orderAsc() ¶ public
orderAsc(Cake\Database\ExpressionInterfaceClosure|string $field, bool $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.
Parameters
-
Cake\Database\ExpressionInterfaceClosure|string
$field The field to order on.
-
bool
$overwrite optional Whether to reset the order clauses.
Returns
$this
orderBy() ¶ public
orderBy(Closure|array|string $fields, bool $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.
Examples:
$query->orderBy(['title' => 'DESC', 'author_id' => 'ASC']);
Produces:
ORDER BY title DESC, author_id ASC
$query
->orderBy(['title' => $query->newExpr('DESC NULLS FIRST')])
->orderBy('author_id');
Will generate:
ORDER BY title DESC NULLS FIRST, author_id
$expression = $query->newExpr()->add(['id % 2 = 0']);
$query->orderBy($expression)->orderBy(['title' => 'ASC']);
Will become:
ORDER BY (id %2 = 0), title ASC
If you need to set complex expressions as order conditions, you
should use orderByAsc()
or orderByDesc()
.
Parameters
-
Closure|array|string
$fields fields to be added to the list
-
bool
$overwrite optional whether to reset order with field list or not
Returns
$this
orderByAsc() ¶ public
orderByAsc(Cake\Database\ExpressionInterfaceClosure|string $field, bool $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.
Parameters
-
Cake\Database\ExpressionInterfaceClosure|string
$field The field to order on.
-
bool
$overwrite optional Whether to reset the order clauses.
Returns
$this
orderByDesc() ¶ public
orderByDesc(Cake\Database\ExpressionInterfaceClosure|string $field, bool $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.
Parameters
-
Cake\Database\ExpressionInterfaceClosure|string
$field The field to order on.
-
bool
$overwrite optional Whether to reset the order clauses.
Returns
$this
orderDesc() ¶ public
orderDesc(Cake\Database\ExpressionInterfaceClosure|string $field, bool $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.
Parameters
-
Cake\Database\ExpressionInterfaceClosure|string
$field The field to order on.
-
bool
$overwrite optional Whether to reset the order clauses.
Returns
$this
page() ¶ public
page(int $num, int|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.
Parameters
-
int
$num The page number you want.
-
int|null
$limit optional The number of rows you want in the page. If null the current limit clause will be used.
Returns
$this
Throws
InvalidArgumentException
If page number < 1.
removeJoin() ¶ public
removeJoin(string $name): $this
Remove a join if it has been defined.
Useful when you are redefining joins or want to re-order the join clauses.
Parameters
-
string
$name The alias/name of the join to remove.
Returns
$this
resultSetFactory() ¶ public
resultSetFactory(): Cake\ORM\ResultSetFactory
Get resultset factory.
Returns
Cake\ORM\ResultSetFactory
rightJoin() ¶ public
rightJoin(array<string, mixed>|string $table, Cake\Database\ExpressionInterfaceClosure|array|string $conditions = [], array $types = []): $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.
Parameters
-
array<string, mixed>|string
$table The table to join with
-
Cake\Database\ExpressionInterfaceClosure|array|string
$conditions optional The conditions to use for joining.
-
array
$types optional a list of types associated to the conditions used for converting values to the corresponding database representation.
Returns
$this
rowCountAndClose() ¶ public
rowCountAndClose(): int
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.
Example
$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.
Returns
int
select() ¶ public
select(Cake\Database\ExpressionInterfaceCake\ORM\TableCake\ORM\AssociationClosure|array|string|float|int $fields = [], bool $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 callback 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.
Examples:
$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.
Parameters
-
Cake\Database\ExpressionInterfaceCake\ORM\TableCake\ORM\AssociationClosure|array|string|float|int
$fields optional Fields to be added to the list.
-
bool
$overwrite optional whether to reset fields with passed list or not
Returns
$this
selectAllExcept() ¶ public
selectAllExcept(Cake\ORM\TableCake\ORM\Association $table, list<string> $excludedFields, bool $overwrite = false): $this
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.
Parameters
-
Cake\ORM\TableCake\ORM\Association
$table The table to use to get an array of columns
-
list<string>
$excludedFields The un-aliased column names you do not want selected from $table
-
bool
$overwrite optional Whether to reset/remove previous selected fields
Returns
$this
selectAlso() ¶ public
selectAlso(Cake\Database\ExpressionInterfaceCake\ORM\TableCake\ORM\AssociationClosure|array|string|float|int $fields): $this
Behaves the exact same as select()
except adds the field to the list of fields selected and
does not disable auto-selecting fields for Associations.
Use this instead of calling select()
then enableAutoFields()
to re-enable auto-fields.
Parameters
-
Cake\Database\ExpressionInterfaceCake\ORM\TableCake\ORM\AssociationClosure|array|string|float|int
$fields Fields to be added to the list.
Returns
$this
setConnection() ¶ public
setConnection(Cake\Database\Connection $connection): $this
Sets the connection instance to be used for executing and transforming this query.
Parameters
-
Cake\Database\Connection
$connection Connection instance
Returns
$this
setConnectionRole() ¶ public
setConnectionRole(string $role): $this
Sets the connection role.
Parameters
-
string
$role Connection role ('read' or 'write')
Returns
$this
setDefaultTypes() ¶ public
setDefaultTypes(array<int|string, string> $types): $this
Overwrite the default type mappings for fields in the implementing object.
This method is useful if you need to set type mappings that are shared across multiple functions/expressions in a query.
To add a default without overwriting existing ones
use getTypeMap()->addDefaults()
Parameters
-
array<int|string, string>
$types The array of types to set.
Returns
$this
See Also
setEagerLoader() ¶ public
setEagerLoader(Cake\ORM\EagerLoader $instance): $this
Sets the instance of the eager loader class to use for loading associations and storing containments.
Parameters
-
Cake\ORM\EagerLoader
$instance The eager loader to use.
Returns
$this
setRepository() ¶ public
setRepository(Cake\Datasource\RepositoryInterface $repository): $this
Set the default Table object that will be used by this query
and form the FROM
clause.
Parameters
-
Cake\Datasource\RepositoryInterface
$repository The default table object to use
Returns
$this
setResult() ¶ public
setResult(iterable $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.
Parameters
-
iterable
$results The results this query should return.
Returns
$this
setSelectTypeMap() ¶ public
setSelectTypeMap(Cake\Database\TypeMap|array $typeMap): $this
Sets the TypeMap class where the types for each of the fields in the select clause are stored.
Parameters
-
Cake\Database\TypeMap|array
$typeMap Creates a TypeMap if array, otherwise sets the given TypeMap.
Returns
$this
setTypeMap() ¶ public
setTypeMap(Cake\Database\TypeMap|array $typeMap): $this
Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.
Parameters
-
Cake\Database\TypeMap|array
$typeMap Creates a TypeMap if array, otherwise sets the given TypeMap
Returns
$this
setValueBinder() ¶ public
setValueBinder(Cake\Database\ValueBinder|null $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.
Parameters
-
Cake\Database\ValueBinder|null
$binder The binder or null to disable binding.
Returns
$this
sql() ¶ public
sql(Cake\Database\ValueBinder|null $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.
Parameters
-
Cake\Database\ValueBinder|null
$binder optional
Returns
string
toArray() ¶ public
toArray(): array
Returns an array representation of the results after executing the query.
Returns
array
traverse() ¶ public
traverse(Closure $callback): $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.
Example
$query->select(['title'])->from('articles')->traverse(function ($value, $clause) {
if ($clause === 'select') {
var_dump($value);
}
});
Parameters
-
Closure
$callback Callback to be executed for each part
Returns
$this
traverseExpressions() ¶ public
traverseExpressions(Closure $callback): $this
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.
Parameters
-
Closure
$callback the function to be executed for each ExpressionInterface found inside this query.
Returns
$this
traverseParts() ¶ public
traverseParts(Closure $visitor, list<string> $parts): $this
Will iterate over the provided parts.
Traversing functions can aggregate results using variables in the closure or instance variables. This method can be used to traverse a subset of query parts in order to render a SQL 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.
Example
$query->select(['title'])->from('articles')->traverse(function ($value, $clause) {
if ($clause === 'select') {
var_dump($value);
}
}, ['select', 'from']);
Parameters
-
Closure
$visitor Callback executed for each part
-
list<string>
$parts The list of query parts to traverse
Returns
$this
triggerBeforeFind() ¶ public
triggerBeforeFind(): void
Trigger the beforeFind event on the query's repository object.
Will not trigger more than once, and only for select queries.
Returns
void
type() ¶ public
type(): string
Returns the type of this query (select, insert, update, delete)
Returns
string
union() ¶ public
union(Cake\Database\Query|string $query, bool $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().
Examples
$union = (new SelectQuery($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
Parameters
-
Cake\Database\Query|string
$query full SQL query to be used in UNION operator
-
bool
$overwrite optional whether to reset the list of queries to be operated or not
Returns
$this
unionAll() ¶ public
unionAll(Cake\Database\Query|string $query, bool $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 SelectQuery($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
Parameters
-
Cake\Database\Query|string
$query full SQL query to be used in UNION operator
-
bool
$overwrite optional whether to reset the list of queries to be operated or not
Returns
$this
where() ¶ public
where(Closure|array|string|null $conditions = null, array<string, string> $types = [], bool $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.
Conditions using operators:
$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.
Nesting conditions with conjunctions:
$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]])
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.
Using expressions objects:
$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.
Adding conditions in multiple steps:
You can use callback 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);
});
- The previous example produces:
WHERE title != 'Hello World' AND (id = 1 OR (id > 2 AND id < 10))
Conditions as strings:
$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. 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.
Parameters
-
Closure|array|string|null
$conditions optional The conditions to filter on.
-
array<string, string>
$types optional Associative array of type names used to bind values to query
-
bool
$overwrite optional whether to reset conditions with passed list or not
Returns
$this
whereInList() ¶ public
whereInList(string $field, array $values, array<string, mixed> $options = []): $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.
Parameters
-
string
$field Field
-
array
$values Array of values
-
array<string, mixed>
$options optional Options
Returns
$this
whereNotInList() ¶ public
whereNotInList(string $field, array $values, array<string, mixed> $options = []): $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.
Parameters
-
string
$field Field
-
array
$values Array of values
-
array<string, mixed>
$options optional Options
Returns
$this
whereNotInListOrNull() ¶ public
whereNotInListOrNull(string $field, array $values, array<string, mixed> $options = []): $this
Adds a NOT IN condition or set of conditions to be used in the WHERE clause for this query. This also allows the field to be null with a IS NULL condition since the null value would cause the NOT IN condition to always fail.
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.
Parameters
-
string
$field Field
-
array
$values Array of values
-
array<string, mixed>
$options optional Options
Returns
$this
whereNotNull() ¶ public
whereNotNull(Cake\Database\ExpressionInterface|array|string $fields): $this
Convenience method that adds a NOT NULL condition to the query
Parameters
-
Cake\Database\ExpressionInterface|array|string
$fields A single field or expressions or a list of them that should be not null.
Returns
$this
whereNull() ¶ public
whereNull(Cake\Database\ExpressionInterface|array|string $fields): $this
Convenience method that adds a IS NULL condition to the query
Parameters
-
Cake\Database\ExpressionInterface|array|string
$fields A single field or expressions or a list of them that should be null.
Returns
$this
window() ¶ public
window(string $name, Cake\Database\Expression\WindowExpressionClosure $window, bool $overwrite = false): $this
Adds a named window expression.
You are responsible for adding windows in the order your database requires.
Parameters
-
string
$name Window name
-
Cake\Database\Expression\WindowExpressionClosure
$window Window expression
-
bool
$overwrite optional Clear all previous query window expressions
Returns
$this
with() ¶ public
with(Cake\Database\Expression\CommonTableExpressionClosure $cte, bool $overwrite = false): $this
Adds a new common table expression (CTE) to the query.
Examples:
Common table expressions can either be passed as preconstructed expression objects:
$cte = new \Cake\Database\Expression\CommonTableExpression(
'cte',
$connection
->selectQuery('*')
->from('articles')
);
$query->with($cte);
or returned from a closure, which will receive a new common table expression object as the first argument, and a new blank select query object as the second argument:
$query->with(function (
\Cake\Database\Expression\CommonTableExpression $cte,
\Cake\Database\Query $query
) {
$cteQuery = $query
->select('*')
->from('articles');
return $cte
->name('cte')
->query($cteQuery);
});
Parameters
-
Cake\Database\Expression\CommonTableExpressionClosure
$cte The CTE to add.
-
bool
$overwrite optional Whether to reset the list of CTEs.
Returns
$this
Property Detail
$_autoFields ¶ protected
Tracks whether the original query should include fields from the top level table.
Type
bool|null
$_beforeFindFired ¶ protected
True if the beforeFind event has already been triggered for this query
Type
bool
$_cache ¶ protected
A query cacher instance if this query has caching enabled.
Type
Cake\Datasource\QueryCacher|null
$_connection ¶ protected
Connection instance to be used to execute this query.
Type
Cake\Database\Connection
$_counter ¶ protected
A callback used to calculate the total amount of
records this query will match when not using limit
Type
Closure|null
$_dirty ¶ protected
Indicates whether internal state of this query was changed, this is used to discard internal cached objects such as the transformed query or the reference to the executed statement.
Type
bool
$_eagerLoaded ¶ protected
Whether the query is standalone or the product of an eager load operation.
Type
bool
$_eagerLoader ¶ protected
Instance of a class responsible for storing association containments and for eager loading them when this query is executed
Type
Cake\ORM\EagerLoader|null
$_formatters ¶ protected
List of formatter classes or callbacks that will post-process the results when fetched
Type
arrayClosure>
$_functionsBuilder ¶ protected
Instance of functions builder object used for generating arbitrary SQL functions.
Type
Cake\Database\FunctionsBuilder|null
$_hasFields ¶ protected
Whether the user select any fields before being executed, this is used to determined if any fields should be automatically be selected.
Type
bool|null
$_mapReduce ¶ protected
List of map-reduce routines that should be applied over the query result
Type
array
$_options ¶ protected
Holds any custom options passed using applyOptions that could not be processed by any method in this class.
Type
array
$_parts ¶ protected
List of SQL parts that will be used to build this query.
Type
array<string, mixed>
$_repository ¶ protected
Instance of a repository/table object this query is bound to.
Type
Cake\ORM\Table
$_resultDecorators ¶ protected
A list of callbacks to be called to alter each row from resulting statement upon retrieval. Each one of the callback function will receive the row array as first argument.
Type
listClosure>
$_results ¶ protected
A ResultSet.
When set, SelectQuery execution will be bypassed.
Type
iterable|null
$_resultsCount ¶ protected
The COUNT(*) for the query.
When set, count query execution will be bypassed.
Type
int|null
$_selectTypeMap ¶ protected
The Type map for fields in the select clause
Type
Cake\Database\TypeMap|null
$_valueBinder ¶ protected
The object responsible for generating query placeholders and temporarily store values associated to each of those.
Type
Cake\Database\ValueBinder|null
$resultSetFactory ¶ protected
Resultset factory
Type
Cake\ORM\ResultSetFactoryCake\Datasource\EntityInterface|array>