staleTime vs cacheTime

[hosseinmd]

I really don't know what is use case of staleTime and cacheTime and what is different

[TkDodo]

It does get people confused sometimes, which is why I tried to clear that up in a blog post: https://tkdodo.eu/blog/practical-react-query#the-defaults-explained

StaleTime: The duration until a query transitions from fresh to stale. As long as the query is fresh, data will always be read from the cache only - no network request will happen! If the query is stale (which per default is: instantly), you will still get data from the cache, but a background refetch can happen under certain conditions.

CacheTime: The duration until inactive queries will be removed from the cache. This defaults to 5 minutes. Queries transition to the inactive state as soon as there are no observers registered, so when all components which use that query have unmounted.

there is also a very good example in the docs: https://react-query.tanstack.com/guides/caching

[ibadeeCodes]

@TkDodo Nice explanation.
I have a short question regarding this.

By default, if cacheTime is 5 minutes then why staleTime is set to 0ms even if we all knew that the data is coming from the cache which will get updated after 5 minutes and the data is still the same.

Why is the staleTime isn't set to 5 minutes by default even if we all knew that fresh data will only be available after 5 minutes, why does react-query stale the data after 0ms and keep getting data from the cache which will keep providing the same data for the next 5 minutes.

Could you please explain this to me?

[TkDodo]

I'm not sure if you've really understood the explanation above 😅

By default, if cacheTime is 5 minutes then why staleTime is set to 0ms even if we all knew that the data is coming from the cache which will get updated after 5 minutes and the data is still the same.

The data i the cache is not updated after 5 minutes. react-query will not update anything automatically after a fixed period of time, unless you use refetchInterval. The cacheTime is a garbage-collect time. While you are using queries, it does nothing. It only starts to do something after you've stopped using a query (=displaying it on the screen with useQuery). Because maybe you'll need that data later and want to still get it from the cache. So react-query keeps it around for 5 more minutes in case you need it again. If you're sure you don't need it after the last component that used the query has unmounted, you can also set the cacheTime to zero.

Why is the staleTime isn't set to 5 minutes by default even if we all knew that fresh data will only be available after 5 minutes, why does react-query stale the data after 0ms and keep getting data from the cache which will keep providing the same data for the next 5 minutes.

How do we all know that fresh data is available after 5 minutes? If you know that for your app, then please set your staleTime to 5 minutes. But don't expect a refetch after 5 minutes, because again, that's not what staleTime is doing.

React-Query will smartly refetch stale queries in the background, e.g. if you focus the window or mount a new component that uses the query (=an observer). If you just have a todo list on the screen and re-render that a bunch of times, and you do that for 30 minutes or even the whole day, there won't be a refetch, even with staleTime of zero.

[mikib0]

If you just have a todo list on the screen and re-render that a bunch of times, and you do that for 30 minutes or even the whole day, there won't be a refetch, even with staleTime of zero.

Ha! Because rerendering a component doesn't create a new observer hence no refetch!

Refetch happens on:

• mounting a new component that useQuery (creating a new observer)
• window refocus
• network reconnect

Took me a while to grasp :)

[markomitranic]

To summarize this for future readers (and guys please correct me if i am wrong @TkDodo ) so that they don't have to read the long-winded technical explanations and the blogpost:

• staleTime is actually what most people think about when they say cache time. It is the maximum real time that the data is kept in the browser cache. If this time runs out, data will be fetched without cache the next time a component requests it.
• cacheTime name is therefore misleading, as it is only relevant if the cache is inactive for that amount of time. It does the same kind of cache invalidation - but only if the data has not been accessed/used in a given amount of time.

That is the bottom line, spoken like a human, not a developer. :D

[TkDodo]

cacheTime name is therefore misleading

we renamed it to gcTime in v5 for that reason.

[hyf0]

After reading some post, let me try to clear difference.
If you set staleTime to Infinity, a cached query will never re-try unless it get garbage collected determined by cacheTime.

[TkDodo]

Yes, that’s absolutely right. If you unmount all observers, data will be garbage collected after cacheTime. To really keep data forever, you need cacheTime: Infinity as well

[lukemorales]

@TkDodo digging on a very old discussion, but I just had a question from a co-worker and couldn't come up with a precise answer.
Does cacheTime start running if the page is not focused? What happens if you have a page with a query with staleTime = Infinity and you go browse other tabs, and 30 min later you come back to that page?

[TkDodo]

the query will still be there. inactive means no mounted observer.

[ivan-kleshnin]

I really don't know what is use case of staleTime and cacheTime and what is different

Given the defaults with cacheTime = 5min what staleTime really does in plain english:

It allows to limit the amount of HTTP queries sent in background.

Imagine a component that is remounted and mounted back again within 5 min interval.
What will happen as this widget is restored in UI?

Q-1: Will the cached data be reused in component? Yes, default cacheTime = 5 min preserves the data from garbage collection and allows it to be reused.

Q-2: Will an HTTP request to refresh the data be triggered? It depends on staleTime.

1. If staleTime == 0, the cache will be used but an HTTP request will be sent to refresh the data.
   It will happen "in background"', cause UI will typically stay the same unless you rely on isFetching in some way.
2. If staleTime == 5min, the cache will be used and no HTTP request will be sent cause the data is still fresh.

Now you can mentally replace "remount" with "window/tab refocus" and the above explanation will stay true.

Extra tips/conclusions from the above:

• staleTime shouldn't normally exceed cacheTime. staleTime = cacheTime and staleTime > cacheTime will behave exactly the same (unless there's some active polling, or other exotic cases).

R-Q Dev. Tools helped me to clarify the above for myself. I highly recommend to play with it for exploration purposes.

[TkDodo]

staleTime shouldn't normally exceed cacheTime. staleTime = cacheTime and staleTime > cacheTime will behave exactly the same (unless there's some active polling, or other exotic cases).

I don't think this is true at all, as cacheTime only starts to kick in once you have no active observers. It's quite common to set a high staleTime, for example, you can set it to 20 minutes. As long as your component is mounted, cacheTime is irrelevant - the timer doesn't even run. So your query will be fresh for 20 minutes, if you go to lunch break and come back after 30 minutes and re-focus your screen, your query will refetch because it's stale.

Now if you unmount he last observer / component that was using this query - this is where the query goes to inactive in the devtools - and now you have 5 more minutes (or whatever cacheTime is). If you use the query again in this time, you will get the cached data again. If not, it will be garbage collected, and if you then want to use it again, you get a hard loading state.

[SAURABH0504]

I have set staleTime to 10 second and cache time to 2 second. The query is still refetching after 10 second after unmounting. As per your explanation it should have refetch after 2 second. Can you explain this case with an example staleTime > cacheTime.

[TkDodo]

can you show this in a codesandbox example? Even with those values - there is no automatic refetch. 10 seconds staleTime doesn't mean refetch after 10 seconds. It means the data currently available in the cache becomes stale after 10 seconds, so it will refetch the next time a refetch point occurs. These are:

• mounting
• window focus
• network reconnect

if none of these happens, you can view your data on screen for any amount of time without a refetch!

[patricklafrance]

@TkDodo i've set a staleTime of 10 seconds for one of my query with the following key ["/api/plants/search"].

My apps does the initial fetch for ["/api/plants/search"]

Then 2 seconds later (so 8 seconds before the stale time), the same query is done with a parameter "Liliaceae"... Which means the following key: ["/api/plants/search","Liliaceae"].

Since it's not the same key (there is a parameter), I would have expect react-query to fetch immediatly instead of waiting 8 seconds for the cache entry to be stale. I don't understand how parameterized queries can benefit from staleTime.

Is it the expected behavior? I am new to react-query so maybe i've missed something?

Thanks for your help!

Patrick

[TkDodo]

if you mount a query with a new query key, like ["/api/plants/search","Liliaceae"], it will immediately try to fetch data. This query has nothing to do with the query that has the key ["/api/plants/search"]. You should also see two entries in the react-query-devtools.

Even if you would specify a 10 second staleTime globally for all queries, the new query would still fetch on mount because it doesn't have data yet. staleTime only does something if you already have stale data to serve.

So, not sure what is going on - I would have to see it in a codesandbox reproduction please.

[patricklafrance]

Thanks for your answer @TkDodo. Glad to hear it's not an expected behavior. I'll try to come up with a reproduction in the new days.

[SangWonyy]

@TkDodo

i have some question..
i use useQuery in two component : EditMyInfoContainer, TabContainer

detail code :
export const FetchTagListQuery = () => { return useQuery<tagRes, Error | void>("getTag", getTags, { staleTime: 10000 }); };

like above code , i call two useQuery as staleTime : 10000
but,,

each component call api..

also i. found cache-control : no-cache

am i using incorrectly ' react-query ' ?

[TkDodo]

1. cache-control : no-cache has nothing to do with that.
2. not sure which request is done by the getTags function, but I don't see duplicate requests in that screenshot. There is one request to myhashtags only 🤷
3. FetchTagListQuery violates the rules of hooks, it needs to be a custom hook like useTagListQuery
4. It would be better if you'd provide a codesandbox reproduction rather than screenshots...

[yunjin-kim]

@TkDodo

then i have a question

why react query set default time at cacheTime to five minutes and staleTime to 0 second?

and where react query save cache data at computer? cache memory or disk memory?

and if staleTime is gone, react query request to server, if response data is same with react query's cache data. in this situation how react query doing? unconditional change cache data to server data? or compare with react query cache data and server data?
i think unconditional change cache data to server data?, the compare cost is very expensive

[syNack0]

@TkDodo

Thanks for your answer!

you'd want to set refetchInterval

but what if i just want a refetch when it re-renders ?

[TkDodo]

I'm pretty sure you don't want that. useQuery itself will re-render the component when the fetch yields new data, so that would then trigger another refetch, potentially going infinitely. re-renders can happen a lot.

What use-case are you actually trying to solve here ?

[syNack0]

@TkDodo

useQuery itself will re-render the component when the fetch yields new data, so that would then trigger another refetch, potentially going infinitely. re-renders can happen a lot.

sounds make sense... maybe i got something wrong.
one more question please, when the data gets stale, useQuery will re-render the component too, is that right?

[TkDodo]

only if the component uses a field that would change because of that, like the isStale option returned from useQuery.

[syNack0]

@TkDodo
Thanks a looooooot!! have a good day!

[trungvose]

I noticed some confusion in my team recently about what staleTime is and what it does. Surprisingly, no one brought up gcTime (cacheTime). I thought I would share some screenshots to help explain staleTime, in case anyone else here is wondering about it. I also wrote a bit more about it on my blog if you want to check it out.

https://trungvose.com/blog/stale-time-vs-gc-time-cache-time-in-react-query/

Thanks everyone for your input so far!

staleTime

The duration a query result is considered fresh. While fresh, data is read from the cache only, with no network requests. Once stale (default is instantly), data is still read from the cache, but a background refetch can happen under certain conditions.

To understand staleTime, consider a simple example of a hook to fetch a single vehicle:

export const useFetchVehicle = (vehicleId: string | undefined) => {
  const [vehicle, setVehicle] = useState<Vehicle | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);
  useEffect(() => {
    const init = async () => {
      try {
        const data: Vehicle = await fetchVehicle(vehicleId);
        setVehicle(data);
      } catch (err) {
        setError((err as Error).message);
      } finally {
        setLoading(false);
      }
    };
    init();
  }, [vehicleId]);
  return { vehicle, loading, error };
};

Using React Query, we can simplify this with the useQuery hook, eliminating the need for useState and useEffect:

import { useQuery } from '@tanstack/react-query’;

export const useFetchVehicle = (vehicleId: string | undefined) => {
  return useQuery({
    queryKey: ['vehicle', vehicleId],
    queryFn: () => fetchVehicle(vehicleId),
  });
};

Default staleTime of 0

In the above code, useQuery manages the loading, error, and data states. The queryKey uniquely identifies the query, and queryFn fetches the data. Since staleTime is not set, it defaults to 0.

Notice how selecting the first item triggers an API call for /vehicle/1. Returning to the list and selecting the first item again triggers another API call. The UI renders immediately with cached data, but a background refetch happens due to the default staleTime of 0.

In DevTools, ['vehicle', '1'] is considered stale immediately with staleTime set to 0.

A background refetch can happen when:

• New instances of the query mount
• The window is refocused
• The network is reconnected
• The query is configured with a refetch interval

Read more from Important Defaults.

Setting staleTime to another value

Consider setting staleTime to 30 seconds (30 * 1000 milliseconds):

export const useFetchVehicle = (vehicleId: string | undefined) => {
  return useQuery({
    queryKey: ['vehicle', vehicleId],
    queryFn: () => fetchVehicle(vehicleId),
+   staleTime: 30 * 1000,
  });
};

Now, selecting the first item triggers an API call for /vehicle/1. Returning to the list and selecting the first item again does not trigger an API call. The UI renders immediately with cached data, considered fresh for 30 seconds, with no background refetch.

In DevTools, ['vehicle', '1'] is considered fresh for 30 seconds with staleTime set to 30 seconds.

Why the default staleTime is 0

Quoted from UI Dev Data Synchronization.

The default staleTime of 0 means every query is instantly considered stale. This "aggressive but sane default" ensures frequent refetching, which is generally safer than fetching too infrequently.

The docs define this as "aggressive but sane defaults".

Aggressive, because it means we might be refetching from the server more often than we need to, but sane because fetching too often is the lesser evil of the two options.

It's a bit like re-renders in React. Yes, we all want to minimize our application's re-renders, but having too many is significantly better than having too little where your view could be out of sync with your application's state.

Also, if the default value weren't 0, what would be a better default? 20 seconds? 30? 1 minute? It's one of those cases that you can't reliably set up for every possible situation. The answer is always it depends.

Specifically, it depends on the resource in question: How often is it updated? How accurate does the data displayed on your screen need to be? How collaborative is the environment you're working in?

The answer to these questions should be decided by developers on a case by case basis.

If we fetch a Twitter post with all its likes and comments, it's likely stale pretty fast. On the other hand, if we fetch exchange rates that update on a daily basis, well, our data is going to be quite accurate for some time even without refetching.