`useQueries` hook: Support for dynamically executing multiple queries at runtime

[ItaiYosephi]

We're implementing a feature in our application that requires executing multiple GraphQL queries that are determined at runtime. Currently, Apollo Client doesn't provide a clean way to handle this use case.

We'd like to propose adding a useQueries hook that would allow for elegant handling of multiple dynamic queries, similar to:

const visibleSteps = STEPS.filter(isStepVisible);
const results = useQueries(
  visibleSteps.map(step => ({ 
    query: step.query, 
    variables: step.variables 
  }))
);

While there is a similar feature request (#178) the solution proposed there only addresses running the same query multiple times with different variables.

Our use case requires running completely different queries that are determined at runtime. TanStack Query (formerly React Query) already offers this functionality through their useQueries hook.

It's worth noting that while we could potentially use Apollo Client directly for this purpose, there's currently no way to utilize the cache-and-network fetch policy in such an implementation, which is a critical requirement for our application's data fetching strategy.

Adding this capability to Apollo Client would significantly improve developer experience for complex applications that need to fetch data from multiple dynamic sources simultaneously while maintaining proper caching behavior.

[jerelmiller]

Hey @ItaiYosephi 👋

We'd like to avoid this hook if at all possible. One of the advantages of GraphQL is the ability to select what you need in a single request, so we'd really prefer to encourage using a single query to fetch needed data and encourage good schema design that allows for these use cases. It's more necessary with TanStack Query since it primarily is used to call REST APIs where you might not have the ability to pull the data from a single endpoint.

I think we need a pretty convincing use case that is very difficult with a single query or good schema design before we would consider this. For example, a field in the schema that accepted a list of IDs would be enough to support the use case for querying a dynamic set of entities.

Do you have a use case to share that fits into this category?

[ItaiYosephi]

Hi @jerelmiller,

Thank you for your thoughtful response! I'd be happy to share more details about our specific use case.

We've built an interactive walkthrough page that guides users through exploring our system. This walkthrough consists of numerous steps (over 100 in total) that users need to complete. Each step is self-contained with its own GraphQL query and completion logic.

What makes our situation unique is the highly dynamic nature of the experience:

• Different users see different steps based on their tenant's licensing
• User roles further determine which steps are visible
• Each step needs to track its own loading and completion state independently

While we could theoretically create a single large query document, this approach presents several challenges:

1. Maintainability: The resulting query would be massive and difficult to maintain, especially as we continue adding steps
2. Query complexity: We'd need multiple aliases since some steps use the same query with different variables
3. User experience: A single query means a single loading state for all steps, which would significantly delay the rendering of the walkthrough
4. Encapsulation: Our architecture keeps each step's logic encapsulated, making the code more maintainable and testable
5. Conditional logic: We'd need numerous boolean variables for @include/@skip directives, further complicating the query

Our goal is to keep each step's concerns separate while still leveraging Apollo's excellent caching capabilities. The proposed useQueries hook would allow us to maintain this separation while providing a clean API for our developers.

Thanks again for considering this request!

[jerelmiller]

Could you perhaps give me some pseudo code that demonstrates how you're building the walkthrough? Are you showing more than one step at a time? Some at a time? All at the same time?

I read this and assume you're only showing one step at a time, so I think I'm missing some more context. Pseudo code would definitely help 🙂

Each step is self-contained with its own GraphQL query and completion logic... The proposed useQueries hook would allow us to maintain this separation while providing a clean API for our developers.

How would useQueries help here? If each step already loads its own query, why would you need to load multiple? These two sentences when put together read a bit contradictory to me, so please help me understand what I'm missing 🙂

[ItaiYosephi]

Hi @jerelmiller,
In our app, there are multiple modules, and each module as a list of steps.
We show an overview of all modules and a progress bar of each module (completeSteps/allSteps), something like this:

interface OnboardingStep<TQueryResult = unknown, TQueryVariables = unknown> {
  id: string;
  title: string;
  query?: TypedDocumentNode<TQueryResult, TQueryVariables>;
  queryVariables?: (context: Context) => TQueryVariables;
  completed: (data: TQueryResult) => boolean;
}

interface OnboardingModule {
  id: string;
  title: string;
  icon: IconDefinition;
  steps: OnboardingStep[];
}

// Parent component renders multiple modules
const OnboardingDashboard = () => {
  const modules = useOnboardingModules(); 
  
  return (
    <div>
      {modules.map(module => (
        <OnboardingModuleCard key={module.id} module={module} />
      ))}
    </div>
  );
};

// Each module component needs to query its own steps
const OnboardingModuleCard = ({ module }: { module: OnboardingModule }) => {
  // ❌ PROBLEM: Can't conditionally call hooks based on dynamic step configuration
  
  // Need to query each step - but steps are dynamic!
  // Can't do this:
  const stepResults = module.steps.filter(isStepVisible).map(step => {
    if (step.query) {
      // eslint-disable-next-line react-hooks/rules-of-hooks
      return useQuery(step.query, {
        variables: step.queryVariables?.(context)
      });
    }
    return null;
  });
  
  // Calculate completion status from ALL step queries
  const completedSteps = stepResults.filter((result, idx) => {
    const step = module.steps[idx];
    return result?.data && step.completed(result.data);
  });
  
  return (
    <Card>
      <h3>{module.title}</h3>
      <ProgressBar 
        value={completedSteps.length} 
        total={module.steps.length}
      />
      <Text>{completedSteps.length}/{module.setps.length} completed</Text>
    </Card>
  );
};

Here, use queries will be helpful.
In other places, we might import an individual step in other pages, and use its query an onCompleted, so in those places, we don't want to use a huge document of the whole module.

[jerelmiller]

@ItaiYosephi thank you, that is helpful. This definitely makes it clearer that its difficult to solve from a runtime perspective.

I want to bring back this point from one of my earlier comments (bolded for emphasis):

One of the advantages of GraphQL is the ability to select what you need in a single request, so we'd really prefer to encourage using a single query to fetch needed data and encourage good schema design that allows for these use cases

It's clear this is difficult to solve at the runtime level since you need array filtering and hooks don't allow for loops, but I still think this is solvable at the schema level and we'd encourage that first. Seems to me either your schema should have the ability to do something like:

query {
  module {
    id
    steps {
      # ...
    }
  }
}

or something like:

query ($stepIds: [ID!]!) {
  steps(ids: $stepIds) {
    # ...
  }

  # or the "filter"-like approach
  steps(filter: { ids: $stepIds }) {
    # ...
  }
}

---

The problem with useQueries is that it encourages many network fetches in place of good schema design. Good schema design would solve this problem and keep the client to a single network fetch which is going to be much better for performance in your app (likely the server would be able to optimize at the database layer as well instead of dealing with the network layer).

We've seen far too many cases where a certain feature of Apollo Client is abused simply because its available so we're really trying to avoid that here. I'm sorry for the amount of pushback I'm giving here, but I want to make sure what we include in Apollo Client encourages good practices for GraphQL apps.