Creating a persisted query

A persisted query is a combination of GraphQL and REST APIs: it is a normal GraphQL query, published on the site and accessed under its own URL, similar to a REST endpoint.

For instance, we can expose data for a website through the following persisted queries:

  • /graphql-query/homepage-posts
  • /graphql-query/user-widget
  • /graphql-query/post-content and execute it passing the ID of the post: ?post=1
  • /graphql-query/post-content/es to translate the content of the post to Spanish
  • Others

Accessing all persisted queries

Clicking on "Persisted Queries" on the plugin's menu, it displays the list of all the created persisted queries:

Persisted Queries in the admin
Persisted Queries in the admin

Creating a new persisted query

Click on button "Add New GraphQL persisted query" to open the WordPress editor:

Creating a persisted query
Creating a persisted query

Give it a title and make sure the permalink is the expected one, input the GraphQL query, select the schema configuration, and adjust the options. When ready, click on the Publish button, and the permalink becomes the persisted query's endpoint:

Publishing the persisted query
Publishing the persisted query

Query editor

The GraphiQL client in the editor is where to input the GraphQL persisted query:

The persisted query's GraphiQL client
The persisted query's GraphiQL client

The editor comes with the Explorer add-on, which allows to compose the query by clicking on the fields on the left side panel. Clicking on the "Run" button executes the query, to preview the response:

Composing a persisted query with the Explorer
Composing a persisted query with the Explorer

Schema configuration

Defining who can access the fields requested in the persisted query is defined in the schema configuration.

So we must create a create a schema configuration, and then select it from the dropdown (or use none, or the default one):

Selecting the schema configuration
Selecting the schema configuration

Making the persisted query dynamic via URL params

If the query makes use of variables, and option "Accept variables as URL params?" is enabled, then the values of the variables can be set via URL param when executing the persisted query.

For instance, in this query, the number of results is controlled via variable $limit, with a default value of 3:

Using variables in persisted query
Using variables in persisted query

When executing this persisted query, passing ?limit=5 will execute the query returning 5 results instead:

Overriding value for variables in persisted query
Overriding value for variables in persisted query

Creating a persisted query hierarchy

Please read the instructions on creating an API hierarchy.

Disabling the persisted query

In the options, set "Enabled" to false to disable the persisted query.

This feature can be useful when making the persisted query be part of an API hierarchy, to provide a common behavior to its child persisted queries, but without needing itself be executed.

Describing the persisted query

Use the "Excerpt" field, from the Document settings panel, to give a description to the persisted query.

Find more information in guide Adding a description to the API.

Executing the persisted query

Once the persisted query is published, we can execute it via its permalink.

The persisted query can be executed directly in the browser, since it is accessed via GET, and we will obtain the requested data, in JSON format:

Executing a persisted in the browser
Executing a persisted in the browser

Executing the persisted query in an application

Please follow the instructions on guide Executing queries against the GraphQL server.

Viewing the source

Appending ?view=source to the endpoint, it will show the persisted query's configuration (as long as the user has access to it):

Persisted query's source
Persisted query's source

Configuration in the WordPress editor

These are the inputs in the body of the editor:

InputDescription
TitlePersisted query's title
GraphiQL clientEditor to write and execute the GraphQL query:
  • Write the query on the textarea
  • Declare variables inside the query, and declare their values on the variables input at the bottom
  • Click on the "Run" button to execute the query
  • Obtain the results on the input on the right side
  • Click on "Docs" to inspect the schema information
The Explorer (shown only if module GraphiQL Explorer is enabled) allows to click on the fields, and these are automatically added to the query
Schema configurationFrom the dropdown, select the schema configuration that applies to the persisted query, or one of these options:
  • "Default": the schema configuration is the one selected on the plugin's Settings
  • "None": the persisted query will be unconstrained
  • "Inherit from parent": Use the same schema configuration as the parent persisted query.
    This option is available when module API Hierarchy is enabled, and the persisted query has a parent query (selected on the Document settings)
OptionsCustomize the behavior of the persisted query:
  • Enabled?: If the persisted query is enabled.
    It's useful to disable a persisted query it's a parent query in an API hierarchy
  • Accept variables as URL params?: Allow URL params to override the values for variables defined in the GraphiQL client
  • Inherit query from ancestor(s)?: Use the same query as the parent persisted query.
    This option is available when module API Hierarchy is enabled, and the persisted query has a parent query (selected on the Document settings)

These are the inputs in the Document settings:

InputDescription
PermalinkThe endpoint under which the persisted query will be available
CategoriesCan categorize the persisted query.
Eg: mobile, app, etc
ExcerptProvide a description for the persisted query.
This input is available when module Excerpt as Description is enabled
Page attributesSelect a parent persisted query.
This input is available when module API Hierarchy is enabled