Struct QueryOptions 

pub struct QueryOptions {
    pub key: QueryKey,
    pub cache_policy: CachePolicy,
    pub request_policy: RequestPolicy,
    pub retry_policy: RetryPolicy,
    pub gc_time_ms: u64,
    pub keep_previous_data: bool,
    pub force_fetch: bool,
    pub refetch_on_mount: RefetchTrigger,
    pub refetch_on_window_focus: RefetchTrigger,
    pub refetch_on_reconnect: RefetchTrigger,
}

Available on crate feature hook only.

Options for use_query and fetch_query.

Quick Start

use gpui_query::QueryOptions;
use gpui_query::core::{CachePolicy, RetryPolicy};
use gpui_query::hook::use_query;

// Simplest: just a string key
let result = use_query("users", |signal| async move {
    Ok::<Vec<User>, MyError>(vec![])
}, cx);

// With options:
let result = use_query(
    QueryOptions::new("users")
        .cache_policy(CachePolicy::Ttl { ttl_ms: 300_000 })
        .retry_policy(RetryPolicy::new(5)),
    |signal| async move {
        Ok::<Vec<User>, MyError>(vec![])
    },
    cx,
);

Fields

key: QueryKey

The query key. Can be a string or multi-segment key.

cache_policy: CachePolicy

Cache policy. Default: Ttl { ttl_ms: 60_000 }.

request_policy: RequestPolicy

Request policy. Default: LatestWins.

retry_policy: RetryPolicy

Retry policy. Default: 3 retries with exponential backoff.

gc_time_ms: u64

GC time in milliseconds. Default: 300_000 (5 minutes).

Reserved / forward-compat (audit fix #80): settable via the .gc_time(ms) builder, but not yet consumed by use_query, fetch_query, or the bucket layer. Garbage collection currently runs off the global GC time set via [QueryClient::with_gc_time]; this per-query value is stored only so a future release can honor it without a breaking API change. Setting it has no effect today.

keep_previous_data: bool

Whether to keep previous data when the key changes.

Reserved / forward-compat (audit fix #80): settable via the .keep_previous() builder, but not yet consumed by use_query or use_query_manual. The placeholderData/keepPreviousData behavior is not yet implemented; the field is stored so a future release can honor it without a breaking API change. Setting it has no effect today.

force_fetch: bool

Whether to force a fetch (ignore cache).

When true, use_query passes QueryFetchMode::Force to begin_request, bypassing cache freshness checks and always starting a new fetch.

refetch_on_mount: RefetchTrigger

Refetch on mount trigger.

Reserved / forward-compat (audit fix #80): settable on the struct, but not yet consumed. The GPUI event-system integration for automatic refetching on component mount is not yet implemented; the field is stored so a future release can honor it without a breaking API change. Setting it has no effect today.

refetch_on_window_focus: RefetchTrigger

Refetch on window focus trigger.

Reserved / forward-compat (audit fix #80): settable on the struct, but not yet consumed. The GPUI event-system integration for automatic refetching on window focus is not yet implemented; the field is stored so a future release can honor it without a breaking API change. Setting it has no effect today.

refetch_on_reconnect: RefetchTrigger

Refetch on reconnect trigger.

Reserved / forward-compat (audit fix #80): settable on the struct, but not yet consumed. The GPUI event-system integration for automatic refetching on reconnect is not yet implemented; the field is stored so a future release can honor it without a breaking API change. Setting it has no effect today.

Implementations

impl QueryOptions

pub fn new(key: impl Into<QueryKey>) -> Self

Create options with just a key.

pub fn force(self) -> Self

Force a fetch, ignoring cache.

When set, use_query passes QueryFetchMode::Force to begin_request, which bypasses cache freshness checks and always starts a new fetch.

pub fn keep_previous(self) -> Self

Keep previous data when the key changes.

Reserved / forward-compat (audit fix #80): sets the keep_previous_data field, which is not yet consumed by use_query or use_query_manual. The keepPreviousData behavior is intended for a future release (preserve the prior data/previous_data slot across a key change so the component keeps rendering the last successful result while the new fetch is in flight). The builder is provided now so callers can opt in without a future API change; calling it has no effect today.

impl QueryOptions

pub fn cache_policy(self, policy: CachePolicy) -> Self

Set the cache policy.

pub fn request_policy(self, policy: RequestPolicy) -> Self

Set the request policy.

pub fn retry_policy(self, policy: RetryPolicy) -> Self

Set the retry policy.

pub fn gc_time(self, ms: u64) -> Self

Set the GC time in milliseconds.

Trait Implementations

impl Clone for QueryOptions

fn clone(&self) -> QueryOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QueryOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for QueryOptions

fn default() -> Self

Returns the “default value” for a type.

impl From<&str> for QueryOptions

fn from(key: &str) -> Self

Converts to this type from the input type.

impl From<(QueryKey, CachePolicy, RequestPolicy)> for QueryOptions

Build QueryOptions from a raw (key, cache_policy, request_policy) triple.

Audit fix #79: this lets use_query_manual_opts / use_query_unsignalled_opts accept callers that already hold the legacy raw-parameter triple without forcing them to spell out QueryOptions::new. Non-breaking: the existing constructors and From impls are untouched.

fn from( (key, cache_policy, request_policy): (QueryKey, CachePolicy, RequestPolicy), ) -> Self

Converts to this type from the input type.

impl From<QueryKey> for QueryOptions

fn from(key: QueryKey) -> Self

Converts to this type from the input type.

impl From<String> for QueryOptions

fn from(key: String) -> Self

Converts to this type from the input type.