www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Entity/Query/QueryAggregateInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Entity\Query;
   4
   5 /**
   6  * Defines a interface for aggregated entity queries.
   7  */
   8 interface QueryAggregateInterface extends QueryInterface {
   9
  10   /**
  11    * Specifies a field and a function to aggregate on.
  12    *
  13    * Available functions: SUM, AVG, MIN, MAX and COUNT.
  14    *
  15    * @todo What about GROUP_CONCAT support?
  16    *
  17    * @param string $field
  18    *   The name of the field to aggregate by.
  19    * @param string $function
  20    *   The aggregation function, for example COUNT or MIN.
  21    * @param string $langcode
  22    *   (optional) The language code.
  23    * @param string $alias
  24    *   (optional) The key that will be used on the resultset.
  25    *
  26    * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
  27    *   The called object.
  28    */
  29   public function aggregate($field, $function, $langcode = NULL, &$alias = NULL);
  30
  31   /**
  32    * Specifies the field to group on.
  33    *
  34    * @param string $field
  35    *   The name of the field to group by.
  36    *
  37    * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
  38    *   The called object.
  39    */
  40   public function groupBy($field);
  41
  42   /**
  43    * Sets a condition for an aggregated value.
  44    *
  45    * @param string $field
  46    *   The name of the field to aggregate by.
  47    * @param string $function
  48    *   The aggregation function, for example COUNT or MIN.
  49    * @param mixed $value
  50    *   The actual value of the field.
  51    * @param $operator
  52    *   Possible values:
  53    *   - '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS',
  54    *     'ENDS_WITH': These operators expect $value to be a literal of the
  55    *     same type as the column.
  56    *   - 'IN', 'NOT IN': These operators expect $value to be an array of
  57    *     literals of the same type as the column.
  58    *   - 'BETWEEN': This operator expects $value to be an array of two literals
  59    *     of the same type as the column.
  60    * @param string $langcode
  61    *   (optional) The language code.
  62    *
  63    * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
  64    *   The called object.
  65    *
  66    * @see \Drupal\Core\Entity\Query\QueryInterface::condition()
  67    */
  68   public function conditionAggregate($field, $function = NULL, $value = NULL, $operator = '=', $langcode = NULL);
  69
  70   /**
  71    * Queries for the existence of a field.
  72    *
  73    * @param string $field
  74    *   The name of the field.
  75    * @param string $function
  76    *   The aggregate function.
  77    * @param $langcode
  78    *   (optional) The language code.
  79    *
  80    * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
  81    *   The called object.
  82    */
  83   public function existsAggregate($field, $function, $langcode = NULL);
  84
  85   /**
  86    * Queries for the nonexistence of a field.
  87    *
  88    * @param string $field
  89    *   The name of a field.
  90    * @param string $function
  91    *   The aggregate function.
  92    * @param string $langcode
  93    *   (optional) The language code.
  94    *
  95    * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
  96    *   The called object.
  97    */
  98   public function notExistsAggregate($field, $function, $langcode = NULL);
  99
 100   /**
 101    * Creates an object holding a group of conditions.
 102    *
 103    * See andConditionAggregateGroup() and orConditionAggregateGroup() for more.
 104    *
 105    * @param string $conjunction
 106    *   - AND (default): this is the equivalent of andConditionAggregateGroup().
 107    *   - OR: this is the equivalent of andConditionAggregateGroup().
 108    *
 109    * @return ConditionInterface
 110    *   An object holding a group of conditions.
 111    */
 112   public function conditionAggregateGroupFactory($conjunction = 'AND');
 113
 114   /**
 115    * Sorts by an aggregated value.
 116    *
 117    * @param string $field
 118    *   The name of a field.
 119    * @param string $function
 120    *   The aggregate function. This is only marked optional for interface
 121    *   compatibility, it is illegal to leave it out.
 122    * @param string $direction
 123    *   The order of sorting, either DESC for descending of ASC for ascending.
 124    * @param string $langcode
 125    *   (optional) The language code.
 126    *
 127    * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
 128    *   The called object.
 129    */
 130   public function sortAggregate($field, $function, $direction = 'ASC', $langcode = NULL);
 131
 132   /**
 133    * Executes the aggregate query.
 134    *
 135    * @return array
 136    *   A list of result row arrays. Each result row contains the aggregate
 137    *   results as keys and also the groupBy columns as keys:
 138    * @code
 139    * $result = $query
 140    *   ->aggregate('nid', 'count')
 141    *   ->condition('status', 1)
 142    *   ->groupby('type')
 143    *   ->executeAggregate();
 144    * @endcode
 145    * Will return:
 146    * @code
 147    * $result[0] = array('count_nid' => 3, 'type' => 'page');
 148    * $result[1] = array('count_nid' => 1, 'type' => 'poll');
 149    * $result[2] = array('count_nid' => 4, 'type' => 'story');
 150    * @endcode
 151    */
 152   public function execute();
 153
 154 }