Select
class Select extends Query implements SelectInterface (View source)
Query builder for SELECT statements.
Traits
Provides an implementation of ConditionInterface.
Properties
| protected Connection | $connection | The connection object on which to run this query. |
from Query |
| protected string | $connectionTarget | The target of the connection object. |
from Query |
| protected string | $connectionKey | The key of the connection object. |
from Query |
| protected array | $queryOptions | The query options to pass on to the connection object. |
from Query |
| protected string | $uniqueIdentifier | A unique identifier for this query object. |
from Query |
| protected int | $nextPlaceholder | The placeholder counter. |
from Query |
| protected array | $comments | An array of comments that can be prepended to a query. |
from Query |
| protected Condition | $condition | The condition object for this query. |
from QueryConditionTrait |
| protected array | $fields | The fields to SELECT. |
|
| protected array | $expressions | The expressions to SELECT as virtual fields. |
|
| protected array | $tables | The tables against which to JOIN. |
|
| protected array | $order | The fields by which to order this query. |
|
| protected array | $group | The fields by which to group. |
|
| protected Condition | $having | The conditional object for the HAVING clause. |
|
| protected bool | $distinct | Whether or not this query should be DISTINCT. |
|
| protected array | $range | The range limiters for this query. |
|
| protected array | $union | An array whose elements specify a query to UNION, and the UNION type. The 'type' key may be '', 'ALL', or 'DISTINCT' to represent a 'UNION', 'UNION ALL', or 'UNION DISTINCT' statement, respectively. |
|
| protected bool | $prepared | Indicates if preExecute() has already been called. |
|
| protected bool | $forUpdate | The FOR UPDATE status. |
Methods
Constructs a Select object.
Implements the magic __clone function.
Runs the query against the database.
Implements PHP magic __toString method to convert the query to a string.
Gets a complete list of all values to insert into the prepared statement.
Compiles the saved conditions for later retrieval.
Check whether a condition has been previously compiled.
Adds a tag to a query.
Determines if a given query has a given tag.
Determines if a given query has all specified tags.
Determines if a given query has any specified tag.
Adds additional metadata to the query.
Retrieves a given piece of metadata.
Helper function to build most common HAVING conditional clauses.
Gets a list of all conditions in the HAVING clause.
Gets a list of all values to insert into the HAVING clause.
Adds an arbitrary HAVING clause to the query.
Enhance this object by wrapping it in an extender object.
Sets a condition in the HAVING clause that the specified field be NULL.
Sets a condition in the HAVING clause that the specified field be NOT NULL.
Sets a HAVING condition that the specified subquery returns values.
Sets a HAVING condition that the specified subquery returns no values.
Add FOR UPDATE to the query.
Returns a reference to the fields array for this query.
Returns a reference to the expressions array for this query.
Returns a reference to the order by array for this query.
Returns a reference to the group-by array for this query.
Returns a reference to the tables array for this query.
Returns a reference to the union queries for this query. This include queries for UNION, UNION ALL, and UNION DISTINCT.
Escapes characters that work as wildcard characters in a LIKE pattern.
Escapes a field name string.
Compiles and returns an associative array of the arguments for this prepared statement.
Indicates if preExecute() has already been called on that object.
Sets this query to be DISTINCT.
Adds a field to the list to be SELECTed.
Add multiple fields from the same table to be SELECTed.
Adds an expression to the list of "fields" to be SELECTed.
Default Join against another table in the database.
Inner Join against another table in the database.
Left Outer Join against another table in the database.
Join against another table in the database.
Orders the result set by a given field.
Orders the result set by a random value.
Restricts a query to a given range in the result set.
Groups the result set by the specified field.
Get the equivalent COUNT query of this query as a new query object.
Prepares a count query from the current query object.
Details
__construct(Connection $connection, string|SelectInterface $table, string $alias = NULL, array $options = [])
Constructs a Select object.
in
Query at line 86
__sleep()
Implements the magic __sleep function to disconnect from the database.
in
Query at line 95
__wakeup()
Implements the magic __wakeup function to reconnect to the database.
__clone()
Implements the magic __clone function.
StatementInterface|null
execute()
Runs the query against the database.
string
__toString()
Implements PHP magic __toString method to convert the query to a string.
The toString operation is how we compile a query object to a prepared statement.
in
Query at line 128
uniqueIdentifier()
Returns a unique identifier for this object.
in
Query at line 138
The
nextPlaceholder()
Gets the next placeholder value for this query object.
in
Query at line 158
$this
comment($comment)
Adds a comment to the query.
By adding a comment to a query, you can more easily find it in your query log or the list of active queries on an SQL server. This allows for easier debugging and allows you to more easily find where a query with a performance problem is being generated.
The comment string will be sanitized to remove * / and other characters that may terminate the string early so as to avoid SQL injection attacks.
in
Query at line 178
array
getComments()
Returns a reference to the comments array for the query.
Because this method returns by reference, alter hooks may edit the comments array directly to make their changes. If just adding comments, however, the use of comment() is preferred.
Note that this method must be called by reference as well:
in
Query at line 188
Connection
getConnection()
Gets the database connection to be used for the query.
condition($field, $value = NULL, $operator = '=')
{@inheritdoc}
isNull($field)
{@inheritdoc}
isNotNull($field)
{@inheritdoc}
exists(SelectInterface $select)
{@inheritdoc}
notExists(SelectInterface $select)
{@inheritdoc}
alwaysFalse()
{@inheritdoc}
conditions()
{@inheritdoc}
An
arguments()
Gets a complete list of all values to insert into the prepared statement.
where($snippet, $args = [])
{@inheritdoc}
compile(Connection $connection, PlaceholderInterface $queryPlaceholder)
Compiles the saved conditions for later retrieval.
This method does not return anything, but simply prepares data to be retrieved via __toString() and arguments().
true
compiled()
Check whether a condition has been previously compiled.
conditionGroupFactory($conjunction = 'AND')
{@inheritdoc}
andConditionGroup()
{@inheritdoc}
orConditionGroup()
{@inheritdoc}
$this
addTag($tag)
Adds a tag to a query.
Tags are strings that identify a query. A query may have any number of tags. Tags are used to mark a query so that alter hooks may decide if they wish to take action. Tags should be all lower-case and contain only letters, numbers, and underscore, and start with a letter. That is, they should follow the same rules as PHP identifiers in general.
true
hasTag($tag)
Determines if a given query has a given tag.
true
hasAllTags()
Determines if a given query has all specified tags.
Each tag to check should be supplied as a separate argument.
true
hasAnyTag()
Determines if a given query has any specified tag.
Each tag to check should be supplied as a separate argument.
$this
addMetaData($key, $object)
Adds additional metadata to the query.
Often, a query may need to provide additional contextual data to alter hooks. Alter hooks may then use that information to decide if and how to take action.
The
getMetaData($key)
Retrieves a given piece of metadata.
ConditionInterface
havingCondition($field, $value = NULL, $operator = NULL)
Helper function to build most common HAVING conditional clauses.
This method can take a variable number of parameters. If called with two parameters, they are taken as $field and $value with $operator having a value of IN if $value is an array and = otherwise.
array
havingConditions()
Gets a list of all conditions in the HAVING clause.
This method returns by reference. That allows alter hooks to access the data structure directly and manipulate it before it gets compiled.
array
havingArguments()
Gets a list of all values to insert into the HAVING clause.
$this
having($snippet, $args = [])
Adds an arbitrary HAVING clause to the query.
havingCompile(Connection $connection)
Compiles the HAVING clause for later retrieval.
ExtendableInterface
extend($extender_name)
Enhance this object by wrapping it in an extender object.
$this
havingIsNull($field)
Sets a condition in the HAVING clause that the specified field be NULL.
$this
havingIsNotNull($field)
Sets a condition in the HAVING clause that the specified field be NOT NULL.
$this
havingExists(SelectInterface $select)
Sets a HAVING condition that the specified subquery returns values.
$this
havingNotExists(SelectInterface $select)
Sets a HAVING condition that the specified subquery returns no values.
ConditionInterface
forUpdate($set = TRUE)
Add FOR UPDATE to the query.
FOR UPDATE prevents the rows retrieved by the SELECT statement from being modified or deleted by other transactions until the current transaction ends. Other transactions that attempt UPDATE, DELETE, or SELECT FOR UPDATE of these rows will be blocked until the current transaction ends.
A
getFields()
Returns a reference to the fields array for this query.
Because this method returns by reference, alter hooks may edit the fields array directly to make their changes. If just adding fields, however, the use of addField() is preferred.
Note that this method must be called by reference as well:
A
getExpressions()
Returns a reference to the expressions array for this query.
Because this method returns by reference, alter hooks may edit the expressions array directly to make their changes. If just adding expressions, however, the use of addExpression() is preferred.
Note that this method must be called by reference as well:
A
getOrderBy()
Returns a reference to the order by array for this query.
Because this method returns by reference, alter hooks may edit the order-by array directly to make their changes. If just adding additional ordering fields, however, the use of orderBy() is preferred.
Note that this method must be called by reference as well:
A
getGroupBy()
Returns a reference to the group-by array for this query.
Because this method returns by reference, alter hooks may edit the group-by array directly to make their changes. If just adding additional grouping fields, however, the use of groupBy() is preferred.
Note that this method must be called by reference as well:
A
getTables()
Returns a reference to the tables array for this query.
Because this method returns by reference, alter hooks may edit the tables array directly to make their changes. If just adding tables, however, the use of the join() methods is preferred.
Note that this method must be called by reference as well:
A
getUnion()
Returns a reference to the union queries for this query. This include queries for UNION, UNION ALL, and UNION DISTINCT.
Because this method returns by reference, alter hooks may edit the tables array directly to make their changes. If just adding union queries, however, the use of the union() method is preferred.
Note that this method must be called by reference as well:
string
escapeLike($string)
Escapes characters that work as wildcard characters in a LIKE pattern.
The
escapeField(string $string)
Escapes a field name string.
Force all field names to be strictly alphanumeric-plus-underscore. For some database drivers, it may also wrap the field name in database-specific escape characters.
An
getArguments(PlaceholderInterface $queryPlaceholder = NULL)
Compiles and returns an associative array of the arguments for this prepared statement.
true
isPrepared()
Indicates if preExecute() has already been called on that object.
true
preExecute(SelectInterface $query = NULL)
Generic preparation and validation for a SELECT query.
$this
distinct($distinct = TRUE)
Sets this query to be DISTINCT.
The
addField($table_alias, $field, $alias = NULL)
Adds a field to the list to be SELECTed.
$this
fields($table_alias, array $fields = [])
Add multiple fields from the same table to be SELECTed.
This method does not return the aliases set for the passed fields. In the majority of cases that is not a problem, as the alias will be the field name. However, if you do need to know the alias you can call getFields() and examine the result to determine what alias was created. Alternatively, simply use addField() for the few fields you care about and this method for the rest.
The
addExpression($expression, $alias = NULL, $arguments = [])
Adds an expression to the list of "fields" to be SELECTed.
An expression can be any arbitrary string that is valid SQL. That includes various functions, which may in some cases be database-dependent. This method makes no effort to correct for database-specific functions.
The
join($table, $alias = NULL, $condition = NULL, $arguments = [])
Default Join against another table in the database.
This method is a convenience method for innerJoin().
The
innerJoin($table, $alias = NULL, $condition = NULL, $arguments = [])
Inner Join against another table in the database.
The
leftJoin($table, $alias = NULL, $condition = NULL, $arguments = [])
Left Outer Join against another table in the database.
The
addJoin($type, $table, $alias = NULL, $condition = NULL, $arguments = [])
Join against another table in the database.
This method does the "hard" work of queuing up a table to be joined against. In some cases, that may include dipping into the Schema API to find the necessary fields on which to join.
$this
orderBy($field, $direction = 'ASC')
Orders the result set by a given field.
If called multiple times, the query will order by each specified field in the order this method is called.
If the query uses DISTINCT or GROUP BY conditions, fields or expressions that are used for the order must be selected to be compatible with some databases like PostgreSQL. The PostgreSQL driver can handle simple cases automatically but it is suggested to explicitly specify them. Additionally, when ordering on an alias, the alias must be added before orderBy() is called.
$this
orderRandom()
Orders the result set by a random value.
This may be stacked with other orderBy() calls. If so, the query will order by each specified field, including this one, in the order called. Although this method may be called multiple times on the same query, doing so is not particularly useful.
Note: The method used by most drivers may not scale to very large result sets. If you need to work with extremely large data sets, you may create your own database driver by subclassing off of an existing driver and implementing your own randomization mechanism. See
http://jan.kneschke.de/projects/mysql/order-by-rand/
for an example of such an alternate sorting mechanism.
$this
range($start = NULL, $length = NULL)
Restricts a query to a given range in the result set.
If this method is called with no parameters, will remove any range directives that have been set.
$this
union(SelectInterface $query, $type = '')
Add another Select query to UNION to this one.
Union queries consist of two or more queries whose results are effectively concatenated together. Queries will be UNIONed in the order they are specified, with this object's query coming first. Duplicate columns will be discarded. All forms of UNION are supported, using the second '$type' argument.
Note: All queries UNIONed together must have the same field structure, in the same order. It is up to the caller to ensure that they match properly. If they do not, an SQL syntax error will result.
$this
groupBy($field)
Groups the result set by the specified field.
SelectInterface
countQuery()
Get the equivalent COUNT query of this query as a new query object.
protected Select
prepareCountQuery()
Prepares a count query from the current query object.