Handle pushed down predicates in query collection #646
main fromrefs/pull/646/head·opened Stacked on: #669
Overview#
This PR extends Query Collections to support predicate pushdown from live queries by enabling multiple concurrent queries with different predicates/filters. When live queries push down predicates via loadSubset, Query Collections now create separate TanStack Query instances for each unique set of options, pass those options to both the query key builder and query function, and manage the lifecycle of multiple queries with proper reference counting and garbage collection.
Problem#
When live queries push down predicates (via loadSubset), Query Collections need to:
- Pass
LoadSubsetOptions(predicates, limits, ordering) to the query key builder and query function - Create separate TanStack Query instances for each unique set of options
- Track which rows belong to which queries (reference counting)
- Only remove rows when no active queries reference them
- Handle query garbage collection when queries are no longer needed
- Return promises that resolve when query data is first available
Without this, Query Collections couldn't properly support the on-demand sync mode introduced in #669.
Solution#
This PR implements a comprehensive multi-query management system that flows predicates from live queries through to your TanStack Query implementation:
Predicate Flow#
When a live query calls loadSubset with predicates, those options flow through the system:
- Live Query → calls
collection._sync.loadSubset(options) - Query Collection → calls
createQueryFromOpts(options) - Query Key Builder → receives
optionsto create unique query key - Query Function → receives
optionsviacontext.meta.loadSubsetOptions
Example Usage#
import { createCollection } from "@tanstack/react-db"
import { queryCollectionOptions } from "@tanstack/query-db-collection"
const itemsPerPage = 20
export const todoCollection = createCollection(
queryCollectionOptions({
syncMode: 'on-demand', // Enable predicate pushdown
// Query key builder receives LoadSubsetOptions
queryKey: ({ limit, orderBy, where }) => {
const page = computePageNumber(limit ?? itemsPerPage)
return ["todos", { page, where, orderBy }]
},
// Query function receives options via context.meta.loadSubsetOptions
queryFn: async (ctx) => {
const { limit, where, orderBy } = ctx.meta?.loadSubsetOptions ?? {}
const page = computePageNumber(limit ?? itemsPerPage)
const params = new URLSearchParams({
page: page.toString(),
...(where && { filter: JSON.stringify(where) }),
...(orderBy && { sort: JSON.stringify(orderBy) }),
})
const res = await fetch(`/api/todos?${params}`)
if (!res.ok) throw new Error("Failed to fetch todos")
return res.json()
},
getKey: (item) => item.id,
schema: todoSchema,
})
)
function computePageNumber(limit: number): number {
return Math.max(1, Math.ceil(limit / itemsPerPage))
}
In this example:
- The
queryKeyfunction builds different cache keys based on page/filters - The
queryFnreceives the same options viactx.meta.loadSubsetOptionsto fetch the right data - Each unique combination of predicates creates a separate TanStack Query
- Rows are reference-counted across all queries
1. Dynamic Query Keys#
Type: Added TQueryKeyBuilder<TQueryKey> type
type TQueryKeyBuilder<TQueryKey> = (opts: LoadSubsetOptions) => TQueryKey
interface QueryCollectionConfig {
queryKey: TQueryKey | TQueryKeyBuilder<TQueryKey>
// ... other properties
}
The queryKey config option now accepts either:
- A static query key (for eager mode with no predicates)
- A function that builds a query key from
LoadSubsetOptions(for on-demand mode with predicate pushdown)
LoadSubsetOptions Structure:
interface LoadSubsetOptions {
where?: any // Filter predicates
orderBy?: any // Ordering directives
limit?: number // Result limit
offset?: number // Result offset
}
2. Meta Property Extension#
When creating a query, the collection merges LoadSubsetOptions into the query's meta:
const extendedMeta = { ...meta, loadSubsetOptions: opts }
const observerOptions = {
queryKey: key,
queryFn: queryFn,
meta: extendedMeta, // Contains loadSubsetOptions
// ... other options
}
Your queryFn can then access these options via context.meta.loadSubsetOptions to fetch the appropriate data.
3. Multi-Query Tracking System#
Implemented comprehensive state tracking using Maps:
// hashedQueryKey → QueryKey
const hashToQueryKey = new Map<string, QueryKey>()
// hashedQueryKey → Set<RowKey> (which rows belong to which query)
const queryToRows = new Map<string, Set<string | number>>()
// RowKey → Set<hashedQueryKey> (which queries reference each row)
const rowToQueries = new Map<string | number, Set<string>>()
// hashedQueryKey → QueryObserver (active query observers)
const observers = new Map<string, QueryObserver>()
// hashedQueryKey → unsubscribe function
const unsubscribes = new Map<string, () => void>()
Reference Counting: Rows are only deleted from the collection when their reference count drops to zero (no queries reference them anymore).
4. createQueryFromOpts Function#
New internal function that creates or reuses queries based on LoadSubsetOptions:
Return Type: true | Promise<void>
- Returns
truesynchronously if query data is already available - Returns
Promise<void>that resolves when query data loads - Returns
Promise<void>that rejects if query encounters an error
Behavior:
- Hashes the query key (built from options) to check for existing queries
- Reuses existing
QueryObserverinstances when the same predicates are requested - Creates new observers for unique predicate combinations
- Passes options to both query key builder and query function (via
meta.loadSubsetOptions) - Automatically subscribes if sync has started or collection has subscribers
5. Query Garbage Collection#
Listens to TanStack Query's cache events to handle query removal:
queryClient.getQueryCache().subscribe((event) => {
if (event.type === 'removed') {
cleanupQuery(hashedKey)
}
})
Cleanup Process:
- Decrements reference counts for all rows in the removed query
- Deletes rows when reference count reaches zero
- Cleans up observer and unsubscribe function
- Removes query from all tracking Maps
6. Sync Mode Integration#
Eager Mode (default):
- Creates single initial query with empty options (
{}) - Bypasses
loadSubset(returnsundefined) - Static query key (no builder function needed)
On-Demand Mode:
- No initial query created
- Calls
markReady()immediately since there's nothing to wait for - Creates queries dynamically as
loadSubset(options)is called - Requires query key builder function to handle different predicates
- Returns
createQueryFromOptsdirectly as theloadSubsetimplementation
Sync Started Tracking:
Added syncStarted flag to determine when to subscribe to new queries:
- Set to
truewhen sync begins (viapreload(),startSync, or first subscriber) - Used instead of checking
config.startSyncto handle all sync scenarios
Changes#
Files Modified:
packages/query-db-collection/src/query.ts- Core implementation (+354 lines)packages/query-db-collection/tests/query.test.ts- Comprehensive test suite (+567 lines).changeset/silent-trains-tell.md- Changeset entry
Test Coverage:
- Added 4 new tests for Query Garbage Collection scenarios
- Added test for
preload()in on-demand mode - All 64 tests passing
- Code coverage: 88.66% lines
Key Features#
✅ Predicate Pushdown - Pass LoadSubsetOptions from live queries to TanStack Query
✅ Multiple Concurrent Queries - Manage multiple TanStack Query instances with different predicates
✅ Reference Counting - Track which queries reference which rows
✅ Automatic Garbage Collection - Clean up queries and rows when no longer needed
✅ Promise-Based Loading - Return promises that resolve when data is available
✅ Sync Mode Support - Works with both eager and on-demand sync modes
✅ Immediate Ready State - On-demand collections transition to ready immediately
Breaking Changes#
None - this is a backward-compatible extension. Existing Query Collections with static query keys continue to work as before.
Migration Guide#
If you want to enable predicate pushdown:
- Set
syncMode: 'on-demand' - Change
queryKeyfrom a static value to a builder function - Access predicates in
queryFnviacontext.meta.loadSubsetOptions
Before:
queryCollectionOptions({
queryKey: ['todos'],
queryFn: async () => fetch('/api/todos').then(r => r.json()),
// ...
})
After:
queryCollectionOptions({
syncMode: 'on-demand',
queryKey: ({ where, limit, orderBy }) => ['todos', { where, limit, orderBy }],
queryFn: async (ctx) => {
const { where, limit } = ctx.meta?.loadSubsetOptions ?? {}
const params = new URLSearchParams()
if (where) params.set('filter', JSON.stringify(where))
if (limit) params.set('limit', limit.toString())
return fetch(`/api/todos?${params}`).then(r => r.json())
},
// ...
})
Related#
- Builds on #669 (loadSubset state tracking and on-demand sync mode)
- Enables live queries to efficiently push down predicates to Query Collections
- Prepares for framework hook integration in follow-up PRs
- 1
More templates
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@646@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@646@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@646@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@646@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@646@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@646@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@646@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@646@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@646@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@646@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@646commit:
65c076fSize Change: 0 B
Total Size: 83.6 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size ./packages/db/dist/esm/collection/change-events.js963 B ./packages/db/dist/esm/collection/changes.js1.01 kB ./packages/db/dist/esm/collection/events.js413 B ./packages/db/dist/esm/collection/index.js3.23 kB ./packages/db/dist/esm/collection/indexes.js1.16 kB ./packages/db/dist/esm/collection/lifecycle.js1.8 kB ./packages/db/dist/esm/collection/mutations.js2.52 kB ./packages/db/dist/esm/collection/state.js3.79 kB ./packages/db/dist/esm/collection/subscription.js2.2 kB ./packages/db/dist/esm/collection/sync.js2.2 kB ./packages/db/dist/esm/deferred.js230 B ./packages/db/dist/esm/errors.js3.57 kB ./packages/db/dist/esm/event-emitter.js798 B ./packages/db/dist/esm/index.js1.65 kB ./packages/db/dist/esm/indexes/auto-index.js794 B ./packages/db/dist/esm/indexes/base-index.js835 B ./packages/db/dist/esm/indexes/btree-index.js2 kB ./packages/db/dist/esm/indexes/lazy-index.js1.21 kB ./packages/db/dist/esm/indexes/reverse-index.js577 B ./packages/db/dist/esm/local-only.js967 B ./packages/db/dist/esm/local-storage.js2.33 kB ./packages/db/dist/esm/optimistic-action.js294 B ./packages/db/dist/esm/proxy.js3.86 kB ./packages/db/dist/esm/query/builder/functions.js615 B ./packages/db/dist/esm/query/builder/index.js4.04 kB ./packages/db/dist/esm/query/builder/ref-proxy.js938 B ./packages/db/dist/esm/query/compiler/evaluators.js1.55 kB ./packages/db/dist/esm/query/compiler/expressions.js760 B ./packages/db/dist/esm/query/compiler/group-by.js2.04 kB ./packages/db/dist/esm/query/compiler/index.js2.21 kB ./packages/db/dist/esm/query/compiler/joins.js2.65 kB ./packages/db/dist/esm/query/compiler/order-by.js1.43 kB ./packages/db/dist/esm/query/compiler/select.js1.28 kB ./packages/db/dist/esm/query/ir.js785 B ./packages/db/dist/esm/query/live-query-collection.js404 B ./packages/db/dist/esm/query/live/collection-config-builder.js5.49 kB ./packages/db/dist/esm/query/live/collection-registry.js233 B ./packages/db/dist/esm/query/live/collection-subscriber.js2.11 kB ./packages/db/dist/esm/query/optimizer.js3.26 kB ./packages/db/dist/esm/scheduler.js1.29 kB ./packages/db/dist/esm/SortedMap.js1.24 kB ./packages/db/dist/esm/transactions.js3.05 kB ./packages/db/dist/esm/utils.js1.01 kB ./packages/db/dist/esm/utils/browser-polyfills.js365 B ./packages/db/dist/esm/utils/btree.js6.01 kB ./packages/db/dist/esm/utils/comparison.js754 B ./packages/db/dist/esm/utils/index-optimization.js1.73 kB Size Change: 0 B
Total Size: 2.36 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size ./packages/react-db/dist/esm/index.js168 B ./packages/react-db/dist/esm/useLiveInfiniteQuery.js885 B ./packages/react-db/dist/esm/useLiveQuery.js1.31 kB Closing this PR and reopening with a rebased branch to remove duplicate commits from #669 that are already in main. New PR incoming...
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
🦋 Changeset detected#
Latest commit: 65c076ff8b4b40451369872ba97e89bf9c9a0e5a
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 2 packages
Not sure what this means? Click here to learn what changesets are.
Click here if you're a maintainer who wants to add another changeset to this PR