Skip to content
Source
Sign inSign up
TanStack/db

feat(db): live query without fetching #2179

Openjchook(GitHub profile, opens in a new tab)wants to merge 13 commits intomain fromrefs/pull/2179/headopened

🎯 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 when autoLoad is 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).

Summary by CodeRabbit

  • New Features

    • Added an autoLoad option 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.
  • Tests

    • Added coverage for local observation across joins, windows, includes, loading states, and React hooks.
    1. 🦋 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
      NameType
      @tanstack/dbMinor
      @tanstack/react-dbMinor
      @tanstack/angular-dbPatch
      @tanstack/capacitor-db-sqlite-persistence-e2e-appPatch
      @tanstack/db-sqlite-persistence-corePatch
      @tanstack/electric-db-collectionPatch
      @tanstack/expo-db-sqlite-persistence-e2e-appPatch
      @tanstack/offline-transactionsPatch
      @tanstack/powersync-db-collectionPatch
      @tanstack/query-db-collectionPatch
      @tanstack/rxdb-db-collectionPatch
      @tanstack/solid-dbPatch
      @tanstack/svelte-dbPatch
      @tanstack/tauri-db-sqlite-persistence-e2e-appPatch
      @tanstack/trailbase-db-collectionPatch
      @tanstack/vue-dbPatch
      todosPatch
      offline-transactions-react-nativePatch
      shopping-list-react-nativePatch
      @tanstack/db-example-react-next-ssr-e2ePatch
      @tanstack/db-example-paced-mutations-demoPatch
      offline-first-electronPatch
      @tanstack/db-example-react-action-enforcementPatch
      @tanstack/db-example-react-start-ssr-e2ePatch
      @tanstack/db-example-react-todoPatch
      @tanstack/browser-db-sqlite-persistencePatch
      @tanstack/capacitor-db-sqlite-persistencePatch
      @tanstack/cloudflare-durable-objects-db-sqlite-persistencePatch
      @tanstack/electron-db-sqlite-persistencePatch
      @tanstack/expo-db-sqlite-persistencePatch
      @tanstack/node-db-sqlite-persistencePatch
      @tanstack/react-native-db-sqlite-persistencePatch
      @tanstack/tauri-db-sqlite-persistencePatch

      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

    2. Review in Change Stack →

      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.ts
      • packages/db/src/query/live/collection-config-builder.ts
      • packages/db/src/query/live/collection-subscriber.ts
      • packages/react-db/src/useLiveInfiniteQuery.ts
      • packages/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: false to 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.ts
      Adds the autoLoad option, 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.md
      When 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.tsx
      React hooks track autoLoad when 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.md
      Adds 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: Passed 4 · Failed 1
      Failed Failed checks: 1 warning
      Check nameStatusExplanationResolution
      Docstring CoverageWarningDocstring 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 Passed checks: 4 passed
      Check nameStatusExplanation
      Title checkPassedThe title clearly and concisely describes the main change: live queries can operate without fetching.
      Description checkPassedThe description includes the required Changes, Checklist, and Release Impact sections. It explains the motivation, implementation behavior, testing, and changeset status.
      Linked Issues checkPassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes checkPassedCheck 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.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.
    3. jchook(GitHub profile, opens in a new tab) changed the title

    4. jchook(GitHub profile, opens in a new tab) changed the title

    5. Couldn't you use local collections for data you're loading in some other way?

    6. 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.

    7. @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 localOnly flag you can pass alongside the query to queryOnce, useLiveQuery, etc.

    8. 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.