feat: Add meta in queries

[Jastrzebowski]

🎯 Changes

Summary

• Add a chainable .meta() method to pass dynamic runtime context (tenant IDs, scopes, feature flags) to query functions
• Ensure query-level metadata is properly serialised in cache keys to prevent data isolation issues in multi-tenant and authorisation scenarios
• Include comprehensive documentation and tests covering meta propagation, merging semantics, and real-world use cases

Discussion and issues related with passing meta in queries:

• Add ability to pass meta to `useLiveQuery` and `useLiveInfiniteQuery` #1129
• Expose QueryFunctionContext properties (signal, meta) in query-db-collection #350

Problem

Applications need to pass runtime context to their query functions — such as tenant IDs for multi-tenancy, authorisation scopes, or feature flags — without embedding these values in query predicates. Previously, there was no way to attach this metadata to queries, forcing developers to either hardcode context or use workarounds.

Additionally, when different runtime contexts share the same predicates, caching and deduplication logic must account for meta differences, otherwise, queries from different tenants or users with identical predicates would incorrectly share cache entries, causing data isolation bugs.

Approach

The .meta() method accepts arbitrary context data and integrates seamlessly with the query builder, following the same chainable pattern as existing methods like .limit(). Query-level metadata is merged with collection-level metadata (with query-level taking precedence).

Meta is included in the cache key serialisation, ensuring that queries with identical predicates but different runtime contexts receive separate cache entries. The isPredicateSubset() deduplication logic also checks meta equality, preventing data corruption in multi-tenant scenarios where two requests with the same predicates but different tenant scopes would otherwise reuse cached data from the wrong tenant.

The implementation includes tests that validate meta preservation throughout the query lifecycle, correct merging semantics, proper cache key differentiation, and deduplication behaviour.

Documentation covers usage in live queries and extends the existing meta documentation for collections.

✅ 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).

[changeset-bot]

🦋 Changeset detected

Latest commit: 002ea39

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 14 packages

Name	Type
@tanstack/query-db-collection	Minor
@tanstack/db	Minor
@tanstack/angular-db	Patch
@tanstack/electric-db-collection	Patch
@tanstack/offline-transactions	Patch
@tanstack/powersync-db-collection	Patch
@tanstack/react-db	Patch
@tanstack/rxdb-db-collection	Patch
@tanstack/solid-db	Patch
@tanstack/svelte-db	Patch
@tanstack/trailbase-db-collection	Patch
@tanstack/vue-db	Patch
todos	Patch
@tanstack/db-example-paced-mutations-demo	Patch

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

[Jastrzebowski]

Hey TanStack team, my first contribution here. I didn't include the generated docs as they generate a lot of changes. What's the general rule: include generated docs in the PR or create a follow-up PR for docs only?

[kevin-dp]

Hey TanStack team, my first contribution here. I didn't include the generated docs as they generate a lot of changes. What's the general rule: include generated docs in the PR or create a follow-up PR for docs only?

Hi @Jastrzebowski, changes to docs should be made in a separate PR because the docs are built and updated by CI when merged into main. So we typically have an implementation PR and a separate docs PR and we only merge the docs PR when the corresponding implementation is released.

[kevin-dp]

The implementation looks great and it's definitely valuable for query collections.

I'm a bit hesitant though because meta is only used for query collections yet it is added to the public query builder API but isn't applicable to other collection types. It also complicates the TanStack DB core implementation while being related only to query collections.

For these reasons, i'd rather have meta on the queryCollectionOptions only.

@samwillis @KyleAMathews any thoughts on this?