Suggestion: clarify caching in docs

Hi there.

I have a use case where first I (in apollo client) grab a list of Documents from my server, using useQuery. Then, at different times, different components in my app query for a single Document (by id), again using useQuery. This single document is one of the list of Documents I grabbed earlier, and I confirmed that that document is in my cache using apollo dev tools.

The docs make it sound like Apollo client will use that cached Document out of the box, for example:

" For example, if a client requests a list of movies, each movie is cached separately on the client. Later, if the client requests a single movie in a different query and the needed movie is in the cache, the request doesn’t have to use the network. This normalized cache is a part of apollo-client by default."
Similarly under ‘Caching->Overview’ it is stated “…And each later time your app queries for that same object, the flow looks like this instead:”. This is definitely misleading/wrong.

However, as my experience showed, this was not the case - a network request was sent to my server for each of the subsequent useQuery calls, even though 100% of the data they needed was in my cache under the expected keys, ie Document:1000 etc. I was really confused at this, and had to do some research to find some stack overflow questions discussing this.

Could I suggest that the team

  1. Remove suggestions that caching like that described above works out of the box - it doesn’t.
  2. Surface the information currently buried at the very bottom of advanced topics (under the heading ‘Cache redirects using field policy read functions’) at a more relevant part of the docs, for example at an early part of the caching section. It should be made much clearer, that cached values will only be used out of the box for identical queries.

I got the information I needed after much searching, I hope this suggestion can lead to improved docs to save the time of some others in future.

1 Like

Thanks for the feedback @Xavier_Taylor - we’ll think about ways to make this more evident (cc @StephenBarlow).

1 Like

Thank you for considering the feedback. And thanks to the team for making apollo available. I am loving using it.

1 Like