Persisted GraphQL queries persisted-graphql-queries

Persisted queries are GraphQL queries that are created and stored on the Adobe Experience Manager (AEM) as a Cloud Service server. They can be requested with a GET request by client applications. The response of a GET request can be cached at the dispatcher and CDN layers, ultimately improving the performance of the requesting client application. This differs from standard GraphQL queries, which are executed using POST requests where the response cannot easily be cached.

The GraphiQL IDE is available in AEM for you to develop, test, and persist your GraphQL queries, before transferring to your production environment. For cases that need customization (for example, when customizing the cache) you can use the API; see the cURL example provided in How to persist a GraphQL query.

Persisted Queries and Endpoints persisted-queries-and-endpoints

Persisted queries must always use the endpoint related to the appropriate Sites configuration; so they can use either, or both:

For example, if there is a particular query called my-query, which uses a model my-model from the Sites configuration my-conf:

How to persist a GraphQL query how-to-persist-query

It is recommended to persist queries on an AEM author environment initially and then transfer the query to your production AEM publish environment, for use by applications.

There are various methods of persisting queries, including:

The GraphiQL IDE is the preferred method for persisting queries. To persist a given query using the cURL command line tool:

How to execute a Persisted query execute-persisted-query

To execute a Persisted query, a client application makes a GET request using the following syntax:

GET <AEM_HOST>/graphql/execute.json/<PERSISTENT_PATH>

Where PERSISTENT_PATH is a shortened path to where the Persisted query is saved.

Using query variables query-variables

Query variables can be used with Persisted Queries. The query variables are appended to the request prefixed with a semicolon (;) using the variable name and value. Multiple variables are separated by semicolons.

The pattern looks like the following:

<AEM_HOST>/graphql/execute.json/<PERSISTENT_QUERY_PATH>;variable1=value1;variable2=value2

For example, the following query contains a variable activity to filter a list based on an activity value:

query getAdventuresByActivity($activity: String!) {
      adventureList (filter: {
        adventureActivity: {
          _expressions: [
            {
              value: $activity
            }
          ]
        }
      }){
        items {
          _path
        adventureTitle
        adventurePrice
        adventureTripLength
      }
    }
  }

This query can be persisted under a path wknd/adventures-by-activity. To call the Persisted query where activity=Camping the request would look like this:

<AEM_HOST>/graphql/execute.json/wknd/adventures-by-activity%3Bactivity%3DCamping

The UTF-8 encoding %3B is for ; and %3D is the encoding for =. The query variables and any special characters must be encoded properly for the Persisted query to execute.

Using query variables - Best Practices query-variables-best-practices

When using variables in your queries there are a few best practices that should be followed:

Caching your persisted queries caching-persisted-queries

Persisted queries are recommended as they can be cached at the Dispatcher and Content Delivery Network (CDN) layers, ultimately improving the performance of the requesting client application.

By default AEM will invalidate cache based on a Time To Live (TTL) definition. These TTLs can be defined by the following parameters. These parameters can be accessed by various means, with variations in the names according to the mechanism used:

Author instances author-instances

For author instances the default values are:

These:

Publish instances publish-instances

For publish instances the default values are:

These can be overwritten:

Managing HTTP Cache Headers in the GraphiQL IDE http-cache-headers-graphiql-ide

The GraphiQL IDE - see Saving Persisted Queries

Managing Cache at the Persisted Query Level cache-persisted-query-level

This involves posting the query to AEM using cURL in your command line interface.

For an example of the PUT (create) method:

curl -u admin:admin -X PUT \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'

For an example of the POST (update) method:

curl -u admin:admin -X POST \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'

The cache-control can be set at the creation time (PUT) or later on (for example, via a POST request for instance). The cache-control is optional when creating the persisted query, as AEM can provide the default value. See How to persist a GraphQL query, for an example of persisting a query using cURL.

Managing Cache with Cloud Manager variables cache-cloud-manager-variables

Cloud Manager Environment Variables can be defined with Cloud Manager to define the required values:

Managing Cache with an OSGi configuration cache-osgi-configration

To manage the cache globally, you can configure the OSGi settings for the Persisted Query Service Configuration.

The default OSGi configuration for publish instances:

Configuring the query response code configuring-query-response-code

By default the PersistedQueryServlet sends a 200 response when it executes a query, regardless of the actual result.

You can configure the OSGi settings for the Persisted Query Service Configuration to control whether more detailed status codes are returned by the /execute.json/persisted-query endpoint, when there is an error in the persisted query.

The field Respond with application/graphql-response+json (responseContentTypeGraphQLResponseJson) can be defined as required:

Encoding the query URL for use by an app encoding-query-url

For use by an application, any special characters used when constructing query variables (that is, semicolons (;), equal sign (=), slashes /) must be converted to use the corresponding UTF-8 encoding.

For example:

curl -X GET \ "https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/adventure-by-path%3BadventurePath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fadventures%2Fbali-surf-camp%2Fbali-surf-camp"

The URL can be broken down into the following parts:

In plain text the request URI looks like the following:

/graphql/execute.json/wknd/adventure-by-path;adventurePath=/content/dam/wknd/en/adventures/bali-surf-camp/bali-surf-camp

To use a persisted query in a client app, the AEM headless client SDK should be used for JavaScript, Java, or NodeJS. The Headless Client SDK will automatically encode any query variables appropriately in the request.

Transferring a persisted query to your Production environment transfer-persisted-query-production

Persisted queries should always be created on an AEM Author service and then published (replicated) to an AEM Publish service. Often, Persisted queries are created and tested on lower environments like local or Development environments. It is then necessary to promote Persisted queries to higher level environments, ultimately making them available on a production AEM Publish environment for client applications to consume.

Package Persisted queries

Persisted queries can be built into AEM Packages. AEM Packages can then be downloaded and installed on different environments. AEM Packages can also be replicated from an AEM Author environment to AEM Publish environments.

To create a Package:

After the package has been built you can: