---
id: query-freshness
track: learn
product: query
locale: en
order: 10
revision: 2
sourceCheckedOn: "2026-08-03"
versionRange: "Query ^5"
verifiedAgainst: "@tanstack/react-query@5.101.4"
contentModel: 2
prerequisites:
  - "Query cache and queryKey basics"
sourceRefs:
  - "https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults"
  - "https://tanstack.com/query/latest/docs/framework/react/guides/query-options"
---

# Define when data is fresh

> Separate staleTime from gcTime and co-locate keys, fetchers, and time policy in shared queryOptions.

**Outcome:** Set freshness from business change frequency and explain why garbage-collection time does not prevent background refetching.

## Freshness and retention are different questions

staleTime controls how long data remains fresh; gcTime controls how long an inactive query without observers remains cached. Cached data is stale by default, while inactive queries are normally collected after five minutes. Increasing gcTime does not make data fresh.

## Put time policy in the query contract

queryOptions returns the supplied configuration at runtime while preserving the type relationship between queryKey and queryFn. Loader prefetching, component reads, and cache writes should reuse the contract so one resource does not acquire conflicting time policies.

> **Note:** Derive timing from data volatility and user tolerance; do not set Infinity merely to reduce requests.

File: `src/features/issues/queries.ts`

```ts
import { queryOptions } from '@tanstack/react-query'

export const issueOptions = (issueId: string) => queryOptions({
  queryKey: ['issues', 'detail', issueId] as const,
  queryFn: () => getIssue(issueId),
  staleTime: 60_000,
  gcTime: 10 * 60_000,
})
```

## Practice and verification

### Completion checkpoint

Choose staleTime from business change frequency and distinguish freshness from inactive-cache collection.

### Exercise

Define distinct freshness policies for issue lists, issue details, and a static priority dictionary, then justify them.

### Verification

Use Devtools to observe fresh, stale, and inactive states and verify focus refetching matches the policy.

### Common pitfalls

- Using gcTime to control whether data refetches.
- Disabling every automatic refetch to hide an incorrect freshness policy.

## Official sources

- https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults
- https://tanstack.com/query/latest/docs/framework/react/guides/query-options