docs(next): teach relationships with diagrams, add streaming, restructure builders

Deep revision of the Fundamentals pages for first-time readers:

- Relations and joins now teaches one-to-one, one-to-many, and
  many-to-many each as concept -> animated diagram -> model -> query ->
  result shape -> pitfalls, using three new ConceptAnimation flow scenes.
  Many-to-many is documented as a working pattern (explicit junction
  model + nested include, verified end to end) instead of a limitation.
- Reading data gains a tested "Stream large results" section: await
  buffers and is reusable, for-await streams and is single-use, mixing
  the two throws. (Verified on both databases; a repeated await does
  NOT throw, correcting the earlier claim.)
- Advanced queries restructured into parallel "PostgreSQL: SQL query
  builder" and "MongoDB: Pipeline builder" sections, each with
  what-it-is, when to use it, when to prefer the ORM API, and tested
  examples per use case.
- Common mistakes rewritten as narrated subsections: what you meant,
  what went wrong, the fix, and why it is safer. Type-level claims
  (no data wrapper, mutations require .where) verified with
  @ts-expect-error assertions; all documented snippets compile under
  strict TypeScript.
- Naming: "Prisma Next ORM" replaced with Prisma Next; the query lane
  is called the ORM API.

Test schema extended with Profile (1:1) and Tag/PostTag (M:N junction);
1:1 back-reference fields are unsupported by the PSL provider, so the
1:1 section documents querying from the foreign-key side.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: ankur-arch

apps/docs/content/docs/orm/next/fundamentals/advanced-queries.mdx

@@ -1,18 +1,31 @@
 ---
 title: Advanced queries
-description: Use the SQL builder on PostgreSQL and the pipeline builder on MongoDB for queries the ORM can't express.
+description: Use the SQL query builder on PostgreSQL and the pipeline builder on MongoDB for queries the ORM API can't express.
 url: /orm/next/fundamentals/advanced-queries
 metaTitle: Advanced queries in Prisma Next
-metaDescription: Use the Prisma Next SQL builder for explicit joins, grouped aggregates, and RETURNING, and the typed aggregation pipeline builder on MongoDB.
+metaDescription: Use the Prisma Next SQL query builder for explicit joins, grouped aggregates, and RETURNING, and the typed aggregation pipeline builder on MongoDB.
 ---
 
-When the ORM can't express a query, drop one level: the SQL builder on PostgreSQL, or the pipeline builder on MongoDB. Both stay typed against your contract; neither means writing raw strings.
+When the ORM API can't express a query, drop one level: the SQL query builder on PostgreSQL, or the pipeline builder on MongoDB. Both stay typed against your contract; neither means writing raw strings.
 
-The ORM remains the default. Reach for these builders for explicit joins, computed projections, grouped top-N queries, and aggregation pipelines. The choice is per query, not per app.
+The choice is per query, not per app. A codebase that uses the ORM API everywhere and the builders in three hot spots is the intended shape.
 
-## Query with the SQL builder (PostgreSQL)
+## PostgreSQL: SQL query builder
 
-Use `db.sql.public.<table>` to build a query as a *plan*, then execute the plan through the runtime. Tables use their lowercase storage names:
+The SQL query builder composes a single SQL statement as a typed *plan*: a description of the query you build once and execute through the runtime. You keep full control over the SQL shape (joins, grouping, projections) and full type safety against your contract.
+
+**Use it when:**
+
+- The query is easier to say in SQL: joins with conditions, computed columns, set-shaped results.
+- You need PostgreSQL behavior the ORM API doesn't surface, such as `RETURNING` on a bulk insert.
+- An aggregation needs precise control, like ordering and limiting by an aggregate in the database.
+- A query is performance-sensitive and you want to decide its exact shape.
+
+**Prefer the ORM API when** the query is CRUD, filtered reads, or relation traversal. The [reading](/orm/next/fundamentals/reading-data), [writing](/orm/next/fundamentals/writing-data), and [relations](/orm/next/fundamentals/relations-and-joins) pages cover that surface, with less code and the same type safety.
+
+### Build and run a plan
+
+Start from a table with `db.sql.public.<table>` (tables use lowercase storage names), chain clauses, and call `.build()`. Execute the plan with the runtime:
 
 ```typescript
 import { db } from "./prisma/db";
@@ -26,11 +39,11 @@ const plan = db.sql.public.post
 const publishedPosts = await db.runtime().execute(plan);
 ```
 
-The `.where(...)` callback receives `(fields, fns)`: `fields` holds the column references, `fns` the operators (`eq`, `ne`, `gt`, `lt`, `and`, `count`, and operators added by extensions).
+The `.where(...)` callback receives `(fields, fns)`: `fields` holds the column references, `fns` the operators (`eq`, `ne`, `gt`, `lt`, `ilike`, `and`, `count`, and operators added by extensions).
 
-### Join tables explicitly
+### Join tables with precise control
 
-Use the SQL builder when you need a join the ORM doesn't express. Alias each side with `.as(...)`, join on any condition, and project columns from both sides:
+Alias each side with `.as(...)`, join on any condition, and project columns from both sides into a flat result:
 
 ```typescript
 const plan = db.sql.public.post
@@ -46,13 +59,26 @@ const plan = db.sql.public.post
   .build();
 
 const postsWithAuthors = await db.runtime().execute(plan);
+// Array<{ postId, title, authorEmail }>
 ```
 
-This is also how you read through a many-to-many junction table while [`.include(...)` does not support it](/orm/next/fundamentals/relations-and-joins#current-limitations): join the junction table to the far side explicitly.
+Chain more joins for multi-hop traversals. This is how you get a flat post-tag list through a [many-to-many junction table](/orm/next/fundamentals/relations-and-joins#many-to-many), one row per pair:
+
+```typescript
+const plan = db.sql.public.postTag
+  .as("pt")
+  .innerJoin(db.sql.public.tag.as("t"), (f, fns) => fns.eq(f.pt.tagId, f.t.id))
+  .innerJoin(db.sql.public.post.as("p"), (f, fns) => fns.eq(f.pt.postId, f.p.id))
+  .select((f) => ({ postTitle: f.p.title, tagName: f.t.name }))
+  .build();
+
+const postTagPairs = await db.runtime().execute(plan);
+// [{ postTitle: "Hello Prisma Next", tagName: "typescript" }, ...]
+```
 
 ### Group and rank results
 
-Use the SQL builder for "top N groups" questions, such as the authors with the most posts. It can order and limit by an aggregate directly in the database, which the ORM's grouped aggregates can't:
+Answer "top N groups" questions, such as the authors with the most posts, by ordering and limiting on an aggregate directly in the database:
 
 ```typescript
 const plan = db.sql.public.post
@@ -71,7 +97,7 @@ const topAuthors = await db.runtime().execute(plan);
 
 ### Write with RETURNING
 
-SQL builder writes take an array of rows. Use `.returning(...)` to choose which columns come back:
+SQL builder writes take an array of rows. Use `.returning(...)` to choose which columns come back from the same statement:
 
 ```typescript
 const plan = db.sql.public.user
@@ -85,9 +111,22 @@ const [insertedUser] = await db.runtime().execute(plan);
 
 Prisma Next does not run raw SQL strings: every query goes through the typed builder. If the builder can't express a shape you need, [share the use case](https://pris.ly/discord).
 
-## Query with the pipeline builder (MongoDB)
+## MongoDB: Pipeline builder
+
+The pipeline builder composes a typed MongoDB aggregation pipeline: a sequence of stages such as `$match`, `$group`, `$sort`, and `$lookup`, checked against your contract. It is the MongoDB counterpart of the SQL query builder, and it is also where all MongoDB aggregation lives, because the ORM API has no `.aggregate(...)` on MongoDB.
+
+**Use it when:**
+
+- You need an aggregation: counts, grouping, or summaries per key.
+- You want to join and reshape documents across collections with `$lookup`.
+- A query needs MongoDB pipeline stages that don't map to the ORM API, such as multi-stage filtering and projection.
+- You need operators the MongoDB `.where(...)` doesn't cover yet, like ranges or boolean logic.
+
+**Prefer the ORM API when** the query is document CRUD or a reference-relation read; `.include(...)` already covers the common `$lookup` case.
+
+### Build and run a pipeline
 
-Use `db.query.from("<collection>")` to build a typed aggregation pipeline, then execute it through the runtime. This is also where MongoDB aggregation lives, since the MongoDB ORM has no `.aggregate(...)`:
+Start from a collection with `db.query.from(...)`, chain stages, and call `.build()`. Execute the plan through the runtime:
 
 ```typescript
 import { acc } from "@prisma-next/mongo-query-builder";
@@ -106,9 +145,28 @@ const plan = db.query
   .build();
 
 const postsByAuthor = await runtime.execute(plan);
+// [{ _id: ObjectId, postCount: 3 }, ...]
 ```
 
-Use `.match(...)` to filter with typed field accessors, and `.lookup(...)` for a type-checked `$lookup` join:
+Accumulators such as `acc.count()` and `acc.max(...)` import from `@prisma-next/mongo-query-builder`.
+
+### Filter and group in stages
+
+Chain `.match(...)` before `.group(...)` to aggregate over a subset, the pipeline equivalent of `WHERE` before `GROUP BY`:
+
+```typescript
+const plan = db.query
+  .from("posts")
+  .match((f) => f.published.eq(false))
+  .group((f) => ({ _id: f.authorId, draftCount: acc.count() }))
+  .build();
+
+const draftsByAuthor = await runtime.execute(plan);
+```
+
+### Join collections with $lookup
+
+Use `.lookup(...)` for a type-checked join against another collection. The joined documents arrive under the name you give `.as(...)`:
 
 ```typescript
 const plan = db.query
@@ -122,21 +180,21 @@ const plan = db.query
   .build();
 
 const postsWithAuthors = await runtime.execute(plan);
+// Each post carries an "author" array with the matching user documents
 ```
 
-Accumulators such as `acc.count()` and `acc.max(...)` import from `@prisma-next/mongo-query-builder`.
-
 ## Choose the right lane
 
 | You need | Use |
 | --- | --- |
-| CRUD, filters, relations, simple aggregates | ORM (`db.orm`) |
-| Explicit join, computed projection, grouped top-N, `RETURNING` | SQL builder (`db.sql.public.<table>`) |
+| CRUD, filters, relations, simple aggregates | ORM API (`db.orm`) |
+| Explicit join, computed projection, grouped top-N, `RETURNING` | SQL query builder (`db.sql.public.<table>`) |
 | `$group`, `$lookup` with reshaping, any MongoDB aggregation | Pipeline builder (`db.query.from(...)`) |
 
 Plans execute through `db.runtime().execute(plan)` on PostgreSQL and `(await db.runtime()).execute(plan)` on MongoDB. Inside a [transaction](/orm/next/fundamentals/transactions), use `tx.execute(plan)`.
 
 ## Next
 
 - [Read data](/orm/next/fundamentals/reading-data): the ORM happy path these builders back up.
+- [Understand relationships](/orm/next/fundamentals/relations-and-joins) before reaching for explicit joins.
 - [Run SQL builder plans atomically](/orm/next/fundamentals/transactions) inside a transaction.

apps/docs/content/docs/orm/next/fundamentals/reading-data.mdx

@@ -1,9 +1,9 @@
 ---
 title: Reading data
-description: Fetch one record or many with the Prisma Next ORM, then filter, select, sort, and paginate the results.
+description: Fetch one record or many with Prisma Next, then filter, select, sort, paginate, and stream the results.
 url: /orm/next/fundamentals/reading-data
 metaTitle: Reading data with Prisma Next
-metaDescription: Query PostgreSQL and MongoDB with the Prisma Next ORM. Filter with where, project with select, sort with orderBy, and paginate with take and skip.
+metaDescription: Query PostgreSQL and MongoDB with Prisma Next. Filter with where, project with select, sort with orderBy, paginate with take and skip, and stream large results.
 ---
 
 Read data by chaining query methods on a model, then running the chain with `.all()` for many records or `.first()` for one.
@@ -30,7 +30,7 @@ const user = await db.orm.users.where({ email: "alice@prisma.io" }).first();
 
 Every result is typed against your contract. Models are addressed by schema namespace on PostgreSQL (`db.orm.public.User`, where `public` is the default PostgreSQL schema) and by collection name on MongoDB (`db.orm.users`).
 
-If you are coming from Prisma 7: `.where(...).all()` replaces `findMany`, and `.where(...).first()` replaces `findFirst` and `findUnique`.
+Coming from Prisma 7? `.where(...).all()` replaces `findMany`, and `.where(...).first()` replaces `findFirst` and `findUnique`.
 
 ## Fetch many records or one
 
@@ -71,7 +71,7 @@ const matchingPosts = await db.orm.public.Post
 
 To combine conditions with OR or NOT on PostgreSQL, use the `or`, `and`, and `not` helpers, currently exported from `@prisma-next/sql-orm-client`.
 
-On MongoDB, use the object form. Comparison operators and boolean logic are not available on MongoDB's `.where(...)` yet; for those queries, use the [pipeline builder](/orm/next/fundamentals/advanced-queries#query-with-the-pipeline-builder-mongodb).
+On MongoDB, use the object form. Comparison operators and boolean logic are not available on MongoDB's `.where(...)` yet; for those queries, use the [pipeline builder](/orm/next/fundamentals/advanced-queries#mongodb-pipeline-builder).
 
 ## Select fields
 
@@ -122,19 +122,92 @@ const result = await db.orm.public.Post
 // result.total: number
 ```
 
-There is no `.count()` method on the query chain. On MongoDB, count with a `$group` stage in the [pipeline builder](/orm/next/fundamentals/advanced-queries#query-with-the-pipeline-builder-mongodb).
+There is no `.count()` method on the query chain. On MongoDB, count with a `$group` stage in the [pipeline builder](/orm/next/fundamentals/advanced-queries#mongodb-pipeline-builder).
+
+## Stream large results
+
+A query result is more than a promise: it can also be iterated record by record. That gives you two ways to consume it.
+
+`await` runs the query and buffers every record into an array. This is the right default: the whole result is in memory, and you can read the array as often as you like.
+
+```typescript
+const posts = await db.orm.public.Post.all();
+
+console.log(posts.length);
+console.log(posts[0]);
+```
+
+`for await` streams the result instead. Records are handed to your loop one at a time, without buffering the full result first. Use it when the result is too large to hold in memory, or when you want to start processing before the last record arrives:
+
+```typescript
+for await (const post of db.orm.public.Post.all()) {
+  await exportToSearchIndex(post);
+}
+```
+
+You can also leave the loop early; unprocessed records are never buffered:
+
+```typescript
+for await (const post of db.orm.public.Post.all()) {
+  if (isMatch(post)) break;
+}
+```
+
+### A streamed result can only be read once
+
+Once a `for await` loop has touched a result, that result is finished, even if the loop exited early. Iterating it again, or `await`ing it afterwards, throws an error explaining the result was already consumed:
+
+```typescript
+const result = db.orm.public.Post.all();
+
+for await (const post of result) {
+  // ...
+}
+
+await result;
+// Error: AsyncIterableResult iterator has already been consumed
+```
+
+If you need the data more than once, `await` the query into an array and reuse the array:
+
+```typescript
+const posts = await db.orm.public.Post.all();
+
+const published = posts.filter((p) => p.published);
+const titles = posts.map((p) => p.title);
+```
+
+Streaming behaves the same on PostgreSQL and MongoDB.
 
 ## Common mistakes
 
-:::warning
+### Fetching everything to use one record
+
+You wanted one record, so you queried and took the first element:
+
+```typescript
+const users = await db.orm.public.User.where({ email }).all();
+const user = users[0];
+```
+
+This fetches every matching record and throws away the rest. Use `.first()` instead: it returns one record or `null`, and on PostgreSQL it asks the database for at most one row:
+
+```typescript
+const user = await db.orm.public.User.where({ email }).first();
+```
+
+### Forgetting that .all() has no limit
+
+`.all()` returns every match. On a table that grows, yesterday's fast query becomes today's slow one. Add `.take(n)` when you don't genuinely need every record, or [stream the result](#stream-large-results) when you do.
 
-A query result can only be consumed once. `await` buffers it into an array; a second `await` on the same result throws `RUNTIME.ITERATOR_CONSUMED`. Store the array in a variable and reuse the variable.
+### Reusing a streamed result
 
-:::
+You streamed a result with `for await`, then tried to read it again. The second read throws, because a streamed result is consumed as it is read. Store the data if you need it twice:
 
-- Using `.all()` for a single record. Use `.first()`: it returns one record or `null`, without fetching the rest.
-- Expecting `.all()` to limit itself. It returns every match; add `.take(n)` when the table can grow.
-- Loading a huge result into memory. Iterate it instead of awaiting: `for await (const row of query.all())`.
+```typescript
+const posts = await db.orm.public.Post.all();
+// posts is a plain array now; read it as often as you like
+```
 
 ## Next