1. interface
  2. Drupal
  3. \
  4. Core
  5. \
  6. Entity
  7. \
  8. Query
  9. \
  10. QueryAggregateInterface

QueryAggregateInterface

interface QueryAggregateInterface implements QueryInterface (View source)

Defines an interface for aggregated entity queries.

Methods

$this
addTag($tag)

Adds a tag to a query.

from  AlterableInterface
true
hasTag($tag)

Determines if a given query has a given tag.

from  AlterableInterface
true
hasAllTags()

Determines if a given query has all specified tags.

from  AlterableInterface
true
hasAnyTag()

Determines if a given query has any specified tag.

from  AlterableInterface
$this
addMetaData($key, $object)

Adds additional metadata to the query.

from  AlterableInterface
The
getMetaData($key)

Retrieves a given piece of metadata.

from  AlterableInterface
string
getEntityTypeId()

Gets the ID of the entity type for this query.

from  QueryInterface
$this
condition(string|ConditionInterface $field, string|int|bool|array|null $value = NULL, string|null $operator = NULL, string|null $langcode = NULL)

Add a condition to the query or a condition group.

from  QueryInterface
$this
exists(string $field, string|null $langcode = NULL)

Queries for a non-empty value on a field.

from  QueryInterface
$this
notExists(string $field, string|null $langcode = NULL)

Queries for an empty field.

from  QueryInterface
$this
pager(int $limit = 10, int|null $element = NULL)

Enables a pager for the query.

from  QueryInterface
$this
range(int|null $start = NULL, int|null $length = NULL)

Defines the range of the query.

from  QueryInterface
$this
sort(string $field, string $direction = 'ASC', string|null $langcode = NULL)

Sorts the result set by a given field.

from  QueryInterface
$this
count()

Makes this a count query.

from  QueryInterface
$this
tableSort(array $headers)

Enables sortable tables for this query.

from  QueryInterface
$this
accessCheck(bool $access_check = TRUE)

Enables or disables access checking for this query.

from  QueryInterface
int|array
execute()

Executes the aggregate query.

ConditionInterface
andConditionGroup()

Creates a new group of conditions ANDed together.

from  QueryInterface
ConditionInterface
orConditionGroup()

Creates a new group of conditions ORed together.

from  QueryInterface
$this
currentRevision()

Limits the query to only default revisions.

from  QueryInterface
$this
latestRevision()

Queries the latest revision.

from  QueryInterface
$this
allRevisions()

Queries all the revisions.

from  QueryInterface
$this
aggregate(string $field, string $function, string $langcode = NULL, string $alias = NULL)

Specifies a field and a function to aggregate on.

$this
groupBy(string $field)

Specifies the field to group on.

$this
conditionAggregate(string $field, string $function = NULL, mixed $value = NULL, $operator = '=', string $langcode = NULL)

Sets a condition for an aggregated value.

$this
existsAggregate(string $field, string $function, $langcode = NULL)

Queries for the existence of a field.

$this
notExistsAggregate(string $field, string $function, string $langcode = NULL)

Queries for the nonexistence of a field.

ConditionInterface
conditionAggregateGroupFactory(string $conjunction = 'AND')

Creates an object holding a group of conditions.

$this
sortAggregate(string $field, string $function, string $direction = 'ASC', string $langcode = NULL)

Sorts by an aggregated value.

Details

in AlterableInterface at line 25
$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.

Parameters

$tag

The tag to add.

Return Value

$this

The called object.

in AlterableInterface at line 36
true hasTag($tag)

Determines if a given query has a given tag.

Parameters

$tag

The tag to check.

Return Value

true

if this query has been marked with this tag, FALSE otherwise.

in AlterableInterface at line 50
true hasAllTags()

Determines if a given query has all specified tags.

Each tag to check should be supplied as a separate argument.

Restore PHPDoc of variadic argument in Drupal 8.8, see https://www.drupal.org/project/drupal/issues/3029729

Return Value

true

if this query has been marked with all specified tags, FALSE otherwise.

in AlterableInterface at line 64
true hasAnyTag()

Determines if a given query has any specified tag.

Each tag to check should be supplied as a separate argument.

Restore PHPDoc of variadic argument in Drupal 8.8, see https://www.drupal.org/project/drupal/issues/3029729

Return Value

true

if this query has been marked with at least one of the specified tags, FALSE otherwise.

in AlterableInterface at line 82
$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.

Parameters

$key

The unique identifier for this piece of metadata. Must be a string that follows the same rules as any other PHP identifier.
$object

The additional data to add to the query. May be any valid PHP variable.

Return Value

$this

The called object.

in AlterableInterface at line 93
The getMetaData($key)

Retrieves a given piece of metadata.

Parameters

$key

The unique identifier for the piece of metadata to retrieve.

Return Value

The

previously attached metadata object, or NULL if one doesn't exist.

in QueryInterface at line 23
string getEntityTypeId()

