GROUP BY (NoSQL query)

  • Article

APPLIES TO: NoSQL

The GROUP BY clause divides the query's results according to the values of one or more specified properties.

Syntax

<group_by_clause> ::= GROUP BY <scalar_expression_list>

<scalar_expression_list> ::=
          <scalar_expression>
        | <scalar_expression_list>, <scalar_expression>

Arguments

Description
<scalar_expression_list> Specifies the expressions that are used to group (or divide) query results.
<scalar_expression> Any scalar expression is allowed except for scalar subqueries and scalar aggregates. Each scalar expression must contain at least one property reference. There's no limit to the number of individual expressions or the cardinality of each expression.

Examples

For the examples in this section, this reference set of items is used. Each item includes a capabilities object that may include softwareDevelopment and mediaTrained properties.

[
  {
    "name": "Jordan Mitchell",
    "capabilities": {
      "softwareDevelopment": "python",
      "mediaTrained": true
    },
    "team": "Cloud software engineering"
  },
  {
    "name": "Mikaela Lee",
    "capabilities": {
      "softwareDevelopment": "javascript",
      "mediaTrained": false
    },
    "team": "Cloud software engineering"
  },
  {
    "name": "Graham Barnes",
    "capabilities": {
      "softwareDevelopment": "c-sharp",
      "mediaTrained": true
    },
    "team": "Cloud software engineering"
  },
  {
    "name": "Hayden Cook",
    "capabilities": {
      "softwareDevelopment": "javascript",
      "mediaTrained": true
    },
    "team": "Cloud software engineering"
  },
  {
    "name": "Morgan Connors",
    "capabilities": {
      "mediaTrained": true
    },
    "team": "Cloud software engineering"
  },
  {
    "name": "Devon Torres",
    "capabilities": {
      "softwareDevelopment": "python",
      "mediaTrained": false
    },
    "team": "Cloud software engineering"
  },
  {
    "name": "Sam Centrell",
    "capabilities": {
      "softwareDevelopment": "javascript",
      "mediaTrained": true
    },
    "team": "Cloud software engineering"
  }
]

In this first example, the GROUP BY clause is used to create groups of items using the value of a specified property.

SELECT 
    e.capabilities.softwareDevelopment AS developmentLang
FROM
    employees e
GROUP BY
    e.capabilities.softwareDevelopment

[
  {
    "developmentLang": "python"
  },
  {
    "developmentLang": "javascript"
  },
  {
    "developmentLang": "c-sharp"
  },
  {}
]

In this next example, an aggregate system function (COUNT) is used with the groupings to provide a total number of items per group.

SELECT 
    COUNT(1) AS trainedEmployees, 
    e.capabilities.softwareDevelopment AS developmentLang
FROM
    employees e
GROUP BY
    e.capabilities.softwareDevelopment

[
  {
    "trainedEmployees": 2,
    "developmentLang": "python"
  },
  {
    "trainedEmployees": 3,
    "developmentLang": "javascript"
  },
  {
    "trainedEmployees": 1,
    "developmentLang": "c-sharp"
  },
  {
    "trainedEmployees": 1
  }
]

In this final example, the items are grouped using multiple properties.

SELECT 
    COUNT(1) AS employeesWithThisTraining, 
    e.capabilities.softwareDevelopment AS developmentLang,
    e.capabilities.mediaTrained AS mediaReady
FROM
    employees e
GROUP BY
    e.capabilities.softwareDevelopment,
    e.capabilities.mediaTrained

[
  {
    "employeesWithThisTraining": 1,
    "developmentLang": "python",
    "mediaReady": true
  },
  {
    "employeesWithThisTraining": 1,
    "developmentLang": "javascript",
    "mediaReady": false
  },
  {
    "employeesWithThisTraining": 1,
    "developmentLang": "c-sharp",
    "mediaReady": true
  },
  {
    "employeesWithThisTraining": 2,
    "developmentLang": "javascript",
    "mediaReady": true
  },
  {
    "employeesWithThisTraining": 1,
    "mediaReady": true
  },
  {
    "employeesWithThisTraining": 1,
    "developmentLang": "python",
    "mediaReady": false
  }
]

Remarks

  • When a query uses a GROUP BY clause, the SELECT clause can only contain the subset of properties and system functions included in the GROUP BY clause. One exception is aggregate functions, which can appear in the SELECT clause without being included in the GROUP BY clause. You can also always include literal values in the SELECT clause.
  • The GROUP BY clause must be after the SELECT, FROM, and WHERE clause and before the OFFSET LIMIT clause. You can't use GROUP BY with an ORDER BY clause.
  • The GROUP BY clause doesn't allow any of the following features, properties, or functions:
    • Aliasing properties or aliasing system functions (aliasing is still allowed within the SELECT clause)
    • Subqueries
    • Aggregate system functions (these functions are only allowed in the SELECT clause)
  • Queries with an aggregate system function and a subquery with GROUP BY aren't supported.
  • Cross-partition GROUP BY queries can have a maximum of 21 aggregate system functions.

Related content