# Guides

> Every query_kit guide in one list, grouped by task: reading queries, refetching and the network, paging, mutations, the cache and tools.

Each guide explains one concept, with the code to use it and the traps around
it. This page lists them all, grouped as the sidebar groups them. If you have
not set up a project yet, start with the [quick start](https://query-kit.dualmeta.io/docs/quick-start.md).

## Queries

- [Queries](https://query-kit.dualmeta.io/docs/guides/queries.md): what a query is, the three result states, `status`
  versus `fetchStatus`, and the flags that combine them.
- [Four ways to read a query](https://query-kit.dualmeta.io/docs/guides/reading-queries-in-widgets.md): `context.query`,
  `QueryBuilder`, `QueryMixin` and `QueryController`, how to pick between them,
  and when a read is released.
- [Hooks](https://query-kit.dualmeta.io/docs/guides/hooks.md): the optional `query_kit_hooks` add-on, with `useQuery`,
  `useMutation` and the rest of React Query's hooks on `flutter_hooks`.
- [Query keys](https://query-kit.dualmeta.io/docs/guides/query-keys.md): `QueryKey` as a value type, hierarchical keys,
  prefix matching and key factories.
- [Query functions](https://query-kit.dualmeta.io/docs/guides/query-functions.md): a function that returns a `Future` and
  throws on failure, the error types a retry policy can read, and what the
  function's context carries.
- [Describing a query once](https://query-kit.dualmeta.io/docs/guides/query-options.md): options functions, the two
  observer options shapes, `withSelect`, and what `null` means.
- [Parallel queries](https://query-kit.dualmeta.io/docs/guides/parallel-queries.md): several queries at once, and
  `QueriesBuilder` for a list that changes length or order.
- [Combining queries](https://query-kit.dualmeta.io/docs/guides/combining-queries.md): `combine` over a record or a list
  of results, and the rules for pending, error and data.
- [Dependent queries](https://query-kit.dualmeta.io/docs/guides/dependent-queries.md): a query that waits for another
  query's result with `enabled`, and why it is still a waterfall.
- [Disabling queries](https://query-kit.dualmeta.io/docs/guides/disabling-queries.md): `Enabled.no`, a query run only on
  demand, and what a disabled query still does.
- [Side effects](https://query-kit.dualmeta.io/docs/guides/side-effects.md): navigation, snackbars and analytics on a
  change of a result, with the listener widgets and mutation callbacks.

## Refetching and the network

- [Background fetching indicators](https://query-kit.dualmeta.io/docs/guides/background-fetching-indicators.md): showing
  that a query is refreshing without hiding its data, for one result or for the
  whole app.
- [App focus refetching](https://query-kit.dualmeta.io/docs/guides/window-focus-refetching.md): stale queries refetch
  when the user returns to the app, and how to narrow or turn that off.
- [Network mode and offline](https://query-kit.dualmeta.io/docs/guides/network-mode.md): what queries and mutations do
  while the client believes it is offline, and how they resume.
- [Connectivity](https://query-kit.dualmeta.io/docs/guides/connectivity.md): telling the client whether it is online,
  with `OnlineStatus`, a `connectivity_plus` adapter and a reachability probe.
- [Polling](https://query-kit.dualmeta.io/docs/guides/polling.md): `refetchInterval`, polling in the background, and
  stopping when the server confirms.
- [Query retries](https://query-kit.dualmeta.io/docs/guides/query-retries.md): `RetryPolicy` and `RetryDelay`, not
  retrying a 4xx, and showing the attempts in the UI.
- [Query cancellation](https://query-kit.dualmeta.io/docs/guides/query-cancellation.md): the `QueryCancelToken` every
  query function receives, and what `cancelQueries` and a leaving screen do to
  a fetch in flight.

## Paging and early data

- [Paginated queries](https://query-kit.dualmeta.io/docs/guides/paginated-queries.md): one page at a time with the page
  number in the key, and a prefetch that makes *Next* instant.
- [Infinite queries](https://query-kit.dualmeta.io/docs/guides/infinite-queries.md): a list of pages behind one key,
  `maxPages`, and load-on-scroll.
- [Initial query data](https://query-kit.dualmeta.io/docs/guides/initial-query-data.md): seeding the cache with data the
  app already has, and saying how old it is.
- [Placeholder query data](https://query-kit.dualmeta.io/docs/guides/placeholder-query-data.md): data shown while the
  real fetch runs and never written to the cache.
- [Scroll restoration](https://query-kit.dualmeta.io/docs/guides/scroll-restoration.md): a list comes back where it was,
  and what Flutter needs from you to put the position back.

## Mutations

- [Mutations](https://query-kit.dualmeta.io/docs/guides/mutations.md): the four ways to read a mutation, `mutate` and
  `mutateAsync`, per-call callbacks and mutation defaults.
- [Query invalidation](https://query-kit.dualmeta.io/docs/guides/query-invalidation.md): `invalidateQueries`, prefix
  matching, `exact`, predicates and `refetchType`.
- [Invalidations from mutations](https://query-kit.dualmeta.io/docs/guides/invalidations-from-mutations.md): which keys
  to invalidate after a write, from which callback, and what returning the
  future does.
- [Updates from mutation responses](https://query-kit.dualmeta.io/docs/guides/updates-from-mutation-responses.md):
  writing what a mutation returned straight into the cache.
- [Optimistic updates](https://query-kit.dualmeta.io/docs/guides/optimistic-updates.md): showing a write before the
  server confirms it, from the pending variables or by patching the cache.
- [Mutation scopes](https://query-kit.dualmeta.io/docs/guides/mutation-scopes.md): mutations that share a scope run one
  at a time, in the order they were started.
- [Cancelling mutations](https://query-kit.dualmeta.io/docs/guides/cancelling-mutations.md): `mutationFnWithContext`, and
  why cancelling a write fails it rather than reverting it.
- [Mutation state](https://query-kit.dualmeta.io/docs/guides/mutation-state.md): every mutation matching a filter, for a
  "saving…" badge no widget owns.

## The cache and performance

- [Filters](https://query-kit.dualmeta.io/docs/guides/filters.md): `QueryFilters` and `MutationFilters`, the one named
  argument every bulk operation takes.
- [Request waterfalls](https://query-kit.dualmeta.io/docs/guides/request-waterfalls.md): when one request cannot start
  before another has answered, and how hoisting and prefetching avoid it.
- [Prefetching](https://query-kit.dualmeta.io/docs/guides/prefetching.md): fetching with `client.query` before a screen
  asks, or serving the cache and revalidating behind it.
- [Caching](https://query-kit.dualmeta.io/docs/guides/caching.md): how long data is fresh, how long an unobserved entry
  is kept, and a query's life from first read to garbage collection.
- [What rebuilds, and when](https://query-kit.dualmeta.io/docs/guides/render-optimizations.md): `select` narrows what a
  widget reads and `buildWhen` narrows when it rebuilds.
- [Structural sharing](https://query-kit.dualmeta.io/docs/guides/structural-sharing.md): a refetch that brings back equal
  data keeps the cached instances, and how a model takes part.
- [Default query function](https://query-kit.dualmeta.io/docs/guides/default-query-function.md): registering a query
  function per key prefix with `setQueryDefaults`.
- [Global callbacks](https://query-kit.dualmeta.io/docs/guides/global-callbacks.md): `QueryCache` and `MutationCache`
  callbacks that run for every query or mutation of a client.

## Tools and architecture

- [Debugging](https://query-kit.dualmeta.io/docs/guides/debugging.md): there are no devtools, so what the cache can tell
  you by its events and entries instead.
- [Testing](https://query-kit.dualmeta.io/docs/guides/testing.md): the teardown every widget test needs, a harness that
  wraps it, and the pump rules that fake timers impose.
- [Without Flutter](https://query-kit.dualmeta.io/docs/guides/pure-dart.md): using `query_kit` on its own, with observers
  and `subscribe`.
- [Does this replace state management?](https://query-kit.dualmeta.io/docs/guides/does-this-replace-state-management.md):
  what moves into the cache and what stays in your state package.

## Beyond the guides

The guides explain concepts one at a time. The [cookbook](https://query-kit.dualmeta.io/docs/cookbook.md)
starts from tasks such as a token refresh or a search box and puts several
guides to work in one app, and the [examples](https://query-kit.dualmeta.io/docs/examples.md) run every
feature as a live screen. [Important defaults](https://query-kit.dualmeta.io/docs/important-defaults.md) and
the [API reference](https://query-kit.dualmeta.io/docs/reference/api.md) sit beside them.