feat(db): live query without fetching #2179
main fromrefs/pull/2179/head·opened 🎯 Changes#
Add autoLoad: false to live-query configuration to query data already in collections without fetching or syncing. Results remain reactive, with filtering, joins, and pagination handled by the existing query engine.
One use case is application-owned fetching. Some remote API requests cannot be derived correctly from the query IR. Applications need to construct those requests themselves and ingest the results into collections, without the live query triggering additional requests.
Implementation Details#
Making loadSubset a no-op is not sufficient:
- Source sync starts automatically on subscription and can fetch independently of
loadSubset. This is also suppressed whenautoLoadis disabled. - The ready state normally depends on data loading. With
autoLoad: false, it indicates that the available rows have been evaluated, even if the collection is empty. - Joins and pagination can request additional subsets or ordered pages. These requests are disabled, and the query runs over the available matching rows.
autoLoad defaults to true. Queries with different settings have separate identities, including with explicit query keys. Collection data remains shared, so updates from other queries or application code still appear in the results.
✅ Checklist#
- I have tested this code locally with
pnpm test.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Related discussion#
Summary by CodeRabbit#
New Features
- Added an
autoLoadoption for live queries and React query hooks. When disabled, queries observe and react to rows already available in their collections without starting source loading. - Queries can become ready based on available rows, independently of source loading. Switching between automatic and local observation uses a separate query identity; infinite-query pages reset when the mode changes.
- Documented how readiness, pagination, errors, and shared source loading behave with automatic loading disabled.
- Added an
Tests
- Added coverage for local observation across joins, windows, includes, loading states, and React hooks.
- 1
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
-
⚙️ Run configuration
-
- Configuration used: defaults
- Review profile: CHILL
- Plan: Advanced
- Run ID:
2f6f41e2-95ac-4f3b-935a-91ebe999f762
📥 Commits
-
Reviewing files that changed from the base of the PR and between eb739d74d04f2712043805680ca42723e76a4e56 and aee450a2773090bc686d88823bec566c6091795c.
📒 Files selected for processing: 5
-
packages/db/src/live-query-options.tspackages/db/src/query/live/collection-config-builder.tspackages/db/src/query/live/collection-subscriber.tspackages/react-db/src/useLiveInfiniteQuery.tspackages/react-db/src/useLiveQuery.ts
🚧 Files skipped from review as they are similar to previous changes: 5
-
- packages/db/src/query/live/collection-subscriber.ts
- packages/react-db/src/useLiveQuery.ts
- packages/db/src/query/live/collection-config-builder.ts
- packages/db/src/live-query-options.ts
- packages/react-db/src/useLiveInfiniteQuery.ts
Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 6 remain after this review.
-
📝 Walkthrough
-
Live queries can use
autoLoad: falseto evaluate available source rows without initiating acquisition. The change adds collection and React hook support, distinguishes loading modes in query identities, and adds oracle and integration tests plus documentation.Changes: Local Live Query Loading
Layer / File(s) Summary Configuration and query identity
.changeset/local-query-observation.md,docs/guides/live-queries.md,packages/db/src/query/live/types.ts,packages/db/src/types.ts,packages/db/src/live-query-options.tsAdds the autoLoadoption, recognizes live-query configuration objects, and distinguishes disabled-loading queries in query identity. The guide describes readiness, errors, pagination, and shared-source behavior.Observe rows without acquisition
packages/db/src/collection/changes.ts,packages/db/src/collection/subscription.ts,packages/db/src/query/live/collection-config-builder.ts,packages/db/src/query/live/collection-subscriber.ts,packages/db/src/query/live/ARCHITECTURE.mdWhen loading is disabled, subscriptions retain detached demands without acquiring source data. Live queries observe available rows and determine readiness from query evaluation rather than provider readiness. React hook mode and identity
packages/react-db/src/useLiveInfiniteQuery.ts,packages/react-db/src/useLiveQuery.ts,packages/react-db/tests/live-query-auto-load.test.tsxReact hooks track autoLoadwhen creating and reusing collections. Tests cover identity changes, local updates, Suspense separation, and infinite-query page resets when the mode changes.Oracle and integration validation
packages/db/tests/live-query-auto-load-oracle.test.ts,packages/db/tests/oracle-config.ts,packages/db/package.json,packages/query-db-collection/tests/live-query-auto-load.test.ts,docs/contributing/oracle-coverage.md,docs/contributing/oracle-reviews/2026-10-14-local-live-query.mdAdds property-based coverage across source modes, index states, and query shapes, plus a Query Collection integration test. Registers the oracle and records coverage scope and validation results. Priority: ➖ Normal
Estimated code review effort: 3 (Moderate) | ~25 minutes
Change: Feature
Sequence Diagram(s)#
sequenceDiagram participant useLiveQuery participant LiveQueryCollection participant CollectionSubscriber participant SourceCollection participant QueryPipeline useLiveQuery->>LiveQueryCollection: Create query with autoLoad false LiveQueryCollection->>CollectionSubscriber: Subscribe to source changes CollectionSubscriber->>SourceCollection: Subscribe without automatic acquisition SourceCollection-->>CollectionSubscriber: Emit available row changes CollectionSubscriber->>QueryPipeline: Forward row changes for evaluation
Merge Risk: ⚪ Minimal · up to
aee45-
The reviewed loading-mode behavior has no identified issue that needs resolution before merging.
Pre-merge checks:
4 · 1-
Failed checks: 1 warningCheck name Status Explanation Resolution Docstring Coverage Docstring coverage is 71.43% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 14 functions across 13 files. Write docstrings for the functions missing them to satisfy the coverage threshold. Passed checks: 4 passed-
Check name Status Explanation Title check The title clearly and concisely describes the main change: live queries can operate without fetching. Description check The description includes the required Changes, Checklist, and Release Impact sections. It explains the motivation, implementation behavior, testing, and changeset status. Linked Issues check Check skipped because no linked issues were found for this pull request. Out of Scope Changes check Check skipped because no linked issues were found for this pull request.
-
- Fix all pre-merge checks with AI
✨ Finishing Touches
-
🧪 Generate unit tests (beta)
-
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment `@coderabbitai help` to get the list of available commands.-
jchook(GitHub profile, opens in a new tab) changed the title
jchook(GitHub profile, opens in a new tab) changed the title
Couldn't you use local collections for data you're loading in some other way?
Couldn't you use local collections for data you're loading in some other way?
In our case, we can translate the TanStack DB query into the right remote API request about 90% of the time. For the remaining cases, we need a custom request whose results we ingest into the same shared collections.
We still want TanStack’s local query evaluation and reactivity in those cases, but without also triggering
loadSubset. So the distinction is per query. The same collection needs to support both automatic loading and custom fetching. Making the collections local-only would mean giving up automatic loading for the 90% that already works.We could move all acquisition into our own wrapper over local collections, but then we’d need to reproduce the query-to-demand planning TanStack already handles, including joins and pagination. Ideally, we’d keep that machinery for supported queries and opt out of automatic acquisition only when supplying a custom fetch.
@KyleAMathews fwiw I'm also looking for something like this for two use-cases:
- devtools panel where I want to be able to let you inspect all the data on device (either in memory or persistence) without triggering new data loading
- Zero-style outbox implementation where you can write async mutators that do tanstack db queries inside to fetch data (thru
queryOnce), and current visible state = server state + replayed outbox (so when an outbox entry is confirmed you roll the whole thing back, remove that entry, and replay again. good explanation in here). when we run those mutators on the server it should fetch data over the network, when we run them on the client it should only fetch against memory/persistence
Prior art here is something like fetch policies in Relay, would be nice to get like a
localOnlyflag you can pass alongside the query toqueryOnce,useLiveQuery, etc.Robert feel free to open feature request issues for these.
@jchook so for the other 10% how do you load data? Some sort of background job thing? I'm confused still how your app works.
Sign in to join this conversation.
🦋 Changeset detected#
Latest commit: aee450a2773090bc686d88823bec566c6091795c
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 33 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