Gets the ID of the entity type for this query.

Return Value

string

The entity type ID.

in QueryInterface at line 113
$this condition(string|ConditionInterface $field, string|int|bool|array|null $value = NULL, string|null $operator = NULL, string|null $langcode = NULL)

Add a condition to the query or a condition group.

For example, to find all entities containing both the Turkish 'merhaba' and the Polish 'siema' within a 'greetings' text field:

Parameters

string|ConditionInterface $field

Name of the field being queried or an instance of ConditionInterface. In the case of the name, it must contain a field name, optionally followed by a column name. The column can be the reference property, usually "entity", for reference fields and that can be followed similarly by a field name and so on. Additionally, the target entity type can be specified by appending the ":target_entity_type_id" to "entity". Some examples:

  • nid
  • tags.value
  • tags
  • tags.entity.name
  • tags.entity:taxonomy_term.name
  • uid.entity.name
  • uid.entity:user.name "tags" "is the same as "tags.value" as value is the default column. If two or more conditions have the same field names they apply to the same delta within that field. In order to limit the condition to a specific item a numeric delta should be added between the field name and the column name. @code ->condition('tags.5.value', 'news') @endcode This will require condition to be satisfied on a specific delta of the field. The condition above will require the 6th value of the field to match the provided value. Further, it's possible to create a condition on the delta itself by using '%delta'. For example, @code ->condition('tags.%delta', 5) @endcode will find only entities which have at least six tags. Finally, the condition on the delta itself accompanied with a condition on the value will require the value to appear in the specific delta range. For example, @code ->condition('tags.%delta', 0, '>')) ->condition('tags.%delta.value', 'news')) @endcode will only find the "news" tag if it is not the first value. It should be noted that conditions on specific deltas and delta ranges are only supported when querying content entities.
string|int|bool|array|null $value

(optional) The value for $field. In most cases, this is a scalar and it's treated as case-insensitive. For more complex operators, it is an array. The meaning of each element in the array is dependent on $operator. Defaults to NULL, for most operators (except: 'IS NULL', 'IS NOT NULL') it always makes the condition false.
string|null $operator

(optional) The comparison operator. Possible values:

  • '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS', 'ENDS_WITH': These operators expect $value to be a literal of the same type as the column.
  • 'IN', 'NOT IN': These operators expect $value to be an array of literals of the same type as the column.
  • 'IS NULL', 'IS NOT NULL': These operators ignore $value, for that reason it is recommended to use a $value of NULL for clarity.
  • 'BETWEEN', 'NOT BETWEEN': These operators expect $value to be an array of two literals of the same type as the column. If NULL, defaults to the '=' operator.
string|null $langcode

(optional) The language code allows filtering results by specific language. If two or more conditions omit the langcode within one condition group then they are presumed to apply to the same translation. If within one condition group one condition has a langcode and another does not they are not presumed to apply to the same translation. If omitted (NULL), any translation satisfies the condition.

Return Value

$this

See also

QueryInterface::andConditionGroup
QueryInterface::orConditionGroup
ConditionInterface
QueryInterface::exists
QueryInterface::notExists

in QueryInterface at line 126
$this exists(string $field, string|null $langcode = NULL)

Queries for a non-empty value on a field.

Parameters

string $field

Name of a field.
string|null $langcode

(optional) The language code allows filtering results by specific language. If omitted (NULL), any translation satisfies the condition.

Return Value

$this

in QueryInterface at line 139
$this notExists(string $field, string|null $langcode = NULL)

Queries for an empty field.

Parameters

string $field

Name of a field.
string|null $langcode

(optional) The language code allows filtering results by specific language. If omitted (NULL), any translation satisfies the condition.

Return Value

$this

in QueryInterface at line 154
$this pager(int $limit = 10, int|null $element = NULL)

Enables a pager for the query.

Parameters

int $limit

(optional) An integer specifying the number of elements per page. If passed 0, the pager is disabled.
int|null $element

(optional) An integer to distinguish between multiple pagers on one page. If not provided, one is automatically calculated by incrementing the next pager element value.

Return Value

$this

in QueryInterface at line 170
$this range(int|null $start = NULL, int|null $length = NULL)

Defines the range of the query.

Parameters

int|null $start

(optional) The first record from the result set to return. If NULL, removes any range directives that are set.
int|null $length

(optional) The maximum number of rows to return. If $start and $length are NULL, then a complete result set will be generated. If $start is not NULL and $length is NULL, then an empty result set will be generated.

Return Value

$this

in QueryInterface at line 189
$this sort(string $field, string $direction = 'ASC', string|null $langcode = NULL)

Sorts the result set by a given field.

standardize $direction options in https://www.drupal.org/project/drupal/issues/3079258

Parameters

string $field

Name of a field.
string $direction

(optional) The direction to sort. Allowed values are "ASC" and "DESC". Defaults to "ASC".
string|null $langcode

