Make cache easier to work with

[atrauzzi]

Use case

Great library, love it, does almost everything I need. ⭐ 💪 🚀

There's just one problem.... The cache is insanely arcane to work with. Simple things like removing an entry or replacing it is poorly documented and has a very verbose API behind it.

Describe the solution you'd like

I feel like it should be easier to:

• Figure out the correct cache key(s) of an entry
• Call the API to update or remove that entry
• Maybe also update that entry based on other queries being done?

Anyway, just looking for a bit of quality of life -- but I gotta say, otherwise, such a neat library to use.

[martinbonnin]

Hi 👋 Thanks for the kind words and suggestions.

The easiest way to update the cache as of today is by reading/writing queries with ApolloStore.readOperation() and ApolloStore.writeOperation(). This is because the cache key depend on the field names and arguments, possibly involving variables and only the operation contains that information.

Another lower level API is using NormalizedCache.readRecord() and NormalizedCache.loadRecord() but this one is type unsafe and also doesn't broadcast modification so the details are voluntarily low because it's very easy to get wrong.

Can you elaborate what you mean by 'entry'? Are you trying to work with the low-level Record? If you can share a snippet of how you'd like the API to look like, that'd help investigating different solution.

[atrauzzi]

Thanks 🙂 , I'll definitely try! It's been a tricky one for me to nail down a clear understanding of what I don't know ™️.

So here's my ViewModel, which I think gives the general gist of how things are structured for me at the moment.

@HiltViewModel
@OptIn(ExperimentalCoroutinesApi::class)
class EditGeneralSettingsViewModel @Inject constructor(
    private val appSettings: DataStore<Settings>,
    private val api: Api,
) : ViewModel() {

    public val settings = appSettings.data.flatMapConcat {
        api.client
            .query(SettingsForAdminQuery(
                UUID.fromString(it.currentOrganizationId),
                SupportedSettingPurpose.General.value,
            ))
            .watch()
    }

    public suspend fun saveParameters(iso639Code: String?, slot: String, parameters: ParameterInput?) {

        val organizationId = appSettings.data.first().currentOrganizationId
            ?: throw Exception("No current organization.")

        if (parameters == null) {

            val clearSettingsResult = api.client
                .mutation(ClearSettingMutation(
                    if (iso639Code.isNullOrEmpty()) Optional.absent() else Optional.present(iso639Code),
                    UUID.fromString(organizationId),
                    SupportedSettingPurpose.General.value,
                    slot,
                ))
                .execute()
        }
        else {

            val settingSaveResult = api.client
                .mutation(SaveSettingMutation(
                    if (iso639Code.isNullOrEmpty()) Optional.absent() else Optional.present(iso639Code),
                    UUID.fromString(organizationId),
                    SupportedSettingPurpose.General.value,
                    slot,
                    parameters
                ))
                .execute()
        }
    }
}

I have my main query which is getting turned into a flow, presumably so that when I make updates to the data, at some point, it's going to re-emit and my UI will update. As I'm reading about the cache and looking at other issues, I'm getting a sense that this might not happen the way I'm thinking. But again, it's not explicit anywhere in the documentation, so I'm having to piece together the expected behaviour through indirect sources.

So now I'm trying to just make something work and I'm figuring I can either:

• Somehow trigger a re-fetch of my list, which means I either shouldn't use a flow, or I need to trick my UI into re-subscribing to it to re-trigger it
• Restructure my fetch to be a flow that I can assign to after manually re-fetching data within my saveParameters method, and then my UI will update

The second approach seems like the most conventional, but it's also completely ignoring the nice cache feature that apollo-kotlin has made available. I'd rather learn to make the fullest use of the tool rather than come up with my own approach. 🙏

A second issue if I were to interact with the cache is that I don't have an easy way to know what my cache keys will be. It's not immediately apparent just what exactly I'm clearing. Is it keyed per record? Per query? Is it going to use the id field automatically, or something else? I just don't have a clear explanation of how it behaves for me to know what kind of manipulation would be appropriate after I call my mutations.

