61 KiB
| id | title |
|---|---|
| QueryClient | QueryClient |
Defined in: packages/vue-query/src/queryClient.ts:52
Vue-aware subclass of @tanstack/query-core's QueryClient. Methods that accept options (such as
CancelOptions or InvalidateOptions) or filters (such as the QueryFilters accepted by
invalidateQueries) also accept a MaybeRefDeep version of it, so you can pass refs directly
without unwrapping them yourself — e.g. queryClient.invalidateQueries({ queryKey: ['post', myRef] }).
ref entries in a queryKey are unwrapped this way on every method, but reactive getter entries
(() => id.value) are only unwrapped when the queryKey is passed as a queryKey property of a
filters/options object (e.g. invalidateQueries({ queryKey: ['post', idGetter] })) — methods like
getQueryData that take the queryKey array as their own argument do not unwrap getter entries there,
and the getter function itself ends up in the cache key.
Install one on your app with VueQueryPlugin, or retrieve it with useQueryClient.
Extends
QueryClient
Constructors
Constructor
new QueryClient(config?: QueryClientConfig): QueryClient;
Defined in: packages/vue-query/src/queryClient.ts:53
Parameters
config?
QueryClientConfig = {}
Returns
QueryClient
Overrides
QC.constructor
Properties
isRestoring?
optional isRestoring?: Ref<boolean, boolean>;
Defined in: packages/vue-query/src/queryClient.ts:66
true while a clientPersister passed to VueQueryPlugin is restoring the cache. Queries don't fetch
while this is true. Defaults to false if no persister is configured.
Methods
cancelQueries()
cancelQueries<TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(filters?: QueryFilters<TTaggedQueryKey>, options?: MaybeRefDeep<CancelOptions>): Promise<void>;
Defined in: packages/vue-query/src/queryClient.ts:223
Cancels outgoing fetches for queries matching the given filters. Most useful when performing
optimistic updates, since any outgoing refetch that resolves afterwards would otherwise
overwrite the optimistic update. By default (revert: true), a cancelled query's data is
reverted to its state before the outgoing fetch started.
The returned promise never rejects, even if individual cancellations fail.
Type Parameters
TTaggedQueryKey
TTaggedQueryKey extends readonly unknown[] = readonly unknown[]
Parameters
filters?
QueryFilters<TTaggedQueryKey>
The filters that select which queries to cancel. Without filters, every query is cancelled.
options?
MaybeRefDeep<CancelOptions>
Returns
Promise<void>
A promise that resolves once every cancellation has settled.
Example
await queryClient.cancelQueries({ queryKey: ['posts'], exact: true })
Overrides
QC.cancelQueries
clear()
clear(): void;
Defined in: packages/query-core/src/queryClient.ts:1169
Clears both the query cache and the mutation cache this client is connected to.
Returns
void
Example
import { QueryClient } from '@tanstack/query-core'
const queryClient = new QueryClient()
queryClient.clear()
Inherited from
QC.clear
defaultMutationOptions()
defaultMutationOptions<T extends MutationOptions<any, any, any, any>>(options?: T): T;
Defined in: packages/query-core/src/queryClient.ts:1144
The mutation counterpart of QueryClient#defaultQueryOptions. Called by framework
adapters (e.g. inside useMutation) to merge the client's defaultOptions.mutations, then
queryClient.setMutationDefaults for the given mutationKey, then the caller's options on
top. A no-op if the options are already defaulted (_defaulted: true).
Type Parameters
T
T extends MutationOptions<any, any, any, any>
Parameters
options?
T
The mutation options passed by the caller.
Returns
T
The defaulted options.
Inherited from
QC.defaultMutationOptions
defaultQueryOptions()
defaultQueryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = never>(options:
| QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>
| DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
Defined in: packages/query-core/src/queryClient.ts:1055
Called by framework adapters (e.g. inside useQuery) to resolve the options passed by the
caller into their final, defaulted form: merging the client's own defaultOptions.queries,
then queryClient.setQueryDefaults for the given queryKey, then the caller's options on
top. A no-op if the options are already defaulted (_defaulted: true).
Type Parameters
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TData
TData = TQueryFnData
TQueryData
TQueryData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = never
Parameters
options
| QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>
| DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
The query options passed by the caller.
Returns
DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
The defaulted options, with queryHash and dependent defaults (e.g.
refetchOnReconnect) filled in.
Inherited from
QC.defaultQueryOptions
ensureInfiniteQueryData()
ensureInfiniteQueryData<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: EnsureInfiniteQueryDataOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<InfiniteData<TData, TPageParam>>;
Defined in: packages/query-core/src/queryClient.ts:810
Returns the cached data of an infinite query, or fetches it if there is none. With
revalidateIfStale, stale cached data is also refetched in the background.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
Parameters
options
EnsureInfiniteQueryDataOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
The infinite query options. If the query has no cached data yet, it is fetched with these options.
Returns
Promise<InfiniteData<TData, TPageParam>>
A promise that resolves to the cached InfiniteData, or to the fetched data if nothing was cached yet.
Deprecated
Use queryClient.infiniteQuery({ ...options, staleTime: 'static' }) instead. This method will be removed in the next major version.
Inherited from
QC.ensureInfiniteQueryData
ensureQueryData()
Call Signature
ensureQueryData<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>): Promise<TData>;
Defined in: packages/vue-query/src/queryClient.ts:103
Returns the cached data of a query, or fetches it if there is none. With revalidateIfStale,
stale cached data is also refetched in the background.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
Parameters
options
EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>
The query options. If the query has no cached data yet, it is fetched with these options.
Returns
Promise<TData>
A promise that resolves to the cached data, or to the fetched data if nothing was cached yet.
Deprecated
Use queryClient.query({ ...options, staleTime: 'static' }) instead. This method will be removed in the next major version.
Overrides
QC.ensureQueryData
Call Signature
ensureQueryData<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: MaybeRefDeep<EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey, never>>): Promise<TData>;
Defined in: packages/vue-query/src/queryClient.ts:115
Returns the cached data of a query, or fetches it if there is none. With revalidateIfStale,
stale cached data is also refetched in the background.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
Parameters
options
MaybeRefDeep<EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey, never>>
The query options. If the query has no cached data yet, it is fetched with these options.
Returns
Promise<TData>
A promise that resolves to the cached data, or to the fetched data if nothing was cached yet.
Deprecated
Use queryClient.query({ ...options, staleTime: 'static' }) instead. This method will be removed in the next major version.
Overrides
QC.ensureQueryData
fetchInfiniteQuery()
Call Signature
fetchInfiniteQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<InfiniteData<TData, TPageParam>>;
Defined in: packages/vue-query/src/queryClient.ts:530
Fetches and caches an infinite query, or returns its cached data if it isn't stale.
Type Parameters
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
Parameters
options
FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
The infinite query options, including the queryKey, the queryFn, and the
initialPageParam.
Returns
Promise<InfiniteData<TData, TPageParam>>
A promise that resolves to the cached or fetched InfiniteData, or rejects with the fetch error.
Deprecated
Use queryClient.infiniteQuery(options) instead. This method will be removed in the next major version.
Overrides
QC.fetchInfiniteQuery
Call Signature
fetchInfiniteQuery<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: MaybeRefDeep<FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>): Promise<InfiniteData<TData, TPageParam>>;
Defined in: packages/vue-query/src/queryClient.ts:549
Fetches and caches an infinite query, or returns its cached data if it isn't stale.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
Parameters
options
MaybeRefDeep<FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>
The infinite query options, including the queryKey, the queryFn, and the
initialPageParam.
Returns
Promise<InfiniteData<TData, TPageParam>>
A promise that resolves to the cached or fetched InfiniteData, or rejects with the fetch error.
Deprecated
Use queryClient.infiniteQuery(options) instead. This method will be removed in the next major version.
Overrides
QC.fetchInfiniteQuery
fetchQuery()
Call Signature
fetchQuery<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = never>(options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<TData>;
Defined in: packages/vue-query/src/queryClient.ts:358
Fetches and caches a query, or returns its cached data if it isn't stale. Unlike in observers,
the fetch isn't retried unless retry is set.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = never
Parameters
options
FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
The query options, including the queryKey and the queryFn used if the
query needs to fetch.
Returns
Promise<TData>
A promise that resolves to the cached or fetched data, or rejects with the fetch error.
Deprecated
Use queryClient.query(options) instead. This method will be removed in the next major version.
Overrides
QC.fetchQuery
Call Signature
fetchQuery<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = never>(options:
| MaybeRefDeep<FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>
| (() => FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>)): Promise<TData>;
Defined in: packages/vue-query/src/queryClient.ts:377
Fetches and caches a query, or returns its cached data if it isn't stale. Unlike in observers,
the fetch isn't retried unless retry is set.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = never
Parameters
options
| MaybeRefDeep<FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>
| (() => FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>)
The query options, including the queryKey and the queryFn used if the
query needs to fetch.
Returns
Promise<TData>
A promise that resolves to the cached or fetched data, or rejects with the fetch error.
Deprecated
Use queryClient.query(options) instead. This method will be removed in the next major version.
Overrides
QC.fetchQuery
getDefaultOptions()
getDefaultOptions(): DefaultOptions;
Defined in: packages/query-core/src/queryClient.ts:894
Returns the default options that were set when creating the client, or via QueryClient#setDefaultOptions.
Returns
The client's current default options.
Example
import { QueryClient } from '@tanstack/query-core'
const queryClient = new QueryClient()
const defaultOptions = queryClient.getDefaultOptions()
Inherited from
QC.getDefaultOptions
getMutationCache()
getMutationCache(): MutationCache;
Defined in: packages/query-core/src/queryClient.ts:878
Returns the mutation cache this client is connected to.
Returns
MutationCache
The MutationCache instance.
Example
import { QueryClient } from '@tanstack/query-core'
const queryClient = new QueryClient()
const mutationCache = queryClient.getMutationCache()
const mutations = mutationCache.findAll({ status: 'pending' })
Inherited from
QC.getMutationCache
getMutationDefaults()
getMutationDefaults(mutationKey: MaybeRefDeep<readonly unknown[]>): MutationObserverOptions<any, any, any, any>;
Defined in: packages/vue-query/src/queryClient.ts:693
Returns the default options registered for mutations whose mutation key partially matches
the given mutationKey, via QueryClient#setMutationDefaults. If multiple registered
defaults match, they are merged together in registration order.
Parameters
mutationKey
MaybeRefDeep<readonly unknown[]>
The mutation key to look up registered defaults for.
Returns
MutationObserverOptions<any, any, any, any>
The merged default options of every registration that matches, or an empty object if none match.
Example
const defaultOptions = queryClient.getMutationDefaults(['addPost'])
Overrides
QC.getMutationDefaults
getQueriesData()
getQueriesData<TData = unknown>(filters: MaybeRefDeep<QueryFilters<readonly unknown[]>>): [readonly unknown[], TData | undefined][];
Defined in: packages/vue-query/src/queryClient.ts:139
Imperative (non-reactive) way to retrieve the cached data of multiple queries at once. Only queries matching the given filters are returned; if none match, an empty array is returned.
Because the matched queries can hold data of different shapes (e.g. a broad filter can match
queries with unrelated data types), the TQueryFnData generic defaults to unknown rather
than being inferred. Passing a more specific type is a convenience for call sites that know
every matched query holds the same shape — it is not checked against the actual cache
contents.
Type Parameters
TData
TData = unknown
Parameters
filters
MaybeRefDeep<QueryFilters<readonly unknown[]>>
The filters that select which queries to read.
Returns
[readonly unknown[], TData | undefined][]
An array of query key and data pairs. The data is undefined for a query with no cached data.
See
Example
const data = queryClient.getQueriesData({ queryKey: ['posts'] })
Overrides
QC.getQueriesData
getQueryCache()
getQueryCache(): QueryCache;
Defined in: packages/query-core/src/queryClient.ts:862
Returns the query cache this client is connected to.
Returns
QueryCache
The QueryCache instance.
Example
import { QueryClient } from '@tanstack/query-core'
const queryClient = new QueryClient()
const queryCache = queryClient.getQueryCache()
const queries = queryCache.findAll({ queryKey: ['posts'] })
Inherited from
QC.getQueryCache
getQueryData()
Call Signature
getQueryData<TData = unknown, TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(queryKey: TTaggedQueryKey):
| InferDataFromTag<TData, TTaggedQueryKey>
| undefined;
Defined in: packages/vue-query/src/queryClient.ts:78
Imperative (non-reactive) way to retrieve data for a QueryKey. Should only be used in callbacks or functions where reading the latest data is necessary, e.g. for optimistic updates.
Hint: Do not use this function inside a component, because it won't receive updates.
Use useQuery to create a QueryObserver that subscribes to changes.
Type Parameters
TData
TData = unknown
TTaggedQueryKey
TTaggedQueryKey extends readonly unknown[] = readonly unknown[]
Parameters
queryKey
TTaggedQueryKey
The query key of the query to read.
Returns
| InferDataFromTag<TData, TTaggedQueryKey>
| undefined
The cached data for the query, or undefined if no query with this key has been observed yet.
See
Overrides
QC.getQueryData
Call Signature
getQueryData<TData = unknown>(queryKey: MaybeRefDeep<readonly unknown[]>): TData | undefined;
Defined in: packages/vue-query/src/queryClient.ts:85
Imperative (non-reactive) way to retrieve data for a QueryKey. Should only be used in callbacks or functions where reading the latest data is necessary, e.g. for optimistic updates.
Hint: Do not use this function inside a component, because it won't receive updates.
Use useQuery to create a QueryObserver that subscribes to changes.
Type Parameters
TData
TData = unknown
Parameters
queryKey
MaybeRefDeep<readonly unknown[]>
The query key of the query to read.
Returns
TData | undefined
The cached data for the query, or undefined if no query with this key has been observed yet.
Overrides
QC.getQueryData
getQueryDefaults()
getQueryDefaults(queryKey: MaybeRefDeep<readonly unknown[]>): OmitKeyof<QueryObserverOptions<any, any, any, any, any>, "queryKey">;
Defined in: packages/vue-query/src/queryClient.ts:670
Returns the default options registered for queries whose query key partially matches the
given queryKey, via QueryClient#setQueryDefaults. If multiple registered defaults
match, they are merged together in registration order.
Parameters
queryKey
MaybeRefDeep<readonly unknown[]>
The query key to look up registered defaults for.
Returns
OmitKeyof<QueryObserverOptions<any, any, any, any, any>, "queryKey">
The merged default options of every registration that matches, or an empty object if none match.
Example
const defaultOptions = queryClient.getQueryDefaults(['posts'])
Overrides
QC.getQueryDefaults
getQueryState()
Call Signature
getQueryState<TQueryFnData = unknown, TError = Error, TTaggedQueryKey extends readonly unknown[] = readonly unknown[], TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>, TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>>(queryKey: TTaggedQueryKey):
| QueryState<TInferredQueryFnData, TInferredError>
| undefined;
Defined in: packages/vue-query/src/queryClient.ts:187
Imperative (non-reactive) way to retrieve an existing query's state. If the query does not
exist, undefined is returned.
Type Parameters
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TTaggedQueryKey
TTaggedQueryKey extends readonly unknown[] = readonly unknown[]
TInferredQueryFnData
TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>
TInferredError
TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>
Parameters
queryKey
TTaggedQueryKey
The query key of the query to read.
Returns
| QueryState<TInferredQueryFnData, TInferredError>
| undefined
The query's state, or undefined if no query with this key exists.
Example
const state = queryClient.getQueryState(['posts'])
console.log(state?.dataUpdatedAt)
Overrides
QC.getQueryState
Call Signature
getQueryState<TData = unknown, TError = Error>(queryKey: MaybeRefDeep<readonly unknown[]>):
| QueryState<TData, TError>
| undefined;
Defined in: packages/vue-query/src/queryClient.ts:196
Type Parameters
TData
TData = unknown
TError
TError = Error
Parameters
queryKey
MaybeRefDeep<readonly unknown[]>
Returns
| QueryState<TData, TError>
| undefined
Overrides
QC.getQueryState
infiniteQuery()
Call Signature
infiniteQuery<TQueryFnData = unknown, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<TData[] extends InfiniteData<TQueryFnData, unknown>[] ? InfiniteData<TQueryFnData, TPageParam> : TData>;
Defined in: packages/vue-query/src/queryClient.ts:457
Asynchronous method to fetch and cache an infinite query, resolving with an InfiniteData object or throwing with the error.
Behaves like QueryClient#query, accepting the same options (minus
initialPageParam), plus the required initialPageParam, and an optional pages /
getNextPageParam pair used to refetch a fixed number of pages from the start.
This method replaces the deprecated fetchInfiniteQuery, and — combined with
{ staleTime: 'static' } — the deprecated ensureInfiniteQueryData.
Type Parameters
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TData
TData = InfiniteData<TQueryFnData, unknown>
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
Parameters
options
InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
The infinite query options, including the queryKey, the queryFn, and the
initialPageParam.
Returns
Promise<TData[] extends InfiniteData<TQueryFnData, unknown>[] ? InfiniteData<TQueryFnData, TPageParam> : TData>
A promise that resolves to the InfiniteData, or to the result of select if
provided. It rejects with the error from the fetch or from select.
Example
try {
const data = await queryClient.infiniteQuery({ queryKey, queryFn, initialPageParam: 0 })
console.log(data.pages)
} catch (error) {
console.log(error)
}
Overrides
QC.infiniteQuery
Call Signature
infiniteQuery<TQueryFnData = unknown, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: MaybeRefDeep<InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>): Promise<TData[] extends InfiniteData<TQueryFnData, unknown>[] ? InfiniteData<TQueryFnData, TPageParam> : TData>;
Defined in: packages/vue-query/src/queryClient.ts:477
Asynchronous method to fetch and cache an infinite query, resolving with an InfiniteData object or throwing with the error.
Behaves like QueryClient#query, accepting the same options (minus
initialPageParam), plus the required initialPageParam, and an optional pages /
getNextPageParam pair used to refetch a fixed number of pages from the start.
This method replaces the deprecated fetchInfiniteQuery, and — combined with
{ staleTime: 'static' } — the deprecated ensureInfiniteQueryData.
Type Parameters
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TData
TData = InfiniteData<TQueryFnData, unknown>
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
Parameters
options
MaybeRefDeep<InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>
The infinite query options, including the queryKey, the queryFn, and the
initialPageParam.
Returns
Promise<TData[] extends InfiniteData<TQueryFnData, unknown>[] ? InfiniteData<TQueryFnData, TPageParam> : TData>
A promise that resolves to the InfiniteData, or to the result of select if
provided. It rejects with the error from the fetch or from select.
Overrides
QC.infiniteQuery
invalidateQueries()
invalidateQueries<TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(filters?:
| InvalidateQueryFilters<TTaggedQueryKey>
| (() => InvalidateQueryFilters<TTaggedQueryKey>), options?: MaybeRefDeep<InvalidateOptions>): Promise<void>;
Defined in: packages/vue-query/src/queryClient.ts:234
Marks queries matching the given filters as invalidated. Unlike QueryClient#removeQueries, invalidated queries stay in the cache.
Unless filters.refetchType is 'none', matching queries are then refetched via
QueryClient#refetchQueries, using filters.refetchType if set, otherwise
filters.type, otherwise 'active'.
Type Parameters
TTaggedQueryKey
TTaggedQueryKey extends readonly unknown[] = readonly unknown[]
Parameters
filters?
| InvalidateQueryFilters<TTaggedQueryKey>
| (() => InvalidateQueryFilters<TTaggedQueryKey>)
The filters that select which queries to invalidate, plus refetchType to
control which of them to refetch afterwards. Without filters, every query is invalidated.
options?
MaybeRefDeep<InvalidateOptions>
Passed to QueryClient#refetchQueries, e.g. cancelRefetch and
throwOnError.
Returns
Promise<void>
A promise that resolves once the refetch settles, or immediately if refetchType is
'none'.
Example
await queryClient.invalidateQueries({ queryKey: ['posts'], refetchType: 'active' })
Overrides
QC.invalidateQueries
isFetching()
isFetching(filters?: MaybeRefDeep<Omit<QueryFilters<readonly unknown[]>, "fetchStatus">>): number;
Defined in: packages/vue-query/src/queryClient.ts:68
Returns the number of queries in the cache that are currently fetching, optionally matching a set of filters. This includes background-fetching, loading new pages, and loading more infinite query results.
Parameters
filters?
MaybeRefDeep<Omit<QueryFilters<readonly unknown[]>, "fetchStatus">> = {}
Narrows down which fetching queries are counted. Without filters, every fetching query is counted.
Returns
number
The number of matching queries whose fetchStatus is 'fetching'.
Example
if (queryClient.isFetching()) {
console.log('At least one query is fetching!')
}
Overrides
QC.isFetching
isMutating()
isMutating(filters?: MaybeRefDeep<MutationFilters<unknown, Error, unknown, unknown>>): number;
Defined in: packages/vue-query/src/queryClient.ts:74
Returns the number of mutations in the cache that are currently pending, optionally matching a set of filters.
Parameters
filters?
MaybeRefDeep<MutationFilters<unknown, Error, unknown, unknown>> = {}
Narrows down which pending mutations are counted. Without filters, every pending mutation is counted.
Returns
number
The number of matching mutations whose status is 'pending'.
Example
if (queryClient.isMutating()) {
console.log('At least one mutation is pending!')
}
Overrides
QC.isMutating
mount()
mount(): void;
Defined in: packages/query-core/src/queryClient.ts:103
Called by a framework adapter's QueryClientProvider-equivalent when it mounts, to start
listening for focus/online events and resume paused mutations. Ref-counted via an internal
mount count, so nested or multiple providers sharing the same QueryClient don't tear down
the shared listeners until the last one unmounts.
Returns
void
Inherited from
QC.mount
prefetchInfiniteQuery()
Call Signature
prefetchInfiniteQuery<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<void>;
Defined in: packages/vue-query/src/queryClient.ts:595
Fetches and caches an infinite query like QueryClient#fetchInfiniteQuery, but ignores the result and any error.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
Parameters
options
FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
The infinite query options, including the queryKey, the queryFn, and the
initialPageParam.
Returns
Promise<void>
A promise that resolves once the fetch settles. It never rejects.
Deprecated
use void queryClient.infiniteQuery(options) instead. You can swallow errors with .catch(noop). This method will be removed in the next major version.
Overrides
QC.prefetchInfiniteQuery
Call Signature
prefetchInfiniteQuery<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: MaybeRefDeep<FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>): Promise<void>;
Defined in: packages/vue-query/src/queryClient.ts:614
Fetches and caches an infinite query like QueryClient#fetchInfiniteQuery, but ignores the result and any error.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
Parameters
options
MaybeRefDeep<FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>>
The infinite query options, including the queryKey, the queryFn, and the
initialPageParam.
Returns
Promise<void>
A promise that resolves once the fetch settles. It never rejects.
Deprecated
use void queryClient.infiniteQuery(options) instead. You can swallow errors with .catch(noop). This method will be removed in the next major version.
Overrides
QC.prefetchInfiniteQuery
prefetchQuery()
Call Signature
prefetchQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>): Promise<void>;
Defined in: packages/vue-query/src/queryClient.ts:419
Fetches and caches a query like QueryClient#fetchQuery, but ignores the result and any error.
Type Parameters
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
Parameters
options
FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>
The query options, including the queryKey and the queryFn used if the
query needs to fetch.
Returns
Promise<void>
A promise that resolves once the fetch settles. It never rejects.
Deprecated
Use queryClient.query(options) instead. You can swallow errors with .catch(noop). This method will be removed in the next major version.
Overrides
QC.prefetchQuery
Call Signature
prefetchQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: MaybeRefDeep<FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, never>>): Promise<void>;
Defined in: packages/vue-query/src/queryClient.ts:431
Fetches and caches a query like QueryClient#fetchQuery, but ignores the result and any error.
Type Parameters
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TData
TData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
Parameters
options
MaybeRefDeep<FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, never>>
The query options, including the queryKey and the queryFn used if the
query needs to fetch.
Returns
Promise<void>
A promise that resolves once the fetch settles. It never rejects.
Deprecated
Use queryClient.query(options) instead. You can swallow errors with .catch(noop). This method will be removed in the next major version.
Overrides
QC.prefetchQuery
query()
Call Signature
query<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = never>(options: QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>): Promise<TData>;
Defined in: packages/vue-query/src/queryClient.ts:290
Asynchronous method to fetch and cache a query, resolving with the data or throwing with the error.
If the query already exists in the cache and its data is not stale (per the given
staleTime), the cached data is returned without fetching. Otherwise, the query is fetched
and the promise resolves once the fetch settles. If a select function is provided, it is
applied to the data in both cases (cached or freshly fetched) before it is returned.
Unlike a reactive observer, retries are disabled by default here (retry: false) unless
explicitly configured, since there is no component to catch a thrown error and retry through
re-render.
The accepted options are QueryObserverOptions minus the fields that only make sense for a
reactive observer — enabled, refetchInterval, refetchIntervalInBackground,
refetchOnWindowFocus, refetchOnReconnect, refetchOnMount, retryOnMount,
notifyOnChangeProps, throwOnError, suspense, and placeholderData are not part of this
method's options.
This method replaces the deprecated fetchQuery, and — combined with
{ staleTime: 'static' } — the deprecated ensureQueryData.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = TQueryFnData
TQueryData
TQueryData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = never
Parameters
options
QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>
The query options, including the queryKey and the queryFn used if the
query needs to fetch.
Returns
Promise<TData>
A promise that resolves to the data, or to the result of select if provided. It
rejects with the error from the fetch or from select.
Example
try {
const data = await queryClient.query({ queryKey, queryFn, staleTime: 10000 })
} catch (error) {
console.log(error)
}
Overrides
QC.query
Call Signature
query<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = never>(options: MaybeRefDeep<QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>>): Promise<TData>;
Defined in: packages/vue-query/src/queryClient.ts:308
Asynchronous method to fetch and cache a query, resolving with the data or throwing with the error.
If the query already exists in the cache and its data is not stale (per the given
staleTime), the cached data is returned without fetching. Otherwise, the query is fetched
and the promise resolves once the fetch settles. If a select function is provided, it is
applied to the data in both cases (cached or freshly fetched) before it is returned.
Unlike a reactive observer, retries are disabled by default here (retry: false) unless
explicitly configured, since there is no component to catch a thrown error and retry through
re-render.
The accepted options are QueryObserverOptions minus the fields that only make sense for a
reactive observer — enabled, refetchInterval, refetchIntervalInBackground,
refetchOnWindowFocus, refetchOnReconnect, refetchOnMount, retryOnMount,
notifyOnChangeProps, throwOnError, suspense, and placeholderData are not part of this
method's options.
This method replaces the deprecated fetchQuery, and — combined with
{ staleTime: 'static' } — the deprecated ensureQueryData.
Type Parameters
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = TQueryFnData
TQueryData
TQueryData = TQueryFnData
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = never
Parameters
options
MaybeRefDeep<QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>>
The query options, including the queryKey and the queryFn used if the
query needs to fetch.
Returns
Promise<TData>
A promise that resolves to the data, or to the result of select if provided. It
rejects with the error from the fetch or from select.
Overrides
QC.query
refetchQueries()
refetchQueries<TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(filters?: RefetchQueryFilters<TTaggedQueryKey>, options?: MaybeRefDeep<RefetchOptions>): Promise<void>;
Defined in: packages/vue-query/src/queryClient.ts:274
Refetches queries matching the given filters, regardless of whether they are stale. Without
filters, every query in the cache is refetched. Queries that are disabled, or static (only
have observers with a static staleTime), are never refetched.
By default (cancelRefetch: true), a currently running fetch is cancelled before the new
one starts. The returned promise does not reject on individual query failures unless
throwOnError is true.
Initially paused fetches do not delay the returned promise. Their later errors are handled
even when throwOnError is true.
Type Parameters
TTaggedQueryKey
TTaggedQueryKey extends readonly unknown[] = readonly unknown[]
Parameters
filters?
RefetchQueryFilters<TTaggedQueryKey>
The filters that select which queries to refetch. Without filters, every query in the cache is included.
options?
MaybeRefDeep<RefetchOptions>
Set cancelRefetch to false to keep a running fetch instead of cancelling
it, and throwOnError to true to reject when a refetch that was not initially paused fails.
Returns
Promise<void>
A promise that resolves once all matching refetches that were not initially paused have settled.
Example
// refetch all active queries partially matching a query key:
await queryClient.refetchQueries({ queryKey: ['posts'], type: 'active' })
Overrides
QC.refetchQueries
removeQueries()
removeQueries<TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(filters?: QueryFilters<TTaggedQueryKey>): void;
Defined in: packages/vue-query/src/queryClient.ts:205
Removes queries from the cache that match the given filters. Unlike QueryClient#invalidateQueries or QueryClient#refetchQueries, this removes matching queries from the cache instead of refetching them. Without filters, every query in the cache is removed.
Type Parameters
TTaggedQueryKey
TTaggedQueryKey extends readonly unknown[] = readonly unknown[]
Parameters
filters?
QueryFilters<TTaggedQueryKey>
The filters that select which queries to remove. Without filters, every query is removed.
Returns
void
Example
queryClient.removeQueries({ queryKey: ['posts'], exact: true })
Overrides
QC.removeQueries
resetQueries()
resetQueries<TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(filters?: QueryFilters<TTaggedQueryKey>, options?: MaybeRefDeep<ResetOptions>): Promise<void>;
Defined in: packages/vue-query/src/queryClient.ts:212
Resets queries matching the given filters back to their initial state (e.g. any
initialData), notifying subscribers rather than removing them. Active queries among the
matched set are then refetched, and the returned promise resolves once that refetch settles.
Type Parameters
TTaggedQueryKey
TTaggedQueryKey extends readonly unknown[] = readonly unknown[]
Parameters
filters?
QueryFilters<TTaggedQueryKey>
The filters that select which queries to reset. Without filters, every query is reset.
options?
MaybeRefDeep<ResetOptions>
Passed to the refetch of the active matched queries, e.g. cancelRefetch and
throwOnError.
Returns
Promise<void>
A promise that resolves once the refetch of the active matched queries settles.
Example
await queryClient.resetQueries({ queryKey: ['posts'], exact: true })
Overrides
QC.resetQueries
resumePausedMutations()
resumePausedMutations(): Promise<unknown>;
Defined in: packages/query-core/src/queryClient.ts:843
Resumes mutations that were paused because there was no network connection. Does nothing (resolving immediately) if the client is currently offline.
Returns
Promise<unknown>
A promise that resolves once the resumed mutations have settled.
Example
import { QueryClient } from '@tanstack/query-core'
const queryClient = new QueryClient()
await queryClient.resumePausedMutations()
Inherited from
QC.resumePausedMutations
setDefaultOptions()
setDefaultOptions(options: MaybeRefDeep<DefaultOptions<Error>>): void;
Defined in: packages/vue-query/src/queryClient.ts:652
Dynamically sets the default options for this client, overwriting any previously defined default options.
Parameters
options
MaybeRefDeep<DefaultOptions<Error>>
The new default options for queries and mutations.
Returns
void
See
Example
import { QueryClient } from '@tanstack/query-core'
const queryClient = new QueryClient()
queryClient.setDefaultOptions({
queries: {
staleTime: Infinity,
},
})
Overrides
QC.setDefaultOptions
setMutationDefaults()
setMutationDefaults<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationKey: MaybeRefDeep<readonly unknown[]>, options: MaybeRefDeep<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>>): void;
Defined in: packages/vue-query/src/queryClient.ts:676
Sets default options for mutations whose mutation key partially matches the given
mutationKey. As with QueryClient#setQueryDefaults, the order of registration
matters when several registered defaults match the same mutation key.
Type Parameters
TData
TData = unknown
TError
TError = Error
TVariables
TVariables = void
TOnMutateResult
TOnMutateResult = unknown
Parameters
mutationKey
MaybeRefDeep<readonly unknown[]>
The mutation key that mutation keys are partially matched against.
options
MaybeRefDeep<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>>
The default options applied to matching mutations.
Returns
void
See
QueryClient#getMutationDefaults
Example
queryClient.setMutationDefaults(['addPost'], { mutationFn: addPost })
Overrides
QC.setMutationDefaults
setQueriesData()
setQueriesData<TData>(
filters: MaybeRefDeep<QueryFilters<readonly unknown[]>>,
updater: Updater<TData | undefined, TData | undefined>,
options?: MaybeRefDeep<SetDataOptions>
): [readonly unknown[], TData | undefined][];
Defined in: packages/vue-query/src/queryClient.ts:175
Synchronous way to immediately update the cached data of multiple queries at once, using filters or partial query key matching. Only queries that already exist and match the given filters are updated; no new cache entries are created. Internally this calls QueryClient#setQueryData for each matching query.
Type Parameters
TData
TData
Parameters
filters
MaybeRefDeep<QueryFilters<readonly unknown[]>>
The filters that select which existing queries to update.
updater
Updater<TData | undefined, TData | undefined>
Either the new data, or a function that receives each matched query's current
data (which may be undefined) and returns the new data.
options?
MaybeRefDeep<SetDataOptions> = {}
Set updatedAt to override the timestamp the written data is recorded with.
Returns
[readonly unknown[], TData | undefined][]
One [queryKey, data] tuple per matched query, in the same shape and with the same
undefined case as QueryClient#setQueryData.
Example
queryClient.setQueriesData({ queryKey: ['posts'] }, (oldPosts) =>
oldPosts ? oldPosts.filter((post) => post.id !== deletedId) : oldPosts,
)
Overrides
QC.setQueriesData
setQueryData()
Call Signature
setQueryData<TQueryFnData = unknown, TTaggedQueryKey extends readonly unknown[] = readonly unknown[], TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>>(
queryKey: TTaggedQueryKey,
updater: Updater<NoInfer<TInferredQueryFnData> | undefined, NoInfer<TInferredQueryFnData> | undefined>,
options?: MaybeRefDeep<SetDataOptions>
): NoInfer<TInferredQueryFnData> | undefined;
Defined in: packages/vue-query/src/queryClient.ts:145
Synchronous way to immediately update a query's cached data. If the updater (or the value
passed) resolves to undefined, the cache is left untouched and no query is created;
otherwise, if the query does not exist yet, it will be created. To update multiple queries
at once by partially matching query keys, use QueryClient#setQueriesData instead.
Updates must be performed immutably: do not mutate oldData, or data previously retrieved
via QueryClient#getQueryData, in place.
Type Parameters
TQueryFnData
TQueryFnData = unknown
TTaggedQueryKey
TTaggedQueryKey extends readonly unknown[] = readonly unknown[]
TInferredQueryFnData
TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>
Parameters
queryKey
TTaggedQueryKey
The query key to set data for.
updater
Updater<NoInfer<TInferredQueryFnData> | undefined, NoInfer<TInferredQueryFnData> | undefined>
Either the new data, or a function that receives the current data (which
may be undefined) and returns the new data.
options?
MaybeRefDeep<SetDataOptions>
Set updatedAt to override the timestamp the written data is recorded with.
Returns
NoInfer<TInferredQueryFnData> | undefined
The data that was written, or undefined if the updater returned undefined — in that case
the write is skipped and the cache is left unchanged.
Example
queryClient.setQueryData(['posts'], newPosts)
// Or, using an updater function that receives the current data:
queryClient.setQueryData(['posts'], (oldPosts) => [...oldPosts, newPost])
Overrides
QC.setQueryData
Call Signature
setQueryData<TQueryFnData, TData = NoUnknown<TQueryFnData>>(
queryKey: MaybeRefDeep<readonly unknown[]>,
updater: Updater<NoInfer<TData> | undefined, NoInfer<TData> | undefined>,
options?: MaybeRefDeep<SetDataOptions>
): NoInfer<TData> | undefined;
Defined in: packages/vue-query/src/queryClient.ts:158
Synchronous way to immediately update a query's cached data. If the updater (or the value
passed) resolves to undefined, the cache is left untouched and no query is created;
otherwise, if the query does not exist yet, it will be created. To update multiple queries
at once by partially matching query keys, use QueryClient#setQueriesData instead.
Updates must be performed immutably: do not mutate oldData, or data previously retrieved
via QueryClient#getQueryData, in place.
Type Parameters
TQueryFnData
TQueryFnData
TData
TData = NoUnknown<TQueryFnData>
Parameters
queryKey
MaybeRefDeep<readonly unknown[]>
The query key to set data for.
updater
Updater<NoInfer<TData> | undefined, NoInfer<TData> | undefined>
Either the new data, or a function that receives the current data (which
may be undefined) and returns the new data.
options?
MaybeRefDeep<SetDataOptions>
Set updatedAt to override the timestamp the written data is recorded with.
Returns
NoInfer<TData> | undefined
The data that was written, or undefined if the updater returned undefined — in that case
the write is skipped and the cache is left unchanged.
Overrides
QC.setQueryData
setQueryDefaults()
setQueryDefaults<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData>(queryKey: MaybeRefDeep<readonly unknown[]>, options: MaybeRefDeep<Omit<UseQueryOptions<TQueryFnData, TError, TData, TQueryData>, "queryKey">>): void;
Defined in: packages/vue-query/src/queryClient.ts:656
Sets default options for queries whose query key partially matches the given queryKey.
If several registered query defaults match a given query key, they are merged together in registration order by QueryClient#getQueryDefaults, so register defaults from the most generic key to the least generic one — more specific defaults should be registered after more generic ones so they take precedence.
Type Parameters
TQueryFnData
TQueryFnData = unknown
TError
TError = Error
TData
TData = TQueryFnData
TQueryData
TQueryData = TQueryFnData
Parameters
queryKey
MaybeRefDeep<readonly unknown[]>
The query key that query keys are partially matched against.
options
MaybeRefDeep<Omit<UseQueryOptions<TQueryFnData, TError, TData, TQueryData>, "queryKey">>
The default options applied to matching queries.
Returns
void
Example
queryClient.setQueryDefaults(['posts'], { queryFn: fetchPosts })
await queryClient.query({ queryKey: ['posts'] })
Overrides
QC.setQueryDefaults
unmount()
unmount(): void;
Defined in: packages/query-core/src/queryClient.ts:126
The inverse of QueryClient#mount — called by a framework adapter's
QueryClientProvider-equivalent when it unmounts. Only tears down the focus/online
listeners once the mount count returns to 0.
Returns
void
Inherited from
QC.unmount