How to Use fetchPolicy in Apollo Client for GraphQL

In Apollo Client, use the fetchPolicy option to control how queries interact with the cache and network. It accepts values like cache-first, network-only, and cache-and-network to decide whether to fetch data from cache, network, or both.

Syntax

The fetchPolicy option is set inside the query options object when using Apollo Client's useQuery hook or client.query method. It controls how Apollo fetches data.

• cache-first: Returns cached data if available, otherwise fetches from network.
• network-only: Always fetches from network, ignoring cache.
• cache-and-network: Returns cached data first, then fetches from network to update.
• no-cache: Does not use cache at all, always fetches from network.

javascript

const { data, loading, error } = useQuery(MY_QUERY, {
  fetchPolicy: 'cache-first' // or 'network-only', 'cache-and-network', 'no-cache'
});

Example

This example shows how to use fetchPolicy with the useQuery hook to fetch user data. It uses cache-and-network to show cached data immediately and update it when the network response arrives.

javascript

import { gql, useQuery } from '@apollo/client';

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      email
    }
  }
`;

function UserProfile({ userId }) {
  const { data, loading, error } = useQuery(GET_USER, {
    variables: { id: userId },
    fetchPolicy: 'cache-and-network'
  });

  if (loading && !data) return 'Loading...';
  if (error) return `Error: ${error.message}`;

  return (
    <div>
      <h2>{data.user.name}</h2>
      <p>{data.user.email}</p>
    </div>
  );
}

Output

<div>
  <h2>John Doe</h2>
  <p>[e-mail]</p>
</div>

Common Pitfalls

Common mistakes when using fetchPolicy include:

• Using cache-first when you expect fresh data, which may return stale cached data.
• Forgetting to set fetchPolicy when you want to bypass cache, causing unexpected cache hits.
• Using no-cache unnecessarily, which disables caching and can hurt performance.

Always choose the policy that matches your data freshness and performance needs.

javascript

/* Wrong: expecting fresh data but using cache-first */
const { data } = useQuery(MY_QUERY, { fetchPolicy: 'cache-first' });

/* Right: force network fetch for fresh data */
const { data } = useQuery(MY_QUERY, { fetchPolicy: 'network-only' });

Quick Reference

fetchPolicy	Description
cache-first	Use cache if available, else fetch from network
network-only	Always fetch from network, ignore cache
cache-and-network	Return cache data first, then update with network data
no-cache	Do not use cache, always fetch from network
standby	Do not automatically fetch, wait for manual trigger

Key Takeaways

Use fetchPolicy to control how Apollo Client fetches and caches data.

Choose 'cache-first' for fast responses with cached data, 'network-only' for fresh data.

'cache-and-network' lets you show cached data immediately and update it after network fetch.

Avoid 'no-cache' unless you want to disable caching completely.

Set fetchPolicy explicitly to avoid unexpected cache behavior.