Would love any guidance that can be offered, and for the purposes of this github ticket, I think the docs would do well to suggest some patterns on this front to try and help people make better use of the library. Perhaps inspired by what you can tell me here? I'm happy to re-summarize where my misunderstandings were once I can interpret them better 😅

[martinbonnin]

Thanks for the detailed context 🙏 ! I think you got the fetch part right:

    public val settings = appSettings.data.flatMapConcat {
        api.client
            .query(SettingsForAdminQuery(
                UUID.fromString(it.currentOrganizationId),
                SupportedSettingPurpose.General.value,
            ))
            .watch()
    }

Using watch() will make sure your Flow emits new values when the cache changes and UI stays up to date 👍 .

Now the problem is how to make sure your mutation updates your cache correctly. For this I definitely agree we could give more guidance as it's not always easy. If you haven't already, I recommend you read this blog article about cache normalization that explains how ids work.

Then, there are basically 2 solutions to this problem:

1. your mutation returns the modified data: this is the easiest case. Just make sure to query in your mutation all the fields that have changed and the cache will be updated automatically and your watcher notified.
2. update the cache programmatically: the easiest way to do this would be do construct a SettingsForAdminQuery.Data instance programmatically and save it to the cache with ApolloStore.writeOperation(query, data, ...)

In both cases, you might have to configure your cache ids either programmatically or declaratively (doc)

Another option which is not using the normalized cache but I thought I mention it too as it could be an acceptable tradeoff is to force a refetch of your settings query. This is an in-between solution in that it's realtively easy to setup but requires a network round trip so it's a bit less optimal. But if you just made a mutation, maybe that's OK because your user probably has network connectivity.

The gist of it would be something like so:

    val channel = Channel<Unit>()

    val settings = channel.consumeAsFlow().onStart { emit(Unit) }.flatMapLatest {
        api.client
            .query(SettingsForAdminQuery(
                UUID.fromString(it.currentOrganizationId),
                SupportedSettingPurpose.General.value,
            ))
            .fetchPolicy(NetworkOnly)
            .toFlow()
    }

    public suspend fun saveParameters(iso639Code: String?, slot: String, parameters: ParameterInput?) {
        val mutationResult = api.client.mutation(...).execute()
        
        // Trigger a refetch
        channel.send(Unit)
    }

Depending how you want to refetch and/or allow stale data, there are variations of this but this is the general idea.

In all cases, agree more docs would be welcome.

[atrauzzi]

Very interesting! Okay, couple more followups for the ugly details...

• For my clear mutation, is there some way for me to blank the record automatically as a result of the operation?

  • If not, is that where I have to use .remove(...)?
    • If so, is there any convention for easily inferring what the correct CacheKey is, or can I rely on some metadata in the generated code to construct it? What should that look like?

• For api.client.apolloStore.writeOperation(), what's the convention there?

  • I see operation: Operation<D> and operationData: D, but are those things I build myself, or reference from the completed mutation?
  • What operation/query am I putting in there? Does it matter that the query I'm using doesn't query by ID?
  • Does it matter that the query fetches a list rather than a single record?

Looking specifically at this block, you can see two places where I'm still foggy on how to make use of the cache.

        if (parameters == null) {

            val clearSettingsResult = api.client
                .mutation(ClearSettingMutation(
                    if (iso639Code.isNullOrEmpty()) Optional.absent() else Optional.present(iso639Code),
                    UUID.fromString(organizationId),
                    SupportedSettingPurpose.General.value,
                    slot,
                ))
                .execute()

              api.client.apolloStore.remove(/* What do I put here? */)
        }
        else {

            val settingSaveResult = api.client
                .mutation(SaveSettingMutation(
                    if (iso639Code.isNullOrEmpty()) Optional.absent() else Optional.present(iso639Code),
                    UUID.fromString(organizationId),
                    SupportedSettingPurpose.General.value,
                    slot,
                    parameters
                ))
                .execute()

            val setting = settingSaveResult.data?.saveSetting?.setting
                ?: throw Exception("Setting was not saved.")

            api.client.apolloStore.writeOperation(/* What do I put here? */) // Keep in mind, I have no idea what the mechanism is looking for, so I don't know what's appropriate to put here.
        }

