Add missing query builder docs (#4196)

# Description of Changes

Document the client query builder api for rust, csharp, and typescript.
Also add/fix some documentation for the module-side query builder.

# API and ABI breaking changes

N/A

# Expected complexity level and risk

0

# Testing

N/A. Just documentation.

---------

Signed-off-by: joshua-spacetime <josh@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>

Author: joshua-spacetime

docs/docs/00200-core-concepts/00100-databases/00500-cheat-sheet.md

@@ -586,9 +586,15 @@ export const my_player = spacetimedb.view({ name: 'my_player' }, {}, t.option(pl
   return ctx.db.player.identity.find(ctx.sender);
 });
 
-// Return multiple rows
+// Return potentially multiple rows
 export const top_players = spacetimedb.view({ name: 'top_players' }, {}, t.array(player.rowType), ctx => {
-  return ctx.db.player.iter().filter(p => p.score > 1000);
+  return ctx.db.player.score.filter(1000);
+});
+
+// Perform a generic filter using the query builder.
+// Equivalent to `SELECT * FROM player WHERE score < 1000`.
+export const bottom_players = spacetimedb.view({ name: 'bottom_players' }, {}, t.array(player.rowType), ctx => {
+  return ctx.from.player.where(p => p.score.lt(1000))
 });
 ```
 
@@ -605,32 +611,45 @@ public static Player? MyPlayer(ViewContext ctx)
     return ctx.Db.Player.Identity.Find(ctx.Sender);
 }
 
-// Return multiple rows
+// Return potentially multiple rows
 [SpacetimeDB.View(Public = true)]
 public static IEnumerable<Player> TopPlayers(ViewContext ctx)
 {
-    return ctx.Db.Player.Iter().Where(p => p.Score > 1000);
+    return ctx.Db.Player.Score.Filter(1000);
+}
+
+// Perform a generic filter using the query builder.
+// Equivalent to `SELECT * FROM player WHERE score < 1000`.
+[SpacetimeDB.View(Public = true)]
+public static IQuery<Player> BottomPlayers(ViewContext ctx)
+{
+    return ctx.From.Player.Where(p => p.Score.Lt(1000));
 }
 ```
 
 </TabItem>
 <TabItem value="rust" label="Rust">
 
 ```rust
-use spacetimedb::{view, ViewContext};
+use spacetimedb::{view, Query, ViewContext};
 
 // Return single row
 #[view(name = my_player, public)]
 fn my_player(ctx: &ViewContext) -> Option<Player> {
     ctx.db.player().identity().find(ctx.sender())
 }
 
-// Return multiple rows
+// Return potentially multiple rows
 #[view(name = top_players, public)]
 fn top_players(ctx: &ViewContext) -> Vec<Player> {
-    ctx.db.player().iter()
-        .filter(|p| p.score > 1000)
-        .collect()
+    ctx.db.player().score().filter(1000).collect()
+}
+
+// Perform a generic filter using the query builder.
+// Equivalent to `SELECT * FROM player WHERE score < 1000`.
+#[view(name = bottom_players, public)]
+fn bottom_players(ctx: &ViewContext) -> impl Query<Player> {
+    ctx.from.player().r#where(|p| p.score.lt(1000))
 }
 ```
 

docs/docs/00200-core-concepts/00200-functions/00500-views.md

@@ -743,6 +743,8 @@ You may notice that views can only access table data through indexed lookups (`.
 
 **Why SQL subscriptions can scan.** You might wonder why SQL subscription queries can include full table scans while view functions cannot. The difference is that SQL queries are not black boxes - SpacetimeDB can analyze and transform them. The query engine uses **incremental evaluation**: when rows change, it computes exactly which output rows are affected without re-running the entire query. Think of it like taking the derivative of the query - given a small change in input, compute the small change in output. Since view functions are opaque code, this kind of incremental computation isn't possible.
 
+**Why query builder subscriptions can scan.** For the same reason that SQL subscriptions can scan. Anything you can do with SQL subscriptions you can do with the query builder API and vice versa.
+
 **The tradeoff is acceptable for indexed access.** For point lookups (`.find()`) and small range scans (`.filter()` on indexed columns), the performance difference between full re-evaluation and incremental evaluation is small. This is why views are limited to indexed access - it's the subset of operations where the black-box limitation doesn't hurt performance.
 
 If you need to aggregate or sort entire tables, consider returning a `Query` from your view instead. Since queries can be analyzed by the query engine, they support incremental evaluation even when scanning full tables. Alternatively, design your schema so the data you need is accessible through indexes.

docs/docs/00200-core-concepts/00400-subscriptions.md

@@ -168,9 +168,9 @@ interface SubscriptionBuilder {
   // or later during the subscription's lifetime if the module's interface changes.
   onError(callback: (ctx: ErrorContext, error: Error) => void): SubscriptionBuilder;
 
-  // Subscribe to the following SQL queries.
+  // Subscribe to the following SQL or typed queries.
   // Returns immediately; callbacks are invoked when data arrives from the server.
-  subscribe(querySqls: string[]): SubscriptionHandle;
+  subscribe(query_sql:string | RowTypedQuery<any, any> | Array<string | RowTypedQuery<any, any>>): SubscriptionHandle;
 
   // Subscribe to all rows from all tables.
   // Intended for applications where memory and bandwidth are not concerns.
@@ -227,6 +227,31 @@ public sealed class SubscriptionBuilder
     /// in order to replicate only the subset of data which the client needs to function.
     /// </summary>
     public void SubscribeToAllTables();
+
+    /// <summary>
+    /// Add a typed query to this subscription.
+    ///
+    /// This is the entry point for building subscriptions without writing SQL by hand.
+    /// Once a typed query is added, only typed queries may follow (SQL and typed queries cannot be mixed).
+    /// </summary>
+    public TypedSubscriptionBuilder AddQuery<TRow>(
+        Func<QueryBuilder, IQuery<TRow>> build
+    );
+}
+
+public sealed class TypedSubscriptionBuilder
+{
+    /// <summary>
+    /// Add a typed query to this subscription.
+    /// </summary>
+    public TypedSubscriptionBuilder AddQuery<TRow>(
+        Func<QueryBuilder, IQuery<TRow>> build
+    );
+
+    /// <summary>
+    /// Subscribe to all typed queries that have been added to this subscription.
+    /// </summary>
+    public SubscriptionHandle Subscribe();
 }
 ```
 
@@ -261,6 +286,17 @@ impl<M: SpacetimeModule> SubscriptionBuilder<M> {
     /// should register more precise queries via [`Self::subscribe`]
     /// in order to replicate only the subset of data which the client needs to function.
     pub fn subscribe_to_all_tables(self);
+
+    /// Build a query and invoke `subscribe` in order to subscribe to its results.
+    pub fn add_query<T>(self, build: impl Fn(M::QueryBuilder) -> impl Query<T>) -> TypedSubscriptionBuilder<M>;
+}
+
+impl<M: SpacetimeModule> TypedSubscriptionBuilder<M> {
+    /// Build a query and invoke `subscribe` in order to subscribe to its results.
+    pub fn add_query<T>(mut self, build: impl Fn(M::QueryBuilder) -> impl Query<T>) -> Self;
+
+    /// Subscribe to the queries that have been built with `add_query`.
+    pub fn subscribe(self) -> M::SubscriptionHandle;
 }
 
 /// Types which specify a list of query strings.

docs/docs/00200-core-concepts/00600-client-sdk-languages/00400-sdk-api.md

@@ -24,7 +24,7 @@ Subscriptions replicate a subset of the database to your client, maintaining a l
 
 ### Creating Subscriptions
 
-Subscribe to tables or queries using SQL:
+Subscribe to tables or queries using raw SQL:
 
 <Tabs groupId="client-language" queryString>
 <TabItem value="typescript" label="TypeScript">
@@ -110,6 +110,63 @@ void OnSubscriptionError(const FErrorContext& Ctx)
 </TabItem>
 </Tabs>
 
+Or use the query builder:
+
+<Tabs groupId="client-language" queryString>
+<TabItem value="typescript" label="TypeScript">
+
+```typescript
+import { queries } from './module_bindings';
+
+// Subscribe with callbacks
+conn
+  .subscriptionBuilder()
+  .onApplied(ctx => {
+    console.log(`Subscription ready with ${ctx.db.User.count()} users`);
+  })
+  .onError((ctx, error) => {
+    console.error(`Subscription failed: ${error}`);
+  })
+  .subscribe([queries.user]);
+```
+
+</TabItem>
+<TabItem value="csharp" label="C#">
+
+```csharp
+// Subscribe with callbacks
+conn.SubscriptionBuilder()
+    .OnApplied(ctx =>
+    {
+        Console.WriteLine($"Subscription ready with {ctx.Db.User.Count()} users");
+    })
+    .OnError((ctx, error) =>
+    {
+        Console.WriteLine($"Subscription failed: {error}");
+    })
+    .AddQuery(ctx => ctx.From.User())
+    .Subscribe();
+```
+
+</TabItem>
+<TabItem value="rust" label="Rust">
+
+```rust
+// Subscribe with callbacks
+conn.subscription_builder()
+    .on_applied(|ctx| {
+        println!("Subscription ready with {} users", ctx.db().user().count());
+    })
+    .on_error(|ctx, error| {
+        eprintln!("Subscription failed: {}", error);
+    })
+    .add_query(|ctx| ctx.from.user())
+    .subscribe();
+```
+
+</TabItem>
+</Tabs>
+
 See the [Subscriptions documentation](/subscriptions) for detailed information on subscription queries and semantics. Subscribe to [tables](/tables) for row data, or to [views](/functions/views) for computed query results.
 
 ### Querying the Local Cache

docs/static/ai-rules/spacetimedb-typescript.mdc

@@ -422,11 +422,8 @@ conn.subscriptionBuilder()
 
 > ⚠️ **Do NOT use Row Level Security (RLS)** — it is deprecated.
 
-⚠️ **CRITICAL: Views SHOULD use index lookups, NOT `.iter()` (performance)**
-
-Using `.iter()` in views is technically possible but causes severe performance issues:
-- Every change to ANY row in the table triggers a full re-evaluation of the view
-- For large tables, this becomes prohibitively expensive
+> ⚠️ **CRITICAL:** Procedural views (views that compute results in code) can ONLY access data via index lookups, NOT `.iter()`.
+> If you need a view that scans/filters across many rows (including the entire table), return a **query** built with the query builder (`ctx.from...`).
 
 ```typescript
 // Private table with index on ownerId
@@ -456,6 +453,20 @@ spacetimedb.view(
 );
 ```
 
+### Query builder view pattern (can scan)
+
+```typescript
+// Query-builder views return a query; the SQL engine maintains the result incrementally.
+// This can scan the whole table if needed (e.g. leaderboard-style queries).
+spacetimedb.anonymousView(
+  { name: 'top_players', public: true },
+  t.array(Player.rowType),
+  (ctx) =>
+    ctx.from.player
+      .where(p => p.score.gt(1000))
+);
+```
+
 ### ViewContext vs AnonymousViewContext
 ```typescript
 // ViewContext — has ctx.sender, result varies per user (computed per-subscriber)