writeQuery, writeFragment, or modify?

[bstro]

I am unclear if this is an issue with documentation or my own understanding. With the existing documentation, its a bit fuzzy to me why I would choose one of these methods over the other—in one example in the Mutation docs, a writeFragment operation is even nested within a call to modify, unclear to me why.

I am further confused by this example from the docs:

When the ADD_TODO mutation is run in the above example, the newly added and returned todo object is saved into the cache. The previously cached list of todos, being watched by the GET_TODOS query, is not automatically updated however. This means the GET_TODOS query isn't notified that a new todo was added, which then means the query will not update to show the new todo. To address this we're using cache.modify which gives us a way to surgically insert or delete items from the cache, by running modifier functions.

— but then under the documentation for writeQuery and writeFragment, the docs state that All subscribers to the Apollo Client cache (including all active queries) see this change and update your application's UI accordingly..

So it is ultimately unclear to me how to get my queries to refresh when they depend on data from the cache, the docs seem contradictory, and unclear when I would use one over the other, and which ones will trigger a rerender from queries that watch the affected fields.

[jcreighton]

@bstro I agree that section isn't as clear as it could be. I'll try to provide some more clarity.

When the ADD_TODO mutation is run in the above example, the newly added and returned todo object is saved into the cache. The previously cached list of todos, being watched by the GET_TODOS query, is not automatically updated however.

What's being referred to here is the ADD_TODO mutation - not including the update function and subsequent cache.writeFragment in cache.modify, so just this portion right here:

const [addTodo] = useMutation(ADD_TODO);

Mutations that create or delete entities do not update the cache automatically. This is also true of mutations that deal with multiple entries. So, the above mutation will not add the newly created Todo to the cache. To do that, we need to use the update function:

const [addTodo] = useMutation(ADD_TODO, {
  update: (cache, mutationResult) => {
    // Here we can update the cache
  }
});

Any changes you make to cached data inside of an update function are automatically broadcast to queries that are listening for changes to that data.

How you make those changes is up to you, depending on what you want to accomplish. Here's a good breakdown of how cache.modify differs from writeQuery and writeFragment.

I'd also take a look at this comment for why cache.modify is useful and why writeFragment is nested inside the call to modify.

I hope this helps!

[bstro]

Really appreciate it, @jcreighton — This helps!

[jcreighton]

Happy to help!