Finally, my mutation does return a settings object, but it doesn't appear to be auto-updating in the cache, so I'm wondering why that mechanism isn't triggering?

[martinbonnin]

Answers inline

• For my clear mutation, is there some way for me to blank the record automatically as a result of the operation?

The cache is usually additive only. What you really want is remove any reference to your settings object. If your query is like so:

query SettingsForAdminQuery {
  admin {
    settings {
      key1
      key2
    }
  }
}

The cache will look like so:

QUERY_ROOT.admin: { "settings": CacheKey("QUERY_ROOT.admin.settings") }
QUERY_ROOT.admin.settings: { "key1": "value1", "key2", "value2" }

• If so, is there any convention for easily inferring what the correct CacheKey is, or can I rely on some metadata in the generated code to construct it? What should that look like?

The cache key is the path to the field by default (it doesn't have to be this way, more on that later).

You can dump the cache to see what the cache key look like. See here for more details.

• For api.client.apolloStore.writeOperation(), what's the convention there?
• I see operation: Operation<D> and operationData: D, but are those things I build myself, or reference from the completed mutation?

Things you build yourself, possibly using the results of the mutation if you can't build them locally.

Looking specifically at this block, you can see two places where I'm still foggy on how to make use of the cache.

You can use writeOperation in both cases. Something like so:

val mutationResult = ...
apolloStore.writeOperation(
            SettingsForAdminQuery(
                UUID.fromString(it.currentOrganizationId),
                SupportedSettingPurpose.General.value,
            ),
            SettingsForAdminQuery.Data(
                admin = SettingsForAdminQuery.Admin(
                        // map to settings here
                        settings = mutationResult.toSetting()
                    )
                )
            )
        )

This will overwrite the data from your previous query and therefore trigger the watcher.

You have to do this dance because by default the cache is using the field path as ids and this doesn't allow de-duplicating the data.

Finally, my mutation does return a settings object, but it doesn't appear to be auto-updating in the cache, so I'm wondering why that mechanism isn't triggering?

You'll have to define explicit ids for your setting object even though it doesn't seem to have one defined by the backend.

If your settings object is a singleton, it can be as easy as using the typename for your object:

val cacheKeyGenerator = object : CacheKeyGenerator {
  override fun cacheKeyForObject(obj: Map<String, Any?>, context: CacheKeyGeneratorContext): CacheKey? {
    if (obj["__typename"] == "Settings") {
      return CacheKey("Settings")    
    }
    return null
  }

hope this helps!

[atrauzzi]

Hey @martinbonnin -- Just circling back to this after a bit. I've decided to take a stab at updating the cache and seeing how that works out.

All my toplevel objects that come back from my API have a GUID identifier under the field id. Will Apollo pick up on that by convention and default to it for cache keys, or do I still need to write a CacheKeyGenerator?

If my query returns a list of results, how do I correctly update a single record that might be in that list within the cache?

[martinbonnin]

Woops, sorry that fell through.

All my toplevel objects that come back from my API have a GUID identifier under the field id. Will Apollo pick up on that by convention and default to it for cache keys, or do I still need to write a CacheKeyGenerator?

You'll need a CacheKeyGenerator, Apollo Kotlin uses the field path as default cache key, not id

If my query returns a list of results, how do I correctly update a single record that might be in that list within the cache?

Do you mean programmatically? If yes then you need to update all the list:

val data = Data(items)

val newData = data.copy(items = data.items.map { 
   if (it.id == idToModify) {
     modifyItem()
   } else {
     it
   }
}

apolloStore.writeOperation(operation, newData)

Alternatively, you can define a fragment and use generateFragmentImplementations/writeFragment if your item is deeply nested, to avoid writing all the other operation data.

Hope this helps

[atrauzzi]

Oof. I guess the title of this ticket is really starting to shine now, haha.