(optional) The language code allows filtering results by specific language. If omitted (NULL), any translation satisfies the condition.

Return Value

$this

in QueryInterface at line 198
$this count()

Makes this a count query.

For count queries, execute() returns the number entities found.

Return Value

$this

in QueryInterface at line 211
$this tableSort(array $headers)

Enables sortable tables for this query.

Parameters

array $headers

An array of headers of the same structure as described in template_preprocess_table(). Use a 'specifier' in place of a 'field' to specify what to sort on. This can be an entity or a field as described in condition().

Return Value

$this

in QueryInterface at line 221
$this accessCheck(bool $access_check = TRUE)

Enables or disables access checking for this query.

Parameters

bool $access_check

(optional) Whether access check is requested or not. Defaults to TRUE.

Return Value

$this

at line 152
int|array execute()

Executes the aggregate query.

Return Value

int|array

Returns an integer for count queries or an array of ids. The values of the array are always entity ids. The keys will be revision ids if the entity supports revision and entity ids if not.

in QueryInterface at line 255
ConditionInterface andConditionGroup()

Creates a new group of conditions ANDed together.

For example, consider a drawing entity type with a 'figures' multi-value field containing 'shape' and 'color' columns. To find all drawings containing both a red triangle and a blue circle:

Return Value

ConditionInterface

A condition object whose conditions will be combined with AND.

in QueryInterface at line 284
ConditionInterface orConditionGroup()

Creates a new group of conditions ORed together.

For example, consider a map entity with an 'attributes' field containing 'building_type' and 'color' columns. To find all green and red bikesheds:

Return Value

ConditionInterface

A condition object whose conditions will be combined with OR.

in QueryInterface at line 294
$this currentRevision()

Limits the query to only default revisions.

See the @link entity_api Entity API topic @endlink for information about the current revision.

Return Value

$this

in QueryInterface at line 305
$this latestRevision()

Queries the latest revision.

The latest revision is the most recent revision of an entity. This will be either the default revision, or a pending revision if one exists and it is newer than the default.

Return Value

$this

in QueryInterface at line 312
$this allRevisions()

Queries all the revisions.

Return Value

$this

at line 29
$this aggregate(string $field, string $function, string $langcode = NULL, string $alias = NULL)

Specifies a field and a function to aggregate on.

Available functions: SUM, AVG, MIN, MAX and COUNT.

What about GROUP_CONCAT support?

Parameters

string $field

The name of the field to aggregate by.
string $function

The aggregation function, for example COUNT or MIN.
string $langcode

(optional) The language code.
string $alias

(optional) The key that will be used on the resultset.

Return Value

$this

The called object.

at line 40
$this groupBy(string $field)

Specifies the field to group on.

Parameters

string $field

The name of the field to group by.

Return Value

$this

The called object.

at line 68
$this conditionAggregate(string $field, string $function = NULL, mixed $value = NULL, $operator = '=', string $langcode = NULL)

Sets a condition for an aggregated value.

Parameters

string $field

The name of the field to aggregate by.
string $function

The aggregation function, for example COUNT or MIN.
mixed $value

The actual value of the field.
$operator

Possible values:

  • '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS', 'ENDS_WITH': These operators expect $value to be a literal of the same type as the column.
  • 'IN', 'NOT IN': These operators expect $value to be an array of literals of the same type as the column.
  • 'BETWEEN': This operator expects $value to be an array of two literals of the same type as the column.
string $langcode

(optional) The language code.

Return Value

$this

The called object.

See also

QueryInterface::condition

at line 83
$this existsAggregate(string $field, string $function, $langcode = NULL)

Queries for the existence of a field.

Parameters

string $field

The name of the field.
string $function

The aggregate function.
$langcode

(optional) The language code.

Return Value

$this

The called object.

at line 98
$this notExistsAggregate(string $field, string $function, string $langcode = NULL)

Queries for the nonexistence of a field.

Parameters

string $field

The name of a field.
string $function

The aggregate function.
string $langcode

(optional) The language code.

Return Value

$this

The called object.

at line 112
ConditionInterface conditionAggregateGroupFactory(string $conjunction = 'AND')

Creates an object holding a group of conditions.

See andConditionAggregateGroup() and orConditionAggregateGroup() for more.

Parameters

string $conjunction
  • AND (default): this is the equivalent of andConditionAggregateGroup().
  • OR: this is the equivalent of andConditionAggregateGroup().

Return Value

ConditionInterface

An object holding a group of conditions.

at line 130
$this sortAggregate(string $field, string $function, string $direction = 'ASC', string $langcode = NULL)

Sorts by an aggregated value.

Parameters

string $field

The name of a field.
string $function

The aggregate function. This is only marked optional for interface compatibility, it is illegal to leave it out.
string $direction

The order of sorting, either DESC for descending of ASC for ascending.
string $langcode

(optional) The language code.

Return Value

$this

The called object.