Summary

Welcome to my series of posts where I talk about some pros and cons to using the GRANDstack. As a whole, this series will go deep into some concepts rather than giving a broad overview of all of them.

What is it

"GRANDstack (GraphQL, React, Apollo, Neo4j Database) is a combination of technologies that work together to enable developers to build data intensive full stack applications." - GRANDstack

I think of it as a great first step into the world of Neo4j, Graph databases, and GraphQL using the popular javascript library React. You learn a good amount of GraphQL while also having to learn a lot of Cypher (query language Neo4j uses).

Good thing

The neo4j-graphql-js node package does all the heavy lifting for you. It builds basic mutations for you so you don't really need to learn Cypher when starting out. Let's say you have the Movie schema here:

Type Movie {
    id: ID!
    name: String!
    releaseDate: String
    description: String
    actors: [Actor] @relation(name: "ACTED_IN", direction: "IN")
}

All you would need to do is call the auto generated mutation CreateMovie. You don't have to pass an ID in the mutation because it knows to generate one for you. This is amazing because Neo4j's standard ID system is unusable. I touch on why it's bad below.

Now let's say you want to relate an actor to that movie. If you don't want to use Cypher then you also need to call AddActorMovie and pass both the actorId and movieId. What if I told you there was a way to make all of this happen using only one GraphQL mutation?

Then I believe it's time to learn a bit of Cypher. Specifically the @cypher directive which becomes available when using neo4j-graphql-js. When I started using GRAND I didn't initially know about the @cypher directive as the community is small and everyone is still learning. Once I found out how powerful it is I immediately dove head first into Cypher.

Cypher? That's not in the stack

Eventually you will understand why learning Cypher is important to get the most out of GRAND. Yeah it's another beast to tackle, but don't leave yet because it's not too bad. Sure it took half a year to really start to understand it, but I took that time to understand Neo4j & how Graph Databases work. In the end it gives you the ability to call a mutation to run custom Cypher whilst returning the data back in GraphQL.

CreateNewMovie(
    info: MovieInfo!
  ): Movie
    @cypher(
      statement: `
      MATCH(a:Actor {id: $info.actor.id})
      CREATE(newmovie:Movie {
          id: randomUUID(),
          name: $info.name,
          releaseDate: $info.releaseDate,
          description: $info.description
        })
      CREATE (a)-[:ACTED_IN]->(newmovie)
      return newmovie
      `
    )

So that might look confusing to someone who has never seen Cypher. Match is like SELECT and the Parenthesis is the node we are matching to. {id: $info.actor.id} The node stores info as Properties and to access them you simply use Object notation. Here we are Matching an Actor where id = variable ($ is variable).

Bad thing

You have to learn a ton just to really get started. Making sure you have a solid understanding around Neo4j and Cypher is no easy task. I was tasked with learning it for one of my clients so I was spending 30 hours a week learning all I could before incorporating it into our main repo. I utilized neo4j's starter project to learn as much as I could while building out what would be version 1 of our schema. grand-stack-starter

Now for the unanswered comment, "...standard ID system is unusable." - Myself. The system works like this: Create new node, it gets assigned ID of 1. Create second node, gets ID of 2. Delete node where ID = 1. Cool it's gone, create a third node...gets ID of 1.

It does this due to the way it stores the database. The indexing isn't the best, but hey...they included a handy command to create a nice uuid (randomUUID()) at least? Another reason why you shouldn't use the neo4j <ID> field is due to the fact that the number can shift around when they update Neo4j.

Short wrap up

We went over very quickly that the GRANDstack can be very powerful, especially if you are down to learn cypher and how Neo4j operates. The drive to learn will help you out a lot when learning this stack due to the small community around it. If you are interested at all in using the GRANDstack I recommend you start with just learning how to use Neo4j and Cypher because it will give you a strong starting point. I wish I would have learned more about Neo4j and Cypher before diving into GRAND, but you know, deadlines.

Thank you! 🙏

tldr: When used properly GRAND is pretty sweet, but once you go off track it becomes a pain.

Let me know if I should continue this series or take it another direction.