ApolloStore

Apollo Kotlin exposes the ApolloStore API to read and write from the normalized cache programmatically. The ApolloStore sits on top of NormalizedCache, exposes a thread safe API as well as methods that make it easier to read and write fragments and operations.

The store is accessible with the ApolloClient.apolloStore extension:

1
val apolloClient = ApolloClient.Builder()
2
  .serverUrl("https://example.com/graphql")
3
  .normalizedCache(MemoryCacheFactory(maxSizeBytes = 10 * 1024 * 1024))
4
  .build()
5

6
val apolloStore: ApolloStore = apolloClient.apolloStore

Reading operation data

Just like a regular GraphQL query, the main way to use the store is to read and write queries:

Given the following query:

1
query GetBook($id: String!) {
2
  book(id: $id) {
3
    title
4
    author {
5
      name
6
    }
7
  }
8
}

You can read it like this:

1
val data = apolloClient.apolloStore.readOperation(GetBookQuery(id = "42"), apolloClient.customScalarAdapters)
2

3
println("Title=${data.title}")
4
println("Author Name=${data.author.name}")

In the event of cache miss, readOperation will throw:

1
try {
2
  apolloClient.apolloStore.readOperation(GetBookQuery(id = "42"), apolloClient.customScalarAdapters)
3
} catch(e: CacheMissException) {
4
  println("CacheMiss on key: ${e.key}.${e.fieldName}")
5
}

If you declared scalar adapters at runtime, pass your client's customScalarAdapters to the store's methods, as the store will need them to convert scalar values to and from their Kotlin/Java types.

Writing operation data

Writing operation data is similar to reading:

1
apolloClient.apolloStore.writeOperation(GetBookQuery(id = "42"), data, apolloClient.customScalarAdapters)

Note how you'll need to pass the data allong the operation.

Reading and Writing fragments

In the GraphQL specification, fragments are always part of a larger operation and cannot be executed standalone.

1
fragment BookDetails on Book {
2
  id
3
  title
4
  author {
5
    name
6
  }
7
}

Apollo Kotlin makes an exception to that rule and allows to read/write individual fragments. This is disabled by default and can be enabled with generateFragmentImplementations:

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

Because fragments are not rooted, you need to specify the root cache id of the fragment:

1
val data = apolloClient.apolloStore.readFragment(BookDetailsImpl(), CacheKey("42"), apolloClient.customScalarAdapters)
2

3
println("Title=${data.title}")
4
println("Author Name=${data.author.name}")

Fragments can contain variables. Different fragments with different variables can return different data. In that case the fragment Impl class will require variables as constructor parameters:

1
fragment BookDetails on Book {
2
  id
3
  title(locale: $locale)
4
}

1
val data = apolloClient.apolloStore.readFragment(BookDetailsImpl(locale = "en-US"), CacheKey("42"), apolloClient.customScalarAdapters)
2

3
println("Title=${data.title}")

Clearing the cache

Call apolloClient.apolloStore.clearAll() to clear the cache of all entries.

Watching cached data

HTTP cache