GroupBy

This is the documentation of the GraphQL Library version 7. For the long-term support (LTS) version 5, refer to GraphQL Library version 5 LTS.

The directive @groupBy defines fields that can be used to group query results.

Consider the following definition:

type Movie @node {
    title: String!
    year: Int! @groupBy
}

It adds the field groupBy to the movieConnection operation.

The groupBy field has a single, mandatory argument fields which defines the field to group the results by. The type of the groupBy field is a list of results compliant to the Connection Spec. The following example shows how to query movies grouped by the year field. In this case, year is the only field the results can be group by.

query {
  moviesConnection {
    groupBy(fields: { year: true }) {
      edges {
        node {
          title
          year
        }
      }
    }
  }
}

The result of this query is a list of edges wherein all results share the same value of the year field.

{
    "moviesConnection": {
        "groupBy": [
            {
                "edges": [
                    {
                        "node": {
                            "title": "The Matrix",
                            "year": 1999
                        }
                    },
                    {
                        "title": "Fight Club",
                        "year": 1999
                    }
                ]
            },
            {
                "edges": [
                    {
                        "node": {
                            "title": "Gladiator",
                            "year": 2000
                        }
                    }
                ]
            }
        ]
    }
}

Nodes can be grouped by multiple fields.

Consider the following type definition:

type Movie @node {
    title: String!
    year: Int! @groupBy
    rating: Int! @groupBy
}

You can now use both year and rating fields in the argument of the groupBy field.

query {
  moviesConnection {
    groupBy(fields: { year: true, rating: true }) {
      edges {
        node {
          title
          year
        }
      }
    }
  }
}

In this case, all movies with the same year and rating are grouped together in the same result.