Drupal 8  8.0.2
SelectInterface Interface Reference
Inheritance diagram for SelectInterface:

Public Member Functions

getFields ()
 
getExpressions ()
 
getOrderBy ()
 
getGroupBy ()
 
getTables ()
 
getUnion ()
 
 escapeLike ($string)
 
 escapeField ($string)
 
 getArguments (PlaceholderInterface $queryPlaceholder=NULL)
 
 distinct ($distinct=TRUE)
 
 addField ($table_alias, $field, $alias=NULL)
 
 fields ($table_alias, array $fields=array())
 
 addExpression ($expression, $alias=NULL, $arguments=array())
 
 join ($table, $alias=NULL, $condition=NULL, $arguments=array())
 
 innerJoin ($table, $alias=NULL, $condition=NULL, $arguments=array())
 
 leftJoin ($table, $alias=NULL, $condition=NULL, $arguments=array())
 
 rightJoin ($table, $alias=NULL, $condition=NULL, $arguments=array())
 
 addJoin ($type, $table, $alias=NULL, $condition=NULL, $arguments=array())
 
 orderBy ($field, $direction= 'ASC')
 
 orderRandom ()
 
 range ($start=NULL, $length=NULL)
 
 union (SelectInterface $query, $type= '')
 
 groupBy ($field)
 
 countQuery ()
 
 isPrepared ()
 
 preExecute (SelectInterface $query=NULL)
 
 execute ()
 
 havingCondition ($field, $value=NULL, $operator=NULL)
 
havingConditions ()
 
 havingArguments ()
 
 having ($snippet, $args=array())
 
 havingCompile (Connection $connection)
 
 havingIsNull ($field)
 
 havingIsNotNull ($field)
 
 havingExists (SelectInterface $select)
 
 havingNotExists (SelectInterface $select)
 
 __clone ()
 
 forUpdate ($set=TRUE)
 
 __toString ()
 
- Public Member Functions inherited from ConditionInterface
 condition ($field, $value=NULL, $operator= '=')
 
 where ($snippet, $args=array())
 
 isNull ($field)
 
 isNotNull ($field)
 
 exists (SelectInterface $select)
 
 notExists (SelectInterface $select)
 
conditions ()
 
 arguments ()
 
 compile (Connection $connection, PlaceholderInterface $queryPlaceholder)
 
 compiled ()
 
 conditionGroupFactory ($conjunction= 'AND')
 
 andConditionGroup ()
 
 orConditionGroup ()
 
- Public Member Functions inherited from AlterableInterface
 addTag ($tag)
 
 hasTag ($tag)
 
 hasAllTags ()
 
 hasAnyTag ()
 
 addMetaData ($key, $object)
 
 getMetaData ($key)
 
- Public Member Functions inherited from ExtendableInterface
 extend ($extender_name)
 
- Public Member Functions inherited from PlaceholderInterface
 uniqueIdentifier ()
 
 nextPlaceholder ()
 

Detailed Description

Interface definition for a Select Query object.

Member Function Documentation

__clone ( )

Clone magic method.

Select queries have dependent objects that must be deep-cloned. The connection object itself, however, should not be cloned as that would duplicate the connection itself.

Implemented in Select, and SelectExtender.

__toString ( )

Returns a string representation of how the query will be executed in SQL.

Returns
string The Select Query object expressed as a string.

Implemented in Select, and SelectExtender.

addExpression (   $expression,
  $alias = NULL,
  $arguments = array() 
)

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.

Parameters
$expressionThe expression string. May contain placeholders.
$aliasThe alias for this expression. If not specified, one will be generated automatically in the form "expression_#". The alias will be checked for uniqueness, so the requested alias may not be the alias that is assigned in all cases.
$argumentsAny placeholder arguments needed for this expression.
Returns
The unique alias that was assigned for this expression.

Implemented in Select, SelectExtender, and Select.

addField (   $table_alias,
  $field,
  $alias = NULL 
)

Adds a field to the list to be SELECTed.

