Skip to main content

use_query

Function use_query 

Source
pub fn use_query<T, E, C, F, Fut>(
    options: impl Into<QueryOptions>,
    fetcher: F,
    cx: &mut Context<'_, C>,
) -> (Entity<QueryResource<T, E>>, Subscription)
where T: Clone + Send + Sync + 'static, E: Clone + Send + Sync + Debug + 'static, C: 'static, F: Fn(QuerySignal) -> Fut + Send + 'static, Fut: Future<Output = Result<T, E>> + Send + 'static,
Available on crate feature hook only.
Expand description

Subscribe to a query resource and automatically re-render when it changes.

This is the primary use_query hook following the v2 “Signal-always” design: the fetcher receives a QuerySignal for cooperative cancellation.

Call this in your component’s constructor (not in render). It:

  1. Gets or creates a QueryResource entity from the global QueryClient
  2. Sets up a QueryObserver so your component re-renders on state changes
  3. Propagates the user’s retry policy to the resource entity (audit fix #16)
  4. Calls begin_request to set status to Loading and obtain a RequestId
  5. Spawns an async fetch with retry logic, using the stored RequestId

§Returns

A tuple of (Entity<QueryResource<T, E>>, Subscription):

  • Store the entity to read state during render
  • Store the subscription to keep the observation alive

§Unmount Behavior (Audit Finding #6)

If the component unmounts while a fetch is in-flight, the fetch result is silently discarded. No callback fires. This is intentional for cache-layer correctness. Callers who need completion guarantees should use fetch_query_with_signal directly with their own completion handling.