Document refetchQueries caveat for skip vs skipToken

[Copilot]

Apollo Client 4 changed how skipped queries participate in client.refetchQueries(), and the migration guide did not call out the remaining behavioral difference between skip: true and skipToken. This left the “active/inactive queries” section incomplete for users upgrading from Apollo Client 3.

• Migration guide

  • Extend the “Tracking of active and inactive queries” note in apollo-client-4-migration.mdx
  • Clarify that both skip and skipToken put a query into standby, but they are not equivalent for explicit client.refetchQueries({ include: [QUERY] }) before first execution

• Behavioral caveat

  • Document that skip: true queries can still be refetched because Apollo Client already knows the query options, including variables
  • Document that skipToken queries are excluded until first execution because no variables were provided yet
  • Call out that this distinction reflects the behavior introduced in v4.0.11

• Example

  // Can still refetch: options and variables are already known
  useQuery(QUERY, { skip: true, variables: { id } });
  
  await client.refetchQueries({ include: [QUERY] });
  
  // Cannot refetch yet: variables were never provided
  useQuery(QUERY, id ? { variables: { id } } : skipToken);
  
  await client.refetchQueries({ include: [QUERY] });

[apollo-cla]

@copilot: Thank you for submitting a pull request! Before we can merge it, you'll need to sign the Apollo Contributor License Agreement here: https://contribute.apollographql.com/

[apollo-librarian]

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 1 changed, 0 removed

* (developer-tools)/react/(latest)/migrating/apollo-client-4-migration.mdx

Build ID: 6513e8fb1a689734a645fe84
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/6513e8fb1a689734a645fe84

---

⚠️ AI Style Review — 5 Issues Found

Summary

The pull request implements several updates to align documentation with the style guide across multiple sections. Structural changes include the use of gerunds in conceptual overview headings. Language and framing were refined by replacing idiomatic expressions like 'are guaranteed to fail' with 'will fail', and using imperative verbs for instructions. Verb tense and voice were adjusted to prioritize the present tense and active voice. Word and symbol usage updates include adopting dictionary-valid contractions, replacing 'create' with 'build' for person actions, and enforcing the use of the Oxford comma for better readability.

Duration: 2498ms
Review Log: View detailed log

This review is AI-generated. Please use common sense when accepting these suggestions, as they may not always be accurate or appropriate for your specific context.

[changeset-bot]

⚠️ No Changeset found

Latest commit: e6e548f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

npm i https://pkg.pr.new/@apollo/client@13290

commit: e6e548f

[FritsvanCampen]

I would like to offer a suggestion. While the text now clearly mentions the difference between skip and skipToken behavior the critical change pertaining to the Apollo 3 to 4 migration is that refetchQueries() will now eagerly refetch a query, even if it is marked with skip, where in Apollo 3 it would not. It's also good to know that skipToken will not save you here because it will also refetch, if options were provided earlier.

This shifts the behavior of 'skip' to a more 'standby' nature. For me 'skip' means: under no circumstances execute this query, where 'standby' means something like: I don't need the result right now. Perhaps that's something for future work.

[FritsvanCampen]

There is an additional unfortunate choice of words. The sentence:

Additionally, this avoids situations where refetchQueries might execute unnecessary network requests due to the tracking behavior.

This implies that refetchQueries tries to avoid performing unnecessary work, but clearly this does not pertain to standby queries. Perhaps it's worth clarifying that.

[phryneas]

the critical change pertaining to the Apollo 3 to 4 migration is that refetchQueries() will now eagerly refetch a query, even if it is marked with skip, where in Apollo 3 it would not.

I am honestly confused here - I've been digging at the old code, but Apollo Client should refetch skipped queries just the same unless you limit it to active.

The distinction between 3 and 4 is that queries without subscribers are not tracked at all anymore, and cannot be refetched anymore.

Here is the code in the 3.x branch:

apollo-client/src/core/QueryManager.ts

Lines 938 to 944 in 5c202cf

	if (
	fetchPolicy === "standby" ||
	(include === "active" && !oq.hasObservers())
	) {
	return;
	}

And here is the code in the 4.x branch:

apollo-client/src/core/QueryManager.ts

Lines 691 to 693 in b9ab334

	if (include === "active" && fetchPolicy === "standby") {
	return;
	}

Wait... lemme reread this. Sorry, I have 30C indoors here and this is code I haven't touched in a while 😓

[phryneas]

Ah no, rereading that and the docs, I've refreshed my memory. So what the migration docs are saying lines up with the code for me:

	v3	v4
no subscribers	refetch on all	never refetches
standby	never refetches	refetch on all
has subscribers, not standby	refetch on active or all	refetch on active or all

[FritsvanCampen]

I'm actually calling refetchQueries() with { include: [ "queryName" ] }, that's when I'm seeing the described behavior.

Trying to stay cool here also 😅

[FritsvanCampen]

The fact that it throws the warning (line 726) is a hint that it's applying a filter based on .. something? queryNamesAndQueryStrings contains some subset of known queries, but I'm not seeing an obvious definition of how included is determined. It's set to false on line 668 and 672, but I'm not sure why.

[FritsvanCampen]

Ah, I see now. The false is merely an initialization. It actually loops over observed queries on line 679, and the skipped query must then not be in that list. I don't know if it's easy to trace how this.obsQueries is determined.

[phryneas]

I'm actually calling refetchQueries() with { include: [ "queryName" ] }, that's when I'm seeing the described behavior.

Oh dang, then you can't pass in active. 🤦

I'll bring this up internally when we next have our maintainers meeting.

[phryneas]

So we just talked about this - what you can do is this:

client.refetchQueries({
  include: ["queryName"],
  onQueryUpdated: (observable) =>
    observable.options.fetchPolicy !== "standby",
});

This would give you behavior similar to v3 when using skip: true

[jerelmiller]

@copilot let's also mention how to get the v3 behavior where skip: true would skip the query by using onQueryUpdated like in the comment above: #13290 (comment). Wrap that in a <Tip> component.

[Copilot]

@copilot let's also mention how to get the v3 behavior where skip: true would skip the query by using onQueryUpdated like in the comment above: https://github.com/apollographql/apollo-client/pull/...

Added the <Tip> with the onQueryUpdated workaround in 0afee47.

[jerelmiller]

I reworked the section entirely to explicitly call out both the skipToken behavior as well as the skip: true behavior with a recipe for getting back the v3 behavior.

Thanks again for reporting this @FritsvanCampen!