QueryObserverOptionsBase<TQueryData, TData> class sealed

QueryOptions plus everything only an observer cares about: when to refetch (refetchOnMount, refetchOnWindowFocus, refetchOnReconnect, refetchInterval, refetchIntervalInBackground, retryOnMount), what to show while there is no data (placeholderData), and what part of the data to report (select).

The fields QueryOptions declares describe the cache entry, which every observer of the key shares; these describe one observer, so two widgets watching one key may poll, refetch and select differently. As on QueryOptions, null means unset on every field, and an unset field takes the key's registered default, then the client's, then the library default each field names.

Sealed over exactly two shapes: QueryObserverOptions, which has no select, and QuerySelectOptions, which requires one. Dart cannot infer the query's data type from a select function alone, so a select that changes the type lives on a separate options class that names both type arguments; the data type an observer reports is then always anchored by a required parameter — queryFn on the plain shape, select on the select shape — and never silently inferred as dynamic. QueryObserver and QueryClient.defaultQueryObserverOptions accept either shape through this base.

Like QueryOptions, deliberately without value equality: an observer is handed the options a widget built on every build and compares what they resolve to, so a select or placeholderData written inline is not a change by itself.

Inheritance
Annotations

Properties

enabled → Enabled?
Whether the query may fetch on its own. The default: Enabled.yes. A disabled query still serves whatever the cache holds and can still be refetched by hand.
finalinherited
gcTime → GcTime?
How long the query stays cached after its last observer leaves. The default: GcTime.defaultValue, five minutes.
finalinherited
hashCode → int
The hash code for this object.
no setterinherited
initialData → InitialData<TQueryData>?
Data the cache starts with, as if it had been fetched — see InitialData. No default: unset, the query starts without data. Unlike placeholderData it is written to the cache, and it goes stale by staleTime from initialDataUpdatedAt on.
finalinherited
initialDataUpdatedAt → DateTime?
When initialData was fetched, for the staleness clock. No default: unset, the seed counts as fetched the moment it is written.
finalinherited
initialDataUpdatedAtCompute → DateTime? Function()?
Computes the seed timestamp only when data is actually seeded. No default. Mutually exclusive with initialDataUpdatedAt; a null result means now.
finalinherited
meta → Object?
Arbitrary data carried along for logging, devtools or a query function, which receives it as QueryFunctionContext.meta. No default: unset, the key's registered default applies, if any.
finalinherited
networkMode → NetworkMode?
How connectivity gates the fetch. The default: NetworkMode.online, an offline device pauses the fetch until it is back.
finalinherited
placeholderData → PlaceholderData<TQueryData>?
Data shown while the query has none of its own — see PlaceholderData. No default: unset, an observer without data reports a pending result. Never written to the cache: a result built from it reports isPlaceholderData, and it gives way the moment real data arrives.
final
queryFn → QueryFn<TQueryData>?
Fetches the data. Unset, the query uses the function registered for its key with QueryClient.setQueryDefaults; with none there either, a fetch fails with MissingQueryFunctionError.
finalinherited
queryKey → QueryKey
The key this query is cached under. Required. Bound to exactly one data type: a key read as another type — a supertype included — throws QueryDataTypeError.
finalinherited
refetchInterval → RefetchInterval?
Polls the query on a timer while this observer is subscribed. The default: RefetchInterval.off.
final
refetchIntervalInBackground → bool?
Whether refetchInterval keeps polling while the app is not focused. The default: false, the timer skips its turns until focus returns.
final
refetchOnMount → RefetchOn?
Whether this observer subscribing triggers a refetch. The default: RefetchOn.ifStale, only when the data is older than staleTime.
final
refetchOnReconnect → RefetchOn?
Whether the device coming back online triggers a refetch. The default: RefetchOn.ifStale — except under NetworkMode.always, where it is RefetchOn.never: a fetch that ignores connectivity has nothing to catch up on.
final
refetchOnWindowFocus → RefetchOn?
Whether the app regaining focus triggers a refetch. The default: RefetchOn.ifStale.
final
retry → RetryPolicy?
Whether a failed fetch is retried. The default: RetryPolicy.times(3), three retries after the first failure (TanStack Query: retry: 3). QueryClient.query is the exception: when neither these options nor the client's defaults set retry, its fetch is not retried.
finalinherited
retryDelay → RetryDelay?
How long to wait between attempts. The default: RetryDelay.defaultValue, exponential back-off from one second — one, two, four, … — capped at thirty.
finalinherited
retryOnMount → bool?
Whether a query that ended in an error retries when an observer mounts. The default: true, the mount refetches, and only retryOnMount: false leaves the error standing until something else asks.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
select → SelectFn<TQueryData, TData>?
Narrows the data the observer reports: while the selection stays equal, the reported data keeps its instance (unless structuralSharing is switched off). The rest of the result (fetchStatus, dataUpdatedAt, …) still changes, and listeners are told of that. No default: null on a QueryObserverOptions, never on a QuerySelectOptions.
no setter
staleTime → StaleTime?
How long fetched data counts as fresh. The default: StaleTime.zero, stale the moment it arrives, so every mount, focus and reconnect refetches.
finalinherited
structuralSharing → StructuralSharing<TQueryData>?
How new data is reconciled with what the cache already holds — see StructuralSharing. The default: replaceEqualDeep, which keeps every deep-equal part of the previous data. noStructuralSharing turns it off.
finalinherited
toStringFields → Map<String, Object?>
What toString shows after the key: every field, in declaration order, with the unset (null) ones skipped — so a test failure or a debug print reads QueryOptions<int>(QueryKey(["a"]), staleTime: …) rather than Instance of 'QueryOptions<int>'. A subclass adds its own fields after these.
no setteroverride

Methods

copyWith({QueryKey? queryKey, QueryFn<TQueryData>? queryFn, Enabled? enabled, StaleTime? staleTime, GcTime? gcTime, RetryPolicy? retry, RetryDelay? retryDelay, NetworkMode? networkMode, InitialData<TQueryData>? initialData, DateTime? initialDataUpdatedAt, DateTime? initialDataUpdatedAtCompute()?, StructuralSharing<TQueryData>? structuralSharing, Object? meta, PlaceholderData<TQueryData>? placeholderData, RefetchOn? refetchOnMount, RefetchOn? refetchOnWindowFocus, RefetchOn? refetchOnReconnect, RefetchInterval? refetchInterval, bool? refetchIntervalInBackground, bool? retryOnMount}) → QueryObserverOptionsBase<TQueryData, TData>
This, with the given fields replaced; each shape returns its own type. select is not a field here — it is what tells the two shapes apart — so only QuerySelectOptions.copyWith accepts one.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited