Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough

Drupal Backender Learns Gatsby: Core JSON:API vs GraphQL 3

Parent Feed: 

In Gatsby you use GraphQL to query data from your backend, the source plugin you use will allow you to access data from your source API. The gatsby_source_drupal plugin pulls data from Drupal JSON:API so it’s queryable with GraphQL inside your Gatsby app, while gatsby_source_graphql is just a wrapper around any backend GraphQL schema. This means we get access to the schema in the GraphQL 3 module for Drupal instead of the one defined in the gatsby_source_drupal plugin.

Let's compare some common query examples from both of these methods.

The queries here are kept simple to focus on specific elements and context.

Lets get a list of 3 nodes of type Article for a link list. Make sure they are published and sorted by sticky and changed.

JSON:API allNodeArticle

Query


query {
  allNodeArticle(
    filter: {
      status: {
        eq: true
      }
    }
    sort: {
      fields: [sticky, changed]
      order: [DESC, DESC]
    }
    skip: 0
    limit: 3
  ) {
    edges {
      node {
        drupal_internal__nid
        title
        path {
          alias
        }
      }
    }
  }
}

Query


query {
  drupal {
    nodeQuery(
      filter: {
        conditions: [
          { field: "status", value: "1" }
          { field: "type", value: "article" }
        ]
      }
      sort: [
        { field: "sticky", direction: DESC }
        { field: "changed", direction: DESC }
      ]
      offset: 0
      limit: 3
    ) {
      entities {
        ... on Drupal_NodeArticle {
          nid
          title
          path {
            alias
          }
        }
      }
    }
  }
}

The main difference I see in the query is how the filter and sort parameters work. With gatsby_source_drupal we have a set of filters for fields defined on the entity type; id, langcode, status, title, etc.

With gatasby_source_graphql and the GrapqhQL module I'm able to use "conditions" the way I would with EntityQuery in Drupal, working in PHP. For instance, I could filter my list of nodes by taxonomy term by adding a condition for that field.


...
    nodeQuery(
      filter: {
        conditions: [
          { field: "status", value: "1" }
          { field: "type", value: "article" }
          { field: "field_tags.entity.name", value: "sailboat"}
        ]
      }
    }
...

I could do this in gatsby_source_drupal as well, but it looks like:


...
  allNodeArticle(
    filter: {
      status: {
        eq: true
      }
      relationships: {
        field_tags: {
          elemMatch: {
            name: {
              eq: "sailboat"
            }
          }
        }
      }
    }
...

It might just be because I come from the backend first that I find the nodeQuery way more intuitive. I like that you can customize the query with conditions, conjunctions and groups. https://drupal-graphql.gitbook.io/graphql/queries/filters

Sometimes I use the Drupal Paragraphs module to make flexible columns of text. In this very simple example I've named the paragraphs field field_components and there are 2 types of paragraphs:

  • Columns: has one field field_components, another paragraph reference field.
  • Text: has field_heading and field_text

On my Article content type I added a paragraphs field called "field_components" as well. I can create an article with a "Columns" paragraph and inside the "Columns" paragraph I can add "Text" paragraphs. The Columns paragraph becomes a wrapper and can be styled to cause the nested Text paragraphs to layout as columns.

In the query, I've aliased the paragraph fields to "column_wrapper" and "columns", so it's a little clearer than field_components in the data.

JSON:API nodeArticle

Query


query($id: Int!) {
  nodeArticle(drupal_internal__nid: { eq: $id }) {
    relationships {
      column_wrapper: field_components {
        ... on paragraph__columns {
          relationships {
            columns: field_components {
              ... on paragraph__text {
                field_heading {
                  processed
                }
                field_text {
                  processed
                }
              }
            }
          }
        }
      }
    }
  }
}

Query


query($id: String!) {
  drupal {
    nodeById (
      id: $id
    ) {
      ... on Drupal_NodeArticle {
        column_wrapper: fieldComponents {
          entity {
            ... on Drupal_ParagraphColumns {
              columns: fieldComponents {
                entity {
                  ... on Drupal_ParagraphText {
                    fieldHeading {
                      processed
                    }
                    fieldText {
                      processed
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

You can see some differences in the way the schema identifies the fields. One uses relationships and field_components while the other uses fieldComponents and entity

JSON:API: nodeArticle has arguments for all the node fields; langcode, status, created, etc. while the GraphQL nodeById has only id and langcode. But if you're not looking for a specific node id and want to filter on something else, use the more flexible nodeQuery.

In my previous post I talked about using Drupal to process and serve derivative images instead of having Gatsby process them all at build time, which can take a very long time as the number of posts/images grows.

I compared the two source queries for this as well, and I think the differences are significant in this case. You can review that post for the details but I'll briefly summarise.

The goal was to load a set of image styles from an image field. To do this with gatsby_source_drupaland the JSON:API requires an additional Drupal contrib module to expose the images styles. The GraphQL module just handles it with derivative(style: [name]) on the field. Which can be aliased to query all the styles you wish.


...
  fieldImage {
    small: derivative(style: small) {
      width
      url
    }
    medium: derivative(style: medium) {
      width
      url
    }
    ...

The resulting data from GraphQL was easier to process, while the structure of the data from the JSON:API version kind of didn't make sense and required some extra massaging.

In general the gatsby-source-drupal plugin gives us queries in the form of "entityBundle" or "allEntityBundle" like the following:

  • nodeArticle, allNodeArticle
  • paragraphColumns, allParagraphColumns
  • taxonomyTermTags, allTaxonomyTermTags

These take arguments mapped to the entity fields.

The GraphQL module instead provides us with entity queries on each entity type that we can use just like an EntityQuery in Drupal PHP, as well as entityById and entityRevsionById.

  • queryNode, nodeById, nodeRevisionById
  • queryUser, userById
  • blockContentQuery, blockContentById, blockContentRevisionById

So far I've been able to do the things I want with either solution, but I find myself favoring GraphQL module. I assume that's from my backend roots. Lucky for us the GraphQL Explorer makes it all pretty easy to explore. Please let me know in the comments if I've said anything preposterous, or if you have any additional insights. Thanks for reading!

"Code like nobody is watching... but then refactor. ;)"

Original Post: 

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web