Neo4j GraphQL Aggregations

Recently we released opens in new tabNeo4j GraphQL 2.4.0 that contained some really cool features, but the coolest, in my opinion, is the autogenerated aggregation queries.

What Do You Mean by Aggregations?

We use the term aggregations to encapsulate the retrieval of statistical information about the nodes, relationships, and their properties in your graph. Statistical information may be answering questions such as:

1. What is the longest movie title?
2. What is the latest movie?
3. Who directed more than 3 movies?
4. What movie has an average rating greater than 10?
5. What is the average age of all the actors in a movie?
6. What is the highest rating of a movie?

Prior to our 2.4.0 release, users would have to employ our Cypher Directive, and where they would have to manually write Cypher to answer such questions. Now, with our latest release, the autogenerated aggregation queries remove the need to write any custom logic at all!

How Do I Get Started?

Let’s first establish what our Graph will look like. For this we will use the ‘Movie Graph’ located on the right side of Neo4j Browser:

This can be expressed with Neo4j GraphQL Type Definitions like so:

	type Movie {
	released: BigInt!
	tagline: String
	title: String!
	actors: [Person] @relationship(type: "ACTED_IN", direction: IN)
	directors: [Person] @relationship(type: "DIRECTED", direction: IN)
	reviewers: [Person] @relationship(type: "REVIEWED", direction: IN, properties: "ReviewedProperties")
	}
	type Person {
	born: BigInt
	name: String!
	actedIn: [Movie] @relationship(type: "ACTED_IN", direction: OUT)
	directed: [Movie] @relationship(type: "DIRECTED", direction: OUT)
	reviewed: [Movie] @relationship(type: "REVIEWED", direction: OUT, properties: "ReviewedProperties")
	}
	interface ReviewedProperties @relationshipProperties {
	rating: BigInt!
	summary: String!
	}

view raw neo4j-graphql-aggregations-blog-schema.gql hosted with by GitHub

You can visit our Documentation Getting Started Guide to learn how to use the above Type Definitions to autogenerate all the queries in this blog.

Top-Level Aggregations

Firstly let’s start at the top. We consider ‘Top-Level’ to be the queries at the root of your GraphQL API. Those queries would be, for example; movies, people, etc. The point is it’s always considered a node from the root. In our new release, we added aggregate queries to this level. Below are some examples using those new queries plus you can learn more about top-level Aggregations here.

What is the longest movie title?

GraphQL Query:

	{
	moviesAggregate {
	title {
	longest
	}
	}
	}

view raw neo4j-graphql-aggregations-longest-title-gql.gql hosted with by GitHub

Response:

	{
	"data": {
	"moviesAggregate": {
	"title": {
	"longest": "One Flew Over the Cuckoo's Nest"
	}
	}
	}
	}

view raw neo4j-graphql-aggregations-longest-title-json.json hosted with by GitHub

What is the latest movie?

GraphQL Query:

	{
	moviesAggregate {
	released {
	max
	}
	}
	}

view raw neo4j-graphql-aggregations-oldest-movie.gql hosted with by GitHub

Response:

	{
	"data": {
	"moviesAggregate": {
	"released": {
	"max": "2012"
	}
	}
	}
	}

view raw neo4j-graphql-aggregations-oldest-movie-json.json hosted with by GitHub

Where Aggregations

These aggregations are those that are inside the already existing where argument. Below are some examples using those new queries plus you can learn more about Where Aggregations here.

Who directed more than 3 movies?

GraphQL Query:

	{
	people(
	where: { directedAggregate: { count_GT: 3 } }
	) {
	born
	name
	}
	}

view raw neo4j-graphql-aggregations-directed-count-gql.gql hosted with by GitHub

Response:

	{
	"data": {
	"people": [
	{
	"born": "1967",
	"name": "Lilly Wachowski"
	},
	{
	"born": "1965",
	"name": "Lana Wachowski"
	}
	]
	}
	}

view raw neo4j-graphql-aggregations-directed-count-json.json hosted with by GitHub

What movie has an average rating greater than 10?

GraphQL Query:

	{
	movies(
	where: {
	reviewersAggregate: {
	edge: { rating_AVERAGE_GT: 10 }
	}
	}
	) {
	title
	}
	}

view raw neo4j-graphql-aggregations-movie-average-rating-gql.gql hosted with by GitHub

Response:

	{
	"data": {
	"movies": [
	{
	"title": "Jerry Maguire"
	},
	{
	"title": "The Replacements"
	},
	{
	"title": "The Birdcage"
	},
	{
	"title": "Unforgiven"
	},
	{
	"title": "Cloud Atlas"
	},
	{
	"title": "The Da Vinci Code"
	}
	]
	}
	}

view raw neo4j-graphql-aggregations-movie-average-rating-json.json hosted with by GitHub

Field Aggregations

Finally, these aggregations are across relationships. You use these aggregations nested inside a node, just like how you would select the actors of a movie, you can now also aggregate the actors of a movie. Below are some examples using Field Aggregations plus you can learn more about them here.

What is the average age of all the actors in a movie?

GraphQL Query:

	{
	movies(where: { title: "The Matrix" }) {
	title
	actorsAggregate {
	node {
	born {
	average
	}
	}
	}
	}
	}

view raw neo4j-graphql-aggregations-average-movie-age-gql.gql hosted with by GitHub

Response:

	{
	"data": {
	"movies": [
	{
	"title": "The Matrix",
	"actorsAggregate": {
	"node": {
	"born": {
	"average": "1966"
	}
	}
	}
	}
	]
	}
	}

view raw neo4j-graphql-aggregations-average-movie-age-json.json hosted with by GitHub

What is the highest rating of a movie?

GraphQL Query:

	{
	movies(where: { title: "The Da Vinci Code" }) {
	title
	reviewersAggregate {
	edge {
	rating {
	max
	}
	}
	}
	}
	}

view raw neo4j-graphql-aggregations-highest-movie-rating-gql.gql hosted with by GitHub

Response:

	{
	"data": {
	"movies": [
	{
	"title": "The Da Vinci Code",
	"reviewersAggregate": {
	"edge": {
	"rating": {
	"max": "68"
	}
	}
	}
	}
	]
	}
	}

view raw neo4j-graphql-aggregations-highest-movie-rating-json.json hosted with by GitHub

Aggregating with the OGM

We also exposed the aggregation queries using the OGM. Here is an example aggregating the title fields on a movie:

	const { OGM } = require("@neo4j/graphql");
	const neo4j = require("neo4j");
	const typeDefs = gql`
	type Movie {
	released: BigInt!
	tagline: String
	title: String!
	## Rest of the Relationships
	}
	## Rest of the Definitions
	`;
	const driver = neo4j.driver("neo4j://localhost:7687", neo4j.auth.basic("admin", "password"));
	const ogm = new OGM({
	typeDefs,
	driver,
	});
	const Movie = ogm.model("Movie");
	const aggregation = await Movie.aggregate({
	aggregate: {
	title: {
	shortest: true,
	longest: true,
	},
	},
	});
	console.log(aggregation);
	/*
	Logs: {
	"title": {
	"shortest": "Hoffa",
	"longest": "One Flew Over the Cuckoo's Nest"
	}
	}
	*/

view raw neo4j-graphql-aggregate-with-ogm.js hosted with by GitHub

That’s It.

Thanks for taking the time to learn more about Neo4j GraphQL aggregations. We are looking forward to hearing your feedback. Resources:

1. NPM: opens in new tabhttps://www.npmjs.com/package/@neo4j/graphql
2. Github: opens in new tabhttps://github.com/neo4j/graphql
3. Documentation: https://development.neo4j.dev/docs/graphql-manual/current/
4. Discord: opens in new tabhttps://discord.gg/neo4j

opens in new tabNeo4j GraphQL Aggregations was originally published in opens in new tabNeo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.