Gatsby & GraphQL: Nodes vs. Edges

Although strictly speaking this doesn't relate directly to Gatsby, it is a question that I am asked fairly frequently when it comes to developing with Gatsby. For many front‑end developers, using Gatsby will be the first time that they have been exposed to GraphQL queries.

So, what's the difference? Take this query for example:

query Shuttles {  allShuttles {    edges {      node {        name      }    }    nodes {      name    }  }}

At first glance, the result from this looks to be the same for both edges and nodes:

data: {  allShuttles: {    edges: [      {        node: {          name: 'Enterprise',        },      },      {        node: {          name: 'Columbia',        },      },      {        node: {          name: 'Challenger',        },      },    ],    nodes: [      {        name: 'Enterprise',      },      {        name: 'Columbia',      },      {        name: 'Challenger',      },    ],  },},

However, there are some subtle and key differences between the two.

Graph Theory

In order to explain the difference, you need to have a very gentle grasp of Graph Theory. In the quickest and simplest way I can manage: Graph Theory describes the idea that data can be modelled by connecting circles (nodes) of data, via lines that describe the relationship between nodes (edges). Therefore, our GraphQL data looks a little like a much more complex version of this diagram:

Each circle is a node, each line between them is an edge.

Nodes

In situations where you only need to access an item of data directly (without any additional data about its relationship with other nodes), then accessing them directly via node makes perfect sense: it is a shorter and more concise query, and it returns all the data you need.

Edges

On the other hand, edges also describe the relationship between those nodes. So, expanding on the original example above:

query Shuttles {  allShuttles {    edges {      node {        name      }      next {        name      }      previous {        name      }    }  }}

Results in:

data: {  allShuttles: {    edges: [      {        node: {          name: 'Enterprise',        },        next: {          name: 'Columbia',        },        previous: {          name: null,        },      },      {        node: {          name: 'Columbia',        },        next: {          name: 'Challenger',        },        previous: {          name: 'Enterprise',        },      },      {        node: {          name: 'Challenger',        },        next: {          name: null,        },        previous: {          name: 'Columbia',        },      },    ],  },},

What we now have is all the same data that we had previously when querying nodes directly but with the addition of knowing which shuttle (item of data) came before and after it.

Pagination in Gatsby Using Edges

Pagination in Gatsby itself is definitely something for another time and another article, but to give some brief context: in the case of developing within Gatsby, the most common use‑case for edge queries is going to be building up pagination between pieces of data. For example, blog articles.

I use this myself to determine what the 'next' article at the bottom of this very page should be. I also use it again to display the next project in the footer of each portfolio item. Using the edges structure, you can pass the next and previous nodes into pageContext from gatsby‑node.js, and then use that data as you need. Were you simply to query nodes directly, this relationship between preceding and proceeding nodes would not be available.

The Difference in a Nutshell

All of this is a lot of words (and excuses to post pictures of Space Shuttles) to say in a nutshell: the difference is that a node is a specific piece of data whereas edge allows you to access and use the relationship between that data and others as well.

Use a node query if you just want the data. Use an edge query if you want to know more about the data's relationship with other pieces of data in your schema.