Parameters
$table_aliasThe name of the table from which the field comes, as an alias. Generally you will want to use the return value of join() here to ensure that it is valid.
$fieldThe name of the field.
$aliasThe alias for this field. If not specified, one will be generated automatically based on the $table_alias and $field. The alias will be checked for uniqueness, so the requested alias may not be the alias that is assigned in all cases.
Returns
The unique alias that was assigned for this field.

Implemented in Select, and SelectExtender.

addJoin (   $type,
  $table,
  $alias = NULL,
  $condition = NULL,
  $arguments = array() 
)

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.

Parameters
$typeThe type of join. Typically one one of INNER, LEFT OUTER, and RIGHT OUTER.
$tableThe table against which to join. May be a string or another SelectQuery object. If a query object is passed, it will be used as a subselect. Unless the table name starts with the database / schema name and a dot it will be prefixed.
$aliasThe alias for the table. In most cases this should be the first letter of the table, or the first letter of each "word" in the table. If omitted, one will be dynamically generated.
$conditionThe condition on which to join this table. If the join requires values, this clause should use a named placeholder and the value or values to insert should be passed in the 4th parameter. For the first table joined on a query, this value is ignored as the first table is taken as the base table. The token alias can be used in this string to be replaced with the actual alias. This is useful when $alias is modified by the database system, for example, when joining the same table more than once.
$argumentsAn array of arguments to replace into the $condition of this join.
Returns
The unique alias that was assigned for this table.

Implemented in Select, and SelectExtender.

countQuery ( )

Get the equivalent COUNT query of this query as a new query object.

Returns
A new SelectQuery object with no fields or expressions besides COUNT(*).

Implemented in Select, SearchQuery, and SelectExtender.

distinct (   $distinct = TRUE)

Sets this query to be DISTINCT.

Parameters
$distinctTRUE to flag this query DISTINCT, FALSE to disable it.
Returns
The called object.

Implemented in Select, and SelectExtender.

escapeField (   $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.

Parameters
string$stringAn unsanitized field name.
Returns
The sanitized field name string.

Implemented in Select, and SelectExtender.

Referenced by Condition\translateCondition().

Here is the caller graph for this function:

escapeLike (   $string)

Escapes characters that work as wildcard characters in a LIKE pattern.

Parameters
$stringThe string to escape.
Returns
string The escaped string.
See Also
::escapeLike()

Implemented in Select, and SelectExtender.

Referenced by Condition\translateCondition().

Here is the caller graph for this function:

execute ( )

Runs the query against the database.

Returns
|null A prepared statement, or NULL if the query is not valid.

Implemented in SearchQuery, Select, SelectExtender, Select, and PagerSelectExtender.

Referenced by MenuTreeStorage\safeExecuteSelect().

Here is the caller graph for this function:

fields (   $table_alias,
array  $fields = array() 
)

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.

Parameters
$table_aliasThe name of the table from which the field comes, as an alias. Generally you will want to use the return value of join() here to ensure that it is valid.
$fieldsAn indexed array of fields present in the specified table that should be included in this query. If not specified, $table_alias.* will be generated without any aliases.
Returns
The called object.

Implemented in Select, and SelectExtender.

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.

Parameters
$setIF TRUE, FOR UPDATE will be added to the query, if FALSE then it won't.
Returns
The called object.

Implemented in SelectExtender, Select, and Select.

getArguments ( PlaceholderInterface  $queryPlaceholder = NULL)

Compiles and returns an associative array of the arguments for this prepared statement.

Parameters
$queryPlaceholderWhen collecting the arguments of a subquery, the main placeholder object should be passed as this parameter.
Returns
An associative array of all placeholder arguments for this query.

Implemented in Select, and SelectExtender.

Referenced by Cache\keyFromQuery().

Here is the caller graph for this function:

& 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:

$fields =& $query->getExpressions();
Returns
A reference to the expression array structure.

Implemented in Select, and SelectExtender.

& 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:

$fields =& $query->getFields();
Returns
A reference to the fields array structure.

Implemented in Select, and SelectExtender.

& 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:

$fields =& $query->getGroupBy();
Returns
A reference to the group-by array structure.

Implemented in Select, and SelectExtender.

& 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:

$fields =& $query->getOrderBy();
Returns
A reference to the expression array structure.

Implemented in Select, and SelectExtender.

& 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:

$fields =& $query->getTables();
Returns
A reference to the tables array structure.

Implemented in Select, and SelectExtender.

Referenced by Condition\compile().

Here is the caller graph for this function:

& 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:

$fields =& $query->getUnion();
Returns
A reference to the union query array structure.

Implemented in Select, and SelectExtender.

groupBy (   $field)

Groups the result set by the specified field.

Parameters
$fieldThe field on which to group. This should be the field as aliased.
Returns
The called object.

Implemented in Select, and SelectExtender.

having (   $snippet,
  $args = array() 
)

Adds an arbitrary HAVING clause to the query.

Parameters
$snippetA portion of a HAVING clause as a prepared statement. It must use named placeholders, not ? placeholders.
$args(optional) An associative array of arguments.
Returns
$this

Implemented in Select, and SelectExtender.

havingArguments ( )

Gets a list of all values to insert into the HAVING clause.

Returns
array An associative array of placeholders and values.

Implemented in Select, and SelectExtender.

havingCompile ( Connection  $connection)

Compiles the HAVING clause for later retrieval.

Parameters
$connectionThe database connection for which to compile the clause.

Implemented in Select, and SelectExtender.

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.

Parameters
$fieldThe name of the field to check. If you would like to add a more complex condition involving operators or functions, use having().
$valueThe value to test the field against. In most cases, this is a scalar. For more complex options, it is an array. The meaning of each element in the array is dependent on the $operator.
$operatorThe comparison operator, such as =, <, or >=. It also accepts more complex options such as IN, LIKE, or BETWEEN. Defaults to IN if $value is an array = otherwise.
Returns
The called object.

Implemented in Select, and SelectExtender.

& 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.

Returns
array An array of conditions.
See Also
::conditions()

Implemented in Select, and SelectExtender.

havingExists ( SelectInterface  $select)

Sets a HAVING condition that the specified subquery returns values.

Parameters
\Drupal\Core\Database\Query\SelectInterface$selectThe subquery that must contain results.
Returns
$this

Implemented in Select, and SelectExtender.

havingIsNotNull (   $field)

Sets a condition in the HAVING clause that the specified field be NOT NULL.

Parameters
$fieldThe name of the field to check.
Returns
$this

Implemented in Select, and SelectExtender.

havingIsNull (   $field)

Sets a condition in the HAVING clause that the specified field be NULL.

Parameters
$fieldThe name of the field to check.
Returns
$this

Implemented in Select, and SelectExtender.

havingNotExists ( SelectInterface  $select)

Sets a HAVING condition that the specified subquery returns no values.

Parameters
\Drupal\Core\Database\Query\SelectInterface$selectThe subquery that must contain results.
Returns
$this

Implemented in Select, and SelectExtender.

innerJoin (   $table,
  $alias = NULL,
  $condition = NULL,
  $arguments = array() 
)

Inner Join against another table in the database.

Parameters
$tableThe table against which to join. May be a string or another SelectQuery object. If a query object is passed, it will be used as a subselect. Unless the table name starts with the database / schema name and a dot it will be prefixed.
$aliasThe alias for the table. In most cases this should be the first letter of the table, or the first letter of each "word" in the table.
$conditionThe condition on which to join this table. If the join requires values, this clause should use a named placeholder and the value or values to insert should be passed in the 4th parameter. For the first table joined on a query, this value is ignored as the first table is taken as the base table. The token alias can be used in this string to be replaced with the actual alias. This is useful when $alias is modified by the database system, for example, when joining the same table more than once.
$argumentsAn array of arguments to replace into the $condition of this join.
Returns
The unique alias that was assigned for this table.

Implemented in Select, and SelectExtender.

isPrepared ( )

Indicates if preExecute() has already been called on that object.

Returns
TRUE is this query has already been prepared, FALSE otherwise.

Implemented in Select, and SelectExtender.

join (   $table,
  $alias = NULL,
  $condition = NULL,
  $arguments = array() 
)

Default Join against another table in the database.

This method is a convenience method for innerJoin().

Parameters
$tableThe table against which to join. May be a string or another SelectQuery object. If a query object is passed, it will be used as a subselect. Unless the table name starts with the database / schema name and a dot it will be prefixed.
$aliasThe alias for the table. In most cases this should be the first letter of the table, or the first letter of each "word" in the table.
$conditionThe condition on which to join this table. If the join requires values, this clause should use a named placeholder and the value or values to insert should be passed in the 4th parameter. For the first table joined on a query, this value is ignored as the first table is taken as the base table. The token alias can be used in this string to be replaced with the actual alias. This is useful when $alias is modified by the database system, for example, when joining the same table more than once.
$argumentsAn array of arguments to replace into the $condition of this join.
Returns
The unique alias that was assigned for this table.

Implemented in Select, and SelectExtender.

leftJoin (   $table,
  $alias = NULL,
  $condition = NULL,
  $arguments = array() 
)

Left Outer Join against another table in the database.

Parameters
$tableThe table against which to join. May be a string or another SelectQuery object. If a query object is passed, it will be used as a subselect. Unless the table name starts with the database / schema name and a dot it will be prefixed.
$aliasThe alias for the table. In most cases this should be the first letter of the table, or the first letter of each "word" in the table.
$conditionThe condition on which to join this table. If the join requires values, this clause should use a named placeholder and the value or values to insert should be passed in the 4th parameter. For the first table joined on a query, this value is ignored as the first table is taken as the base table. The token alias can be used in this string to be replaced with the actual alias. This is useful when $alias is modified by the database system, for example, when joining the same table more than once.
$argumentsAn array of arguments to replace into the $condition of this join.
Returns
The unique alias that was assigned for this table.

Implemented in Select, and SelectExtender.

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.

Parameters
$fieldThe field on which to order. The field is escaped for security so only valid field and alias names are possible. To order by an expression, add the expression with addExpression() first and then use the alias to order on.

Example: $query->addExpression('SUBSTRING(thread, 1, (LENGTH(thread) - 1))', 'order_field'); $query->orderBy('order_field', 'ASC');

Parameters
$directionThe direction to sort. Legal values are "ASC" and "DESC". Any other value will be converted to "ASC".
Returns
The called object.

Implemented in Select, SelectExtender, and Select.

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.

Returns
The called object

Implemented in Select, SelectExtender, and Select.

preExecute ( SelectInterface  $query = NULL)

Generic preparation and validation for a SELECT query.

Returns
TRUE if the validation was successful, FALSE if not.

Implemented in Select, and SelectExtender.

Referenced by Cache\keyFromQuery().

Here is the caller graph for this function:

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.

Parameters
$startThe first record from the result set to return. If NULL, removes any range directives that are set.
$lengthThe number of records to return from the result set.
Returns
The called object.

Implemented in Select, and SelectExtender.

rightJoin (   $table,
  $alias = NULL,
  $condition = NULL,
  $arguments = array() 
)

Right Outer Join against another table in the database.

Parameters
$tableThe table against which to join. May be a string or another SelectQuery object. If a query object is passed, it will be used as a subselect. Unless the table name starts with the database / schema name and a dot it will be prefixed.
$aliasThe alias for the table. In most cases this should be the first letter of the table, or the first letter of each "word" in the table.
$conditionThe condition on which to join this table. If the join requires values, this clause should use a named placeholder and the value or values to insert should be passed in the 4th parameter. For the first table joined on a query, this value is ignored as the first table is taken as the base table. The token alias can be used in this string to be replaced with the actual alias. This is useful when $alias is modified by the database system, for example, when joining the same table more than once.
$argumentsAn array of arguments to replace into the $condition of this join.
Returns
The unique alias that was assigned for this table.

Implemented in Select, and SelectExtender.

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.

Parameters
$queryThe query to UNION to this query.
$typeThe type of UNION to add to the query. Defaults to plain UNION.
Returns
The called object.

Implemented in Select, and SelectExtender.


The documentation for this interface was generated from the following file: