API Reference

A compact index of the public surface, grouped by the crate's three layers. Import hooks and common types from the crate root; import layer-specific items from gpui_query::core, gpui_query::client, or gpui_query::hook.

// Hooks and common types at the crate root:
use gpui_query::{
    use_query, use_mutation, use_infinite_query, use_query_select,
    QueryOptions, InfiniteQueryOptions, MutationOptions, MutationCallbacks,
    QueryKey, QueryKeyFilter, QueryError, QueryErrorKind, QueryStatus,
    CachePolicy, RequestPolicy, RetryPolicy, QueryClient,
};

core — Serde-only state machine

The core layer has no GPUI dependency. Everything here is Serialize + Deserialize (unless noted) and safe to persist.

Keys and filters

Item	Kind	Notes
QueryKey	struct	Hierarchical cache key, Arc<[Arc<str>]>-backed.
QueryKeyFilter	enum	Exact(&k) / Prefix(&k) / All. Used by bulk ops.

Policies and status

Item	Kind	Notes
CachePolicy	enum	NoCache / Ttl { ttl_ms } / StaleWhileRevalidate { ttl_ms, stale_ms }.
RequestPolicy	enum	LatestWins (default) / IgnoreWhileLoading.
RetryPolicy	struct	max_retries, retry_delay_ms, exponential_backoff, max_retry_delay_ms.
QueryStatus	enum	Idle / LoadingEmpty / LoadingWithData / Success / Failure / Cancelled.
MutationStatus	enum	Idle / Loading / Success / Failure.
QueryFetchMode	enum	Normal / Force.
QueryBeginResult	enum	Started / CacheHit / StaleCacheHit / IgnoredWhileLoading.
RequestId	struct	Monotonic per-resource request id.
QuerySignal	struct	Cooperative-cancellation signal handed to fetchers.

Errors

Item	Kind	Notes
QueryError	struct	Default error type. Display + Error, Arc<str> message. Constructors: response / transport / cancelled / unknown / sanitized.
QueryErrorKind	enum	Cancelled / Response / Transport / Unknown.

Resources

Item	Kind	Notes
QueryResource<T, E>	struct	The core cached resource. Accessors: data, error, status, key, cache_policy, retry_count, last_updated_at_ms, …
MutationResource<V,T,E>	struct	One mutation's lifecycle.
InfiniteQueryResource<T,E>	struct	Pages + pagination state. pages, page_count, has_next_page, is_fetching_next_page, …
SelectTransform<T, U>	struct	Fn(&T) -> U wrapper for derived views.
MappedQueryResource<T,U,E>	struct	A derived view applying a SelectTransform.

client — GPUI registry

Item	Kind	Notes
QueryClient	struct	Global registry. resource, query, get_query_data, set_query_data, with_query_data, invalidate_queries, cancel_queries, reset_queries, remove_queries, prepare_fetch_query, prepare_prefetch_query, gc, gc_with_time, diagnostics, dehydrate, hydrate, persist, restore.
Observer<R>	struct	Generic status-deduplicating observer.
QueryObserver<T,E>	alias	Observer<QueryResource<T, E>>.
InfiniteQueryObserver<T,E>	alias	Observer<InfiniteQueryResource<T, E>>.
MutationObserver<V,T,E>	alias	Observer<MutationResource<V, T, E>>.
ObserverConfig	struct	notify_on_status_change_only (default true).
QueryPersister	trait	load() -> Vec<DehydratedEntry>, save(Vec<DehydratedEntry>).
PreparedFetch<T,E>	struct	Imperative fetch handle: entity, signal, request_id, now_ms.
QueryDiagnostic / MutationDiagnostic / ClientDiagnostic	structs	DevTools snapshot types.
DehydratedState / DehydratedEntry	structs	Cache snapshot for persistence.

hook — Ergonomic subscriptions

All hooks return (Entity<Resource>, Subscription) (or a triple for use_query_select). Store both.

Item	Returns	Notes
use_query	(Entity<QueryResource<T,E>>, Subscription)	Primary query hook, signal-always.
use_query_manual / _opts	same	Lower-level: explicit params.
use_query_unsignalled / _opts	same	Fetcher takes no signal (legacy).
use_query_select	(Entity<MappedQueryResource<T,U,E>>, Entity<QueryResource<T,E>>, (Subscription, Subscription))	select pattern.
use_infinite_query	(Entity<InfiniteQueryResource<T,E>>, Subscription)	Pagination / load-more.
fetch_next_page_infinite	()	Grow an infinite query forward.
fetch_previous_page_infinite	()	Grow an infinite query backward.
fetch_query / fetch_query_with_signal	()	Refetch on demand.
use_mutation	(Entity<MutationResource<V,T,E>>, Subscription)	Primary mutation hook.
use_mutation_state	Vec<Entity<MutationResource<V,T,E>>>	All mutations of a type triple.
mutate	()	Trigger with owned V.
mutate_with_callbacks	()	Trigger + lifecycle callbacks.
mutate_by_ref	()	Trigger, mutator borrows &V.
mutate_arc	()	Trigger with shared Arc<V>.

Feature flags

The three layers are gated behind feature flags so you can compile only what you need:

Flag	Enables
core	The Serde-only state machine (no GPUI dep).
client	QueryClient, observers, persister, devtools.
hook	use_query / use_mutation / use_infinite_query and friends.

docsrs enables #[doc(cfg(...))] gating on docs.rs builds so the rendered API docs annotate each item with its feature gate.

Next steps

• The detailed pages in the sidebar cover each of these in depth — start with Queries.
• For the full item-level documentation, build the Rust API docs with cargo doc -p gpui-query --open.