Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 38 ยท Queries and Keys

Parallel Queries and useQueries

Run several queries at once with multiple useQuery calls or useQueries for a dynamic number, merge results with combine, and know how to keep requests parallel.

A dashboard often needs three or four independent pieces of data: the user, their notifications, some statistics. Nothing says one must wait for another, so they should all start at the same time. This lesson shows how to run parallel queries, how to handle a dynamic number of queries with useQueries, and how to merge the results into one object with combine.

Several useQuery calls

The simplest way to run queries in parallel is to call useQuery more than once in the same component:

JSX
function Dashboard() {
  const user = useQuery({ queryKey: ["user"], queryFn: fetchUser });
  const stats = useQuery({ queryKey: ["stats"], queryFn: fetchStats });
  const news = useQuery({ queryKey: ["news"], queryFn: fetchNews });
  // ...
}

All three observers mount in the same render, so all three requests are sent in the same moment. The browser limits how many connections it opens per host (typically six for HTTP/1.1), but with HTTP/2 or HTTP/3 they all fly together.

Each result is independent: user can be done while stats is still loading. That lets you render the parts of the page that are ready, rather than waiting for the slowest request.

With Suspense (useSuspenseQuery), several queries in one component run one after another, because the component suspends at the first one. For parallel fetching there you use useSuspenseQueries, or prefetch earlier. Suspense Queries explains this in detail.

Showing the timeline

This demo fires three requests with different delays and prints when each one finishes. They all start at 0 ms, so the total time is that of the slowest request, not the sum.

Three requests in parallel

The slowest request takes about 800 ms and the page is complete at that moment. In sequence it would have taken about 1600 ms.

useQueries: a dynamic number of queries

Hooks cannot be called in a loop or conditionally, so you cannot write ids.map((id) => useQuery(...)). For a list whose length is only known at runtime, use useQueries. It takes an array of ordinary query options and returns an array of results in the same order.

JSX
const results = useQueries({
  queries: ids.map((id) => ({
    queryKey: ["user", id],
    queryFn: () => fetchUser(id),
  })),
});

// results[0].data, results[1].isPending ...

Each entry has its own cache entry and its own status, so if ids grows from [1, 2] to [1, 2, 3], only user 3 is fetched.

Merging results with combine

An array of result objects is awkward to render. The combine option receives the array of results and returns whatever shape you like. Query structurally shares the combined value, so your component re-renders only when the combined output changes.

useQueries with combine

Click "Add next user" twice. User 3 loads and is added to the list, while the earlier users stay untouched in the cache. Adding the fourth shows the failure counter.

Tips for combine:

  • Keep it a pure function of the results. It may run on every render.
  • A stable function reference helps performance; defining it outside the component, or wrapping it in useCallback, avoids re-running it needlessly when nothing changed.
  • combine is also a neat place to compute "all loaded" flags: results.every((r) => r.isSuccess).

Parallel versus dependent

Choose by asking, "does request B need something from the response of A?"

  • No means parallel: separate useQuery calls, or useQueries.
  • Yes means dependent: use enabled, as in Dependent Queries, and try to cut the dependency on the server if you can.
  • A mix is common: fetch user and settings in parallel, then fetch the projects that depend on the user.

A note on shared work

Because identical keys are deduplicated, you can place the same query in several components without worrying about duplicated requests, as you saw in QueryClient and QueryClientProvider. Use this: let each component declare the data it needs, and Query makes sure the work is done once. That is usually cleaner than fetching everything in a parent and passing it down through props.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Three useQuery calls in one component, no dependencies between them. How do they run?

    All observers mount in the same render, so all requests start together.
  2. 2. Why can't you call useQuery inside ids.map(...)?

    The rules of hooks forbid a variable number of hook calls. useQueries exists for this case.
  3. 3. What does useQueries return when no combine option is given?

    You get one result per query, in order. combine lets you reshape that array.
  4. 4. What is combine best used for?

    It receives all results and returns your own shape, such as lists and counters.

Summary

  • Independent queries run in parallel automatically when several useQuery calls mount together.
  • Use useQueries when the number of queries depends on data.
  • combine turns the array of results into a single, render-friendly value.
  • Each query keeps its own cache entry, so adding an item fetches only the new one.
  • Use enabled only for true dependencies, and keep everything else parallel.

Next: select and queryOptions