QueryOptions

QueryOptions allows you to customize behaviors like caching, refetching, and duplicate handling for a specific query.

Properties

Name	Type	Default	Description
enabled	bool	true	If false, the query will not fetch automatically.
staleTime	Duration	Duration.zero	Time until data is considered “stale”. Stale data triggers a background refetch when accessed.
cacheTime	Duration	5 mins	Time until inactive data is removed from the cache.
refetchOnMount	bool	true	Whether to refetch if data is stale when a widget mounts.
refetchOnResume	bool	true	Whether to refetch if data is stale when the app resumes focus.
retry	int	3	Number of times to retry a failed query.
retryDelay	Duration	1 sec	Base delay between retries.

Usage Examples

Disable Auto-Fetch

Use convenient explicit fetching triggers.

QueryBuilder(
  options: QueryOptions(enabled: false), // Won't fetch on mount
  // ...
)

Long-Lived Cache

Keep data fresh for a long time (e.g., config data).

QueryOptions(
  staleTime: Duration(hours: 1), // Don't refetch for 1 hour
  cacheTime: Duration(hours: 24), // Keep in memory for 24 hours
)

Aggressive Refetching

For real-time-ish data.

QueryOptions(
  staleTime: Duration.zero, // Always stale
  refetchOnResume: true,    // Refetch whenever user comes back
)