staleTime vs cacheTime

[fardad-dev]

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

[sahilw-grorapid]

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.

So if user opens the site in the browser tab after a long time, lets say a full day. And meanwhile content is updated at the backend, would they still see the cached version?

[TkDodo]

the cache is in-memory so if you close the browser tab it is gone. If you want persistence, look into the persistence plugins: https://tanstack.com/query/v5/docs/framework/react/plugins/persistQueryClient

[sahilw-grorapid]

Yes i have persistQueryClient enabled, the issue that I face is-

1. Suppose user had opened the site in a browser tab. And then they close the tab.
2. Meanwhile backend changes the content.
3. User opens the site the next day. So instead of being served the fresh data, cached data renders. It's only after a manual reload the updated data renders.
   If you'd want more info about the cache configurations, I can provide them too.

[TkDodo]

User opens the site the next day. So instead of being served the fresh data, cached data renders.

this all depends on a bunch of settings:

• maxAge on the persister: If a persisted cache is found that is older than this
  time, it will be discarded. So if you set this to 1 day and users come back later than that, no data will be restored at all.
• staleTime on the query: If a query gets put into the cache from storage, and that data is considered stale, you’ll get a background refetch.

It's only after a manual reload the updated data renders.

If you see this behaviour you likely have staleTime: Infinity or so, because the standard flow is likely that data gets restored when they come back “the next day”, they would see stale data, but they would also get a background refetch immediately and they would see data.

[sahilw-grorapid]

Thanks for the reply @TkDodo , I reduced the maxAge on the persister. So now fresh data is served.

[hyfdev]

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 within5 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

[synack-ai]

@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 ?

[synack-ai]

@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.

[synack-ai]

@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:

exportconstuseFetchVehicle=(vehicleId: string|undefined)=>{const[vehicle,setVehicle]=useState<Vehicle|null>(null);const[loading,setLoading]=useState(false);const[error,setError]=useState<string|null>(null);useEffect(()=>{constinit=async()=>{try{constdata: Vehicle=awaitfetchVehicle(vehicleId);setVehicle(data);}catch(err){setError((errasError).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’;
exportconstuseFetchVehicle=(vehicleId: string|undefined)=>{returnuseQuery({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.