feat(db): unionAll operator

.changeset/tender-mugs-hear.md

@@ -3,3 +3,4 @@
 ---
 
 Added the `caseWhen` query operator for scalar conditional expressions and conditional select projections with guarded includes.
+Added `unionAll()` support to combine independent sources or built query branches in a single query.

docs/guides/live-queries.md

@@ -485,16 +485,19 @@ This is particularly useful when you need to:
 
 The foundation of every query is the `from` method, which specifies the source collection or subquery. You can alias the source using object syntax.
 
+Use `from()` with a single source. To combine multiple independent sources
+without a join, use [`unionAll()`](#source-level-unionall) instead.
+
 ### Method Signature
 
 ```ts
 from({
-  [alias]: Collection | Query,
+  [alias]: Collection | Query
 }): Query
 ```
 
 **Parameters:**
-- `[alias]` - A Collection or Query instance. Note that only a single aliased collection or subquery is allowed in the `from` clause.
+- `[alias]` - A Collection or Query instance.
 
 ### Basic Usage
 
@@ -538,6 +541,90 @@ const userNames = createCollection(liveQueryCollectionOptions({
 }))
 ```
 
+### `unionAll`
+
+Use `unionAll()` as a start method, in the same place you would use `from()`,
+to combine independent sources without a join. It has two forms:
+
+```ts
+unionAll({
+  [alias]: Collection | Query,
+  [alias2]: Collection | Query
+}): Query
+
+unionAll(branchQuery, branchQuery2, ...branchQueries): Query
+```
+
+#### Source-Level `unionAll`
+
+The object form combines collection or subquery sources. Conceptually, this
+behaves like `UNION ALL`: each raw result row comes from exactly one source
+alias, and inactive aliases are `undefined`.
+
+```ts
+import { coalesce, createLiveQueryCollection } from '@tanstack/db'
+
+const timeline = createLiveQueryCollection((q) =>
+  q
+    .unionAll({
+      message: messagesCollection,
+      toolCall: toolCallsCollection,
+    })
+    .orderBy(({ message, toolCall }) =>
+      coalesce(message.timestamp, toolCall.timestamp),
+    )
+)
+```
+
+Without `select()`, the result type is an exclusive union:
+
+```ts
+type TimelineRow =
+  | { message: Message; toolCall?: undefined }
+  | { message?: undefined; toolCall: ToolCall }
+```
+
+Use subqueries when each branch needs its own filtering or shaping before the
+sources are combined.
+
+If you project branch values with `select()`, you control the inactive branch
+shape. For example, `caseWhen()` projections use `null` when no branch matches
+unless you provide a default value.
+
+#### Query-Branch `unionAll`
+
+You can also pass built queries directly. This form unions the result rows from
+each branch query. Downstream clauses operate on that shared result shape, so
+ordering can reference shared fields directly instead of using `coalesce()`.
+A branch without `select()` keeps its normal query result shape; for example, a
+joined branch enters the union as a namespaced row.
+
+```ts
+const timeline = createLiveQueryCollection((q) => {
+  const messageRows = q
+    .from({ message: messagesCollection })
+    .select(({ message }) => ({
+      type: `message` as const,
+      id: message.id,
+      body: message.text,
+      timestamp: message.timestamp,
+    }))
+
+  const toolCallRows = q
+    .from({ toolCall: toolCallsCollection })
+    .select(({ toolCall }) => ({
+      type: `toolCall` as const,
+      id: toolCall.id,
+      body: toolCall.name,
+      timestamp: toolCall.timestamp,
+    }))
+
+  return q
+    .unionAll(messageRows, toolCallRows)
+    .orderBy(({ timestamp }) => timestamp)
+})
+```
+
 ## Where Clauses
 
 Use `where` clauses to filter your data based on conditions. You can chain multiple `where` calls - they are combined with `and` logic.
@@ -1661,6 +1748,35 @@ const sortedUsers = createLiveQueryCollection((q) =>
 )
 ```
 
+### `unionAll` Ordering
+
+When ordering a source-level `unionAll` query, use a combined expression such as
+`coalesce()` to produce one comparable value across branches. Query-branch
+`unionAll()` can instead order by shared selected fields, as shown in the
+[`unionAll()` examples](#unionall).
+
+If the order expression sorts strings and the branch collections have different
+default string collation settings, TanStack DB uses the first source collection's
+collation as the default. Pass explicit `orderBy` compare options when you need
+a specific string collation for the combined ordering:
+
+```ts
+const timeline = createLiveQueryCollection((q) =>
+  q
+    .unionAll({
+      message: messagesCollection,
+      toolCall: toolCallsCollection,
+    })
+    .select(({ message, toolCall }) => ({
+      label: coalesce(message.title, toolCall.name),
+    }))
+    .orderBy(({ $selected }) => $selected.label, {
+      stringSort: `locale`,
+      locale: `en-US`,
+    })
+)
+```
+
 ### Ordering by SELECT Fields
 
 When you use `select()` with aggregates or computed values, you can order by those fields using the `$selected` namespace:

packages/db/src/errors.ts

@@ -385,11 +385,26 @@ export class InvalidSourceError extends QueryBuilderError {
   }
 }
 
+export type SourceClauseContext =
+  | `from clause`
+  | `unionAll clause`
+  | `join clause`
+
 export class InvalidSourceTypeError extends QueryBuilderError {
-  constructor(context: string, type: string) {
-    super(
-      `Invalid source for ${context}: Expected an object with a single key-value pair like { alias: collection }. ` +
-        `For example: .from({ todos: todosCollection }). Got: ${type}`,
+  constructor(context: SourceClauseContext, type: string) {
+    const expected =
+      context === `unionAll clause`
+        ? `an object with one or more key-value pairs like { alias: collection }`
+        : `an object with a single key-value pair like { alias: collection }`
+    const example =
+      context === `unionAll clause`
+        ? `.unionAll({ todos: todosCollection, events: eventsCollection })`
+        : context === `join clause`
+          ? `.join({ todos: todosCollection }, ({ todo, todos }) => eq(todo.id, todos.id))`
+          : `.from({ todos: todosCollection })`
+    super(
+      `Invalid source for ${context}: Expected ${expected}. ` +
+        `For example: ${example}. Got: ${type}`,
     )
   }
 }

packages/db/src/indexes/auto-index.ts

@@ -1,6 +1,6 @@
 import { DEFAULT_COMPARE_OPTIONS } from '../utils'
-import { checkCollectionSizeForIndex, isDevModeEnabled } from './index-registry'
 import { hasVirtualPropPath } from '../virtual-props'
+import { checkCollectionSizeForIndex, isDevModeEnabled } from './index-registry'
 import type { CompareOptions } from '../query/builder/types'
 import type { BasicExpression } from '../query/ir'
 import type { CollectionImpl } from '../collection/index.js'