Persisted queries in Apollo Kotlin

Automatic persisted queries

Apollo Kotlin supports Automatic Persisted Queries (APQ). To take advantage of it, your GraphQL server also needs to support APQ (Apollo Server supports it out of the box).

Enable the feature when you initialize your ApolloClient instance, like so:

1
val apolloClient = ApolloClient.Builder()
2
  .serverUrl("https://...")
3
  .autoPersistedQueries()
4
  .build()

You can optionally configure the HTTP methods to use. Using GET may take advantage of HTTP caching for instance when using a CDN:

1
val apolloClient = ApolloClient.Builder()
2
    .serverUrl("https://...")
3
    .autoPersistedQueries(
4
        // For the initial hashed query that does not send the actual Graphql document
5
        httpMethodForHashedQueries = HttpMethod.Get,
6
        
7
        // For the follow-up query that sends the full document if the initial hashed query was not found
8
        httpMethodForDocumentQueries = HttpMethod.Get
9
    )
10
    .build()

Note that mutations will always be sent as POST requests, regardless of these settings, as to avoid hitting caches.

Disable persisted queries for certain queries

You may want to disable persisted queries for certain queries, for instance to avoid any caching when the data is updated often. In order to do that, set enableAutoPersistedQueries to false on the ApolloCall:

1
apolloClient.query(myQuery).enableAutoPersistedQueries(false).toFlow()

operationOutput.json

If your backend uses custom persisted queries, Apollo Kotlin can generate an OperationOutput json from your .graphql queries. They will match what the client is sending exactly so you can persist them on your server.

1
apollo {
2
  service("service") {
3
    generateOperationOutput.set(true)
4
  }
5
}

Custom ID for Persisted Queries

By default, Apollo uses Sha256 hashing algorithm to generate an ID for the query. To provide custom ID generation logic, use the option - operationIdGenerator which accepts an instance that implements the OperationIdGenerator interface (com.apollographql.apollo3.compiler.OperationIdGenerator) as the input. This option can be used to either specify a different hashing algorithm or to fetch the persisted query ID from a different place - e.g. a service or a CLI.

Example Md5 hash generator:

1
apollo {
2
  service("service") {
3
    operationIdGenerator.set(object : com.apollographql.apollo3.compiler.OperationIdGenerator {
4
      override val version = "my-md5-version1"
5

6
      override fun apply(operationDocument: String, operationName: String): String {
7
        return operationDocument.md5()
8
      }
9
    })
10
  }
11
}

1
import com.apollographql.apollo3.compiler.OperationIdGenerator
2

3
apollo {
4
  service("service") {
5
    operationIdGenerator = new OperationIdGenerator() {
6
      String apply(String operationDocument, String operationName) {
7
        return operationDocument.md5()
8
      }
9

10
      /**
11
       * Use this version override to indicate an update to the implementation.
12
       * This forces gradle to recompile models.
13
       */
14
      String version = "my-md5-v1"
15
    }
16
  }
17
}

Versioning Id Generator

The result of the ID generator is cached. The cache is not updated when the implementation of the ID Generator changes. To indicate an update to the implementation of the ID Generator, change the version override as shown in the above example.

HTTP cache

Troubleshooting