$ less ~/blog/drupal-graphql-cheatsheet.txt
-rw-r--r-- guille Feb 11 2021 drupal-graphql-cheatsheet.txt
ARCHIVED · written in 2021. Kept as it was; some of it may be out of date.
Drupal + GraphQL Cheatsheet
Here’s a cheat sheet to show you a couple of examples of GraphQL queries using version 8.x-3.x of Drupal’s GraphQL module. This list is not intended to be exhaustive, it’s just a sample of common queries that I’ve used in almost all decoupled sites that I’ve worked on.
Enough talking, show me the code! ?
Get a single node by its nid
Suppose that we have a node with id 1. To query the basic information about that node, we can use the query below.
query myQuery {
nodeById(id: "1") {
entityId
title
status
}
}
Only fields that belong to all entities and nodes can be fetched using this query. Keep in mind that entityId belongs to all entities (a node is an entity), and title and status are fields of all nodes, regardless of their bundle.
Get a single node of a specific content type by its nid
If we want to retrieve fields that belong only to a specific content type we have to use the fragment associated with that content type. For example, suppose that we have the Article content type, and it has the field_kicker field, so in order to get the value of the field_kicker, wrap the fieldKicker field inside the NodeArticle fragment.
query myQuery {
nodeById(id: "1") {
entityId
title
status
... on NodeArticle {
fieldKicker
}
}
}
Remember that fields and properties are in camelCase, so field_kicker becomes fieldKicker. On the other hand, the nodes’ fragments name has the form Node + Content Type name, so the fragment for the content type Article is NodeArticle.
Querying a list of nodes
Imagine that our content type Article has the field field_section that indicates the section the article belongs to. For the sake of simplicity, suppose that sections are stored as strings. So, to get the 10 latest articles of Sports section, we can use the next query.
query myQuery {
nodeQuery(
filter: {
conditions: [
{ field: "type", value: "article" },
{ field: "status", value: "1" },
{ field: "field_section", value: "sports" },
]
},
sort: { field: "created", direction: DESC },
limit: 10,
) {
entities {
entityId
entityLabel
}
}
}
If you want to filter by an entity reference, use the referenced entity id in the “value” field.
Querying taxonomy terms
To get a taxonomy terms list of a specific vocabulary, for example, the “tags” vocabulary, use a query like the one below.
query myQuery {
taxonomyTermQuery(
filter: {
conditions: [
{ field: "vid", value: "tags" },
{ field: "status", value: "1" },
],
},
) {
entities {
entityId
entityLabel
}
}
}
Using aliases
We can rename the result of a field to anything we want.
query myQuery {
nodeById(id: "1") {
id: entityId
title
... on NodeArticle {
section: fieldSection
}
}
}
And we’ll get the result
{
"data": {
"nodeById": {
"id": "1",
"title": "My awesome article!",
"section": "sports"
}
}
}
Sometimes is necessary to use aliases, for example when we want to make the same query in a single request.
query myQuery {
tags: taxonomyTermQuery(
filter: { conditions: [{ field: "vid", value: "tags" }] },
) {
entities {
entityLabel
}
}
topics: taxonomyTermQuery(
filter: { conditions: [{ field: "vid", value: "topics" }] },
) {
entities {
entityLabel
}
}
}
In the example above we are querying tags and topics using taxonomyTermQuery in both cases, so in order to differentiate the results, we are forced to use aliases.
Using fragments
There are times when we want to reuse the same query in many places. For example, suppose that our articles have a field field_tags that reference taxonomy terms of vocabulary Tags, and in another part of our site we show a list of those tags in the same way that we do in the articles, I mean, using the same fields. In these kinds of cases, fragments are useful to avoid code duplication.
query myQuery {
article: nodeById(id: "1") {
id: entityId
title
... on NodeArticle {
fieldTags {
entity {
...Tag
}
}
}
}
tags: taxonomyTermQuery(
filter: { conditions: [{ field: "vid", value: "tags" }] },
) {
entities {
...Tag
}
}
}
fragment Tag on TaxonomyTermTags {
id: entityId
name: entityLabel
}
Querying referenced paragraphs
A very common use case for paragraphs is when a content type has a field that can reference multiple types of paragraphs. For example, the content type Page can have a field_sections field that references paragraphs of type tag_section for showing the latest tags, and a paragraph of type articles_section for the latest articles. We are not limited to show only one type of paragraph per field, to query all the values for the field_section we just need to list the supported fragments for that field. It’ll be clear with an example.
query myQuery {
page: nodeById(id: "2") {
title
... on NodePage {
fieldSections {
entity {
...TagSection
...ArticlesSection
}
}
}
}
}
fragment TagSection on ParagraphTagSection {
# The required fields
}
fragment ArticlesSection on ParagraphTagSection {
# The required fields
}
The use of fragments in the query above is not necessary but makes the code more readable. Note that even though the first listed fragment is the TagSection, this doesn’t mean that the section to appear first will be the TagSection, the order saved in the CMS is preserved.
Querying image with Image Styles
Suppose that we have an image style square_max_800_px as machine name, in GraphQL the image style name is transformed to SQUAREMAX800PX. Note how the underscores are dropped and the image style’s machine name is capitalized.
query myQuery {
nodeById(id: "1") {
title
fieldImage {
url
alt
title
squareStyle: derivative(style: SQUAREMAX800PX) {
url
width
height
}
}
}
}
We can fetch more than one image style per single query using aliases.
query myQuery {
nodeById(id: "1") {
title
fieldImage {
url
alt
title
squareStyle: derivative(style: SQUAREMAX800PX) {
url
width
height
}
wideStyle: derivative(style: WIDEMAX800PX) {
url
width
height
}
}
}
}
Format dates
GraphQL supports some data transformations out of the box, for example, to format dates.
query myQuery {
nodeById(id: "1") {
title
created: entityCreated(format: "d/m/yy")
}
}
The available formats are those supported by the date function in PHP.