In this guide, you’ll be learning to use something called GraphiQL, a tool that helps you structure GraphQL queries correctly. You can learn more about it in the GraphiQL README.
GraphiQL is the GraphQL integrated development environment (IDE). It’s a powerful (and all-around awesome) tool you’ll use often while building Gatsby websites. It offers syntax highlighting, intellisense autocompletion, automatic documentation, and much more.
Use GraphiQL to interactively build your page and static queries.
When the development server is running for one of your Gatsby sites, open GraphiQL at
http://localhost:8000/___graphql to see the interface:
The UI is divided into three pieces:
- The left sidebar has buttons to open plugin panes and change settings
- The left side is where you write your queries
- The right side is where the results of your queries will be displayed
The left sidebar has a top and bottom section. The top has buttons for the documentation explorer, history, query explorer, and query exporter. The bottom sidebar buttons allow you to refetch the schema, see the keyboard shortcuts, and change settings.
In the middle section, below the welcome comment, begin typing:
Now inside the curly braces press Ctrl + Space (or use Shift + Space as an alternate keyboard shortcut) to bring up the autocomplete window. Build out a query like this:
You can now press the “Execute” button (looks like a “Play” button) or press Ctrl + Enter to run the GraphQL query.
Make sure to check out the GraphiQL docs in the upper left-hand corner of the IDE. It’s easy to miss them, but they’re worth visiting!
In the video below watch a person use GraphiQL to build out a query, both with autocompletation in the query editor and with the GraphQL explorer plugin in the sidebar. The GraphQL exporter plugin is also used to automatically create a static query.
The environment variable
ENABLE_GATSBY_REFRESH_ENDPOINT enables a “Refresh Data” button which allows you to refresh the sourced content. See Refreshing Content.