How to write GraphQL queries for the gatsby-source-craft plugin
A guide on writing queries for a Gatsby project that uses the Craft CMS gatsby-source-craft plugin.
These queries apply to the gatsby-algolia-plugin, if combined with the gatsby-source-craft plugin.
Shout out to Brian J Hanson and the good people at Craft for writing the plugin and taking the time to help me figure this out.
Step One: Open the GraphiQL
In Terminal, run gatsby develop in the current directory of your project.
Once it loads, open the GraphiQL found at the __graphql extension (i.e. localhost:8000/__graphql).
Step Two: Open the Documentation
Click the book on the top left to open the documentation.
To access specific documentation, click the part of the query that you're interested in and it will open the relevant documentation.
Step Three: Write the queries
Using the information provided below and the GraphiQL, code your query and run it to verify that it works.
If you require more information on fetching content, please consult the fetching content section of the gatsby-source-craft GitHub repository linked below.
Please note that our type prefix is CraftAPI_.
How do I list all the entries?
To list all entries use a query similar to that below:
If you wish to gather entry specific data for all entries, it will look similar to that below:
How do I load all the entries from a section ?
You can write a query that targets that specific section by converting the convention Craft_SectionHandle_TypeHandle_Entry to allCraftSectionHandleTypeHandleEntry (i.e. Craft_blog_blog_Entry becomes allCraftBlogBlogEntry, or if your typePrefix is Foo_ Foo_blog_blog_Entry becomes allFooBlogBlogEntry).
How do I find an entry that targets a specific id ?
gatsby-source-craft uses remoteId as the parameter to filter by Id. To filter for a specific id write a query similar to the one below:
How do I write queries that filter to one or many things ?
Below is a sample query that filters all the entries for just the projects.
The query shown below filters all entries for projects and our about page.
If you want to write a secondary filter, you can write it as follows:
How do I sort by descending or descending ?
To sort by ascending or descending, use a query similar to the one below (ASC for ascending, DESC for descending).
How to I use limit and offset ?
To paginate results, use queries similar to that below (offset becomes skip):
How do I use variables and query arguments?
The same way as in a normal GraphQL query, though do not where and how you use arguments is different.
Specific Requirements for Algolia
In order for partial updates to work with Algolia, you must include the contentdigest in your query.
If you do not include it you will get an error similar to "the objects must have internal.contentdigest".
A sample query with the content digest included looks as follows: