Skip to content

add documentation for group by directive#296

Open
angrykoala wants to merge 2 commits into7.xfrom
group-by-docs
Open

add documentation for group by directive#296
angrykoala wants to merge 2 commits into7.xfrom
group-by-docs

Conversation

@angrykoala
Copy link
Member

This is the documentation for the PR neo4j/graphql#7061

Co-authored-by: Richard Sill <156673635+rsill-neo4j@users.noreply.github.com>
Copy link
Contributor

@a-alle a-alle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a couple of suggestions that make sense together, to create a more coherent flow. Don't feel too strongly about it so feel free to ignore but in my opinion it reads better.

Also, should we mention that relationship fields and non-primitive types cannot be annotated with this directive?

[source, graphql, indent=0]
----
"""Enables groupBy operations for this field."""
directive @groupBy() on FIELD_DEFINITION
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this have the empty paranthesis?

The field allows you to query movies grouped by the `year` field.


The `groupBy` field has one argument `fields`, that defines the field to group by.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `groupBy` field has one argument `fields`, that defines the field to group by.
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.

----

It adds the field `groupBy` to the `movieConnection` operation.
The field allows you to query movies grouped by the `year` field.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The field allows you to query movies grouped by the `year` field.



The `groupBy` field has one argument `fields`, that defines the field to group by.
In this case `year` is the only option.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In this case `year` is the only option.
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.

}
----

The `groupBy` field returns a list of results and each result contains a list of `edges`, with all results grouped by the `year` field.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `groupBy` field returns a list of results and each result contains a list of `edges`, with all results grouped by the `year` field.
The result of this query is a list of `edges` wherein all results share the same value of the `year` field.

----

The `groupBy` field returns a list of results and each result contains a list of `edges`, with all results grouped by the `year` field.
For example:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For example:

}
----

Note that the `year` field is repeated on every node of the `edges` from each `groupBy` result.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Note that the `year` field is repeated on every node of the `edges` from each `groupBy` result.


Note that the `year` field is repeated on every node of the `edges` from each `groupBy` result.

Nodes can be grouped by multiple fields:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Nodes can be grouped by multiple fields:
Nodes can be grouped by multiple fields.
Consider the following type definition:
[source, graphql, indent=0]
----
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.

@a-alle
Copy link
Contributor

a-alle commented Mar 19, 2026

One more thing: I feel like this feature is too buried, it's 3 levels deep inside a page with a sort of unrelated title. I'd never think to search for this feature there. Is there any place in the docs that's more visible where we can link this section? Maybe in queries?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants