Documentation on cache-and-network fetchPolicy is unclear

[insidewhy]

I'm referring to this documentation https://www.apollographql.com/docs/react/data/queries/#cache-and-network

We've had a discussion among our whole team and none of us can work out what the intention of this is. It's especially confusing since our tests seem to act differently with respect to this option since upgrading to apollo client 3. We decided it has to be one of the following:

1. On every render, we get a new network request (given how frequently react components can render, this feels a little arbitrary).
2. The network request is only sent the first time a component renders after mounting, after this the cache is always used.

With apollo client 3, it seems that on every render we get a network request sent (1), with apollo 2, it seems, we only get the network request sent on the first render after a mount (2). BTW these behaviors we noticed when using the mocked provider.

So we aren't sure when the network requests are supposed to be triggered.

Following on from this, we aren't sure when nextFetchPolicy triggers. Is this on subsequent renders after the first mount? Or does this "next" policy get remembered across re-renders and thus fetchPolicy only applies once until the entire app is reloaded?

In our testing with apollo client 3, when we set fetchPolicy to cache-and-network and nextFetchPolicy to cache-first we seem to get the "hit network once after hook is first mounted, then use the cache on rerenders" (2) behavior.

At any rate, if ten developers on our team who've been using apollo client extensively for many years can't work out the semantics from the documentation, I think it's likely that the documentation could do with some more details.

[benjamn]

@insidewhy You might find this comment useful regarding what cache-and-network means and why nextFetchPolicy is often needed (though I gather you already know some of this): #6760 (comment)

You can think of nextFetchPolicy as permanently changing the fetchPolicy associated with a particular ObservableQuery (which is what you get when you call client.watchQuery). In React terms, this means the nextFetchPolicy should remain in effect as long as the component remains mounted, but if the component gets unmounted and then remounted, that's when the fetchPolicy will revert to its original value.

As I'm typing this explanation, I'm reminded of a potential complicating factor, which is that the original useQuery options get passed back into useQuery every time the component rerenders (including the original fetchPolicy), which may be overwriting the effect of nextFetchPolicy. If you're seeing behavior that's consistent with this scenario (and inconsistent with what I described in the previous paragraph), please do let me know, since that's something we've been meaning to address.

[insidewhy]

You can think of nextFetchPolicy as permanently changing the fetchPolicy associated with a particular ObservableQuery (which is what you get when you call client.watchQuery). In React terms, this means the nextFetchPolicy should remain in effect as long as the component remains mounted, but if the component gets unmounted and then remounted, that's when the fetchPolicy will revert to its original value.

This aligns with what we expected, i.e. fetchPolicy is used after each mount, then after the query is resolved one, the nextFetchPolicy remains in effect (until unmount).

As I'm typing this explanation, I'm reminded of a potential complicating factor, which is that the original useQuery options get passed back into useQuery every time the component rerenders (including the original fetchPolicy), which may be overwriting the effect of nextFetchPolicy. If you're seeing behavior that's consistent with this scenario (and inconsistent with what I described in the previous paragraph), please do let me know, since that's something we've been meaning to address.

... but then after reading this next paragraph, I'm confused again :D Are you describing a potential bug here?

Also, do you think it's worth updating the documentation?

[insidewhy]

@benjamn Also when I read the comment you linked to, I see that the cache-and-network policy does not mean "hit the network on every render" but "hit the network whenever there's a cache update that would affect this query". Although that doesn't quite match up with what we're seeing in #8125 where we see "hit the network when a cache update affects this query" even for a "cache-first" query (the same as when we use "cache-and-network" with a nextFetchPolicy of "cache-first").