API to trigger queryKeyHashFn recalculation for active observers (multi-tenant context switching)

[dbssman]

Use Case

Multi-tenant application where users can switch tenant context without navigating away (e.g., tenant switcher dropdown). We use queryKeyHashFn to transparently scope queries by user and tenant:

  const queryKeyHashFn = (queryKey: QueryKey) => {
    const tenant = tenantService.getTenant()
    return hashKey(['tenant', tenant, ...queryKey])
  }

This gives us context-agnostic query definitions that work across different tenants without explicitly adding tenant to every queryKey.

The Problem

When tenant changes mid-session, active observers still have their cached queryHash. There's no official API to trigger hash recalculation.

Current Workaround

We force recalculation by calling setOptions without queryHash or _defaulted:

  for (const query of queryClient.getQueryCache().getAll()) {
    for (const observer of query.observers) {
      const { queryHash, _defaulted, ...options } = observer.options
      observer.setOptions(options)
    }
  }

This works because setOptions recomputes the hash when not provided, but it relies on internal behavior (_defaulted causing early return in defaultQueryOptions).

Proposal

An official API to rescope active observers, e.g.:

  queryClient.rescopeQueries()
  // or
  queryCache.rehashObservers()

Alternatives Considered

Approach	Downside
Include tenant in queryKey explicitly	Verbose, loses context-agnostic reusability
Clear cache on context change	Defeats caching purpose
Multiple QueryClients per tenant	Bad when you have global queries cached (with no context)
Force UI rerender	Unnecessary remounts, loses component state

Question

Is there an official/recommended way to handle this? Or would a new API be considered for this use case?

[TkDodo]

I’m wondering - if the user switches tenant and this doesn’t re-render the active components, how are they getting new data? And if the tenantId isn’t part of the QueryKey, how is the queryFn returning different data even if it runs?

I’m guessing the affected components do re-render because they are somehow subscribed to those tenantId changes, or maybe the whole component tree re-renders top-down, but the second part of the question still stands: How is the tenantId passed to the backend then?

The point I’m trying to get towards is that using a different hash wasn’t meant to let you bypass explicit dependencies (and making them implicit). We have the hashing API to allow users to store non-json-serializable things in the QueryKey, so that they can provide their own hashing.