Group

The group statement is only available in EdgeDB 2.0 or later.

The group statement provides a powerful mechanism for categorizing a set of objects (e.g., movies) into groups. You can group by properties, expressions, or combinatations thereof.

This page does not aim to describe how the group statement works, merely the syntax for writing e.group statements with the query builder. For full documentation, refer to EdgeQL > Group.

Simple grouping

Sort a set of objects by a simple property.

TypeScript

EdgeQL

  1. e.group(e.Movie, movie => {
  2.   return {
  3.     by: {release_year: movie.release_year}
  4.   }
  5. });
  6. /*
  7.   [
  8.     {
  9.       key: {release_year: 2008},
  10.       grouping: ["release_year"],
  11.       elements: [{id: "..."}, {id: "..."}]
  12.     },
  13.     {
  14.       key: { release_year: 2009 },
  15.       grouping: ["release_year"],
  16.       elements: [{id: "..."}, {id: "..."}]
  17.     },
  18.     // ...
  19.   ]
  20. */
  1. group Movie
  2. by .release_year

Add a shape that will be applied to elements. The by key is a special key, similar to filter, etc. in e.select. All other keys are interpreted as shape elements and support the same functionality as e.select (nested shapes, computeds, etc.).

TypeScript

EdgeQL

  1. e.group(e.Movie, movie => {
  2.   return {
  3.     title: true,
  4.     actors: {name: true},
  5.     num_actors: e.count(movie.characters),
  6.     by: {release_year: movie.release_year}
  7.   }
  8. });
  9. /* [
  10.   {
  11.     key: {release_year: 2008},
  12.     grouping: ["release_year"],
  13.     elements: [{
  14.       title: "Iron Man",
  15.       actors: [...],
  16.       num_actors: 5
  17.     }, {
  18.       title: "The Incredible Hulk",
  19.       actors: [...],
  20.       num_actors: 3
  21.     }]
  22.   },
  23.   // ...
  24. ] */
  1. group Movie {
  2.   title,
  3.   num_actors := count(.actors)
  4. }
  5. by .release_year

Group by a tuple of properties.

TypeScript

EdgeQL

  1. e.group(e.Movie, movie => {
  2.   const release_year = movie.release_year;
  3.   const first_letter = movie.title[0];
  4.   return {
  5.     title: true,
  6.     by: {release_year, first_letter}
  7.   };
  8. });
  9. /*
  10.   [
  11.     {
  12.       key: {release_year: 2008, first_letter: "I"},
  13.       grouping: ["release_year", "first_letter"],
  14.       elements: [{title: "Iron Man"}]
  15.     },
  16.     {
  17.       key: {release_year: 2008, first_letter: "T"},
  18.       grouping: ["release_year", "first_letter"],
  19.       elements: [{title: "The Incredible Hulk"}]
  20.     },
  21.     // ...
  22.   ]
  23. */
  1. group Movie { title }
  2. using first_letter := .title[0]
  3. by .release_year, first_letter

Using grouping sets to group by several expressions simultaneously.

TypeScript

EdgeQL

  1. e.group(e.Movie, movie => {
  2.   const release_year = movie.release_year;
  3.   const first_letter = movie.title[0];
  4.   return {
  5.     title: true,
  6.     by: e.group.set({release_year, first_letter})
  7.   };
  8. });
  9. /* [
  10.   {
  11.     key: {release_year: 2008},
  12.     grouping: ["release_year"],
  13.     elements: [{title: "Iron Man"}, {title: "The Incredible Hulk"}]
  14.   },
  15.   {
  16.     key: {first_letter: "I"},
  17.     grouping: ["first_letter"],
  18.     elements: [{title: "Iron Man"}, {title: "Iron Man 2"}, {title: "Iron Man 3"}],
  19.   },
  20.   // ...
  21. ] */
  1. group Movie { title }
  2. using first_letter := .title[0]
  3. by {.release_year, first_letter}

Using a combination of tuples and grouping sets.

TypeScript

EdgeQL

  1. e.group(e.Movie, movie => {
  2.   const release_year = movie.release_year;
  3.   const first_letter = movie.title[0];
  4.   const cast_size = e.count(movie.actors);
  5.   return {
  6.     title: true,
  7.     by: e.group.tuple(release_year, e.group.set({first_letter, cast_size}))
  8.     // by .release_year, { first_letter, cast_size }
  9.     // equivalent to
  10.     // by (.release_year, first_letter), (.release_year, cast_size),
  11.   };
  12. });
  13. /* [
  14.   {
  15.     key: {release_year: 2008, first_letter: "I"},
  16.     grouping: ["release_year", "first_letter"],
  17.     elements: [{title: "Iron Man"}]
  18.   },
  19.   {
  20.     key: {release_year: 2008, cast_size: 3},
  21.     grouping: ["release_year", "cast_size"],
  22.     elements: [{title: "The Incredible Hulk"}]
  23.   },
  24.   // ...
  25. ] */
  1. group Movie { title }
  2. using
  3.   first_letter := .title[0],
  4.   cast_size := count(.actors)
  5. by .release_year, {first_letter, cast_size}

The group statement provides a syntactic sugar for defining certain common grouping sets: cube and rollup. Here’s a quick primer on how they work:

  1. ROLLUP (a, b, c)
  2. is equivalent to
  3. {(), (a), (a, b), (a, b, c)}
  5. CUBE (a, b)
  6. is equivalent to
  7. {(), (a), (b), (a, b)}

To use these in the query builder use the e.group.cube and e.group.rollup functions.

TypeScript

EdgeQL

  1. e.group(e.Movie, movie => {
  2.   const release_year = movie.release_year;
  3.   const first_letter = movie.title[0];
  4.   const cast_size = e.count(movie.actors);
  5.   return {
  6.     title: true,
  7.     by: e.group.rollup({release_year, first_letter, cast_size})
  8.   };
  9. });
  1. group Movie { title }
  2. using
  3.   first_letter := .title[0],
  4.   cast_size := count(.actors)
  5. by rollup(.release_year, first_letter, cast_size)

TypeScript

EdgeQL

  1. e.group(e.Movie, movie => {
  2.   const release_year = movie.release_year;
  3.   const first_letter = movie.title[0];
  4.   const cast_size = e.count(movie.actors);
  5.   return {
  6.     title: true,
  7.     by: e.group.cube({release_year, first_letter, cast_size})
  8.   };
  9. });
  1. group Movie { title }
  2. using
  3.   first_letter := .title[0],
  4.   cast_size := count(.actors)
  5. by cube(.release_year, first_letter, cast_size)