Rust: client query builder

[Shubham8287]

Description of Changes

Client Query builder for rust, as per proposal - https://github.com/clockworklabs/SpacetimeDBPrivate/pull/2356.

1. Pach moves query builder to its separate crate, so that it can be shared between module and sdk.
2. Implements TypedSubscriptionBuilder in sdks/rust as mentioned in proposal
3. Modify codegen to extend types to support query builder as mentioned in proposal
4. a test

API and ABI breaking changes

NA, additive changes.

Expected complexity level and risk

2

Testing

Added a test.

[joshua-spacetime]

Looks great! We also need to be able to build queries over views, but otherwise its ready to merge.

[gefjon]

Can you update the Rust sdk-test clients to use the query builder rather than raw SQL strings?

[joshua-spacetime]

Can you update the Rust sdk-test clients to use the query builder rather than raw SQL strings?

I don't mind if this is done in a different patch.

[cloutiertyler]

Approving the LICENSE file addition

[Shubham8287]

/update-llm-benchmark

[clockwork-labs-bot]

LLM Benchmark Results (ci-quickfix)

Language	Mode	Category	Tests Passed	Task Pass %
Rust	rustdoc_json	basics	25/27	83.3% ⬆️ +38.9%
Rust	rustdoc_json	schema	21/34	58.7% ⬆️ +32.2%
Rust	rustdoc_json	total	46/61	72.1% ⬆️ +35.8%
Rust	docs	basics	5/27	11.1%
Rust	docs	schema	8/34	20.5%
Rust	docs	total	13/61	15.4%
C#	docs	basics	27/27	100.0% ⬆️ +38.9%
C#	docs	schema	24/34	71.7% ⬆️ +40.2%
C#	docs	total	51/61	87.1% ⬆️ +39.5%

Compared against master branch baseline

_{Generated at: 2026-01-21T11:35:14.893Z}

Failure Analysis (click to expand)

Benchmark Failure Analysis

Generated from: /__w/SpacetimeDB/SpacetimeDB/tools/xtask-llm-benchmark/../../docs/llms/docs-benchmark-details.json

Summary

• Total failures analyzed: 34

---

SpacetimeDB Benchmark Test Failure Analysis

Rust / rustdoc_json Failures

Compile/Publish Errors (3 failures)

t_002_scheduled_table

1. Generated Code:

   use spacetimedb::{ReducerContext, ScheduleAt, Table};
   
   #[spacetimedb::table(name = tick_timer, scheduled(reducer = tick, column = scheduled_at))]
   pub struct TickTimer {
       #[primary_key]
       #[auto_inc]
       scheduled_id: u64,
       scheduled_at: ScheduleAt,
   }
   
   #[spacetimedb::reducer(init)]
   pub fn init(ctx: &ReducerContext) {
       if ctx.db.tick_timer().count() == 0 {
           ctx.db
               .tick_timer()
               .insert(TickTimer { scheduled_id: 0, scheduled_at: ScheduleAt::Repeat { interval_micros: 50_000 } });
       }
   }
   
   #[spacetimedb::reducer]
   pub fn tick(_ctx: &ReducerContext, _row: TickTimer) {
   }

2. Expected (Golden):

   use spacetimedb::{reducer, table, ReducerContext, ScheduleAt, Table};
   use std::time::Duration;
   
   #[table(name = tick_timer, scheduled(tick))]
   pub struct TickTimer {
       #[primary_key]
       #[auto_inc]
       pub scheduled_id: u64,
       pub scheduled_at: ScheduleAt,
   }
   
   #[reducer]
   pub fn tick(_ctx: &ReducerContext, _row: TickTimer) -> Result<(), String> {
       Ok(())
   }
   
   #[reducer(init)]
   pub fn init(ctx: &ReducerContext) -> Result<(), String> {
       ctx.db.tick_timer().insert(TickTimer {
           scheduled_id: 0,
           scheduled_at: ScheduleAt::Interval(Duration::from_millis(50).into()),
       });
       Ok(())
   }

3. Error: publish_error: spacetime publish failed (exit=1)

4. Explain the Difference:

   • The generated code lacks the correct scheduled reducer syntax and incorrect handling of published_at.
   • The init function in the generated code fails due to not matching the expected Result<(), String> return type.

5. Root Cause: Unclear documentation regarding the use of scheduled and expected return types of reducers.

6. Recommendation:

   • Update documentation to emphasize the correct use of the scheduled attribute and required return types for reducers.
   • Ensure examples highlight the expected behavior for scheduled tables and reducers.

---

t_015_product_type_columns

1. Generated Code:

   use spacetimedb::{ReducerContext, SpacetimeType, Table};
   
   #[derive(SpacetimeType)]
   pub struct Address {
       street: String,
       zip: i32,
   }
   
   #[derive(SpacetimeType)]
   pub struct Position {
       x: i32,
       y: i32,
   }
   
   #[spacetimedb::table(name = profile)]
   pub struct Profile {
       #[primary_key]
       id: i32,
       home: Address,
       work: Address,
       pos: Position,
   }

2. Expected (Golden):

   use spacetimedb::{reducer, table, ReducerContext, SpacetimeType, Table};
   
   #[derive(SpacetimeType, Clone, Debug)]
   pub struct Address {
       pub street: String,
       pub zip: i32,
   }
   
   #[derive(SpacetimeType, Clone, Debug)]
   pub struct Position {
       pub x: i32,
       pub y: i32,
   }
   
   #[table(name = profile)]
   pub struct Profile {
       #[primary_key]
       pub id: i32,
       pub home: Address,
       pub work: Address,
       pub pos: Position,
   }

3. Error: publish_error: spacetime publish failed (exit=1)

4. Explain the Difference:

   • The generated code lacks the pub modifier for fields in structs, making them inaccessible outside their module.
   • Missing Clone and Debug derivations for structures, which are required by SpacetimeDB for composite types.

5. Root Cause: Lack of clear guidelines on struct field visibility and required traits in the documentation.

6. Recommendation:

   • Clarify the need for public struct fields and necessary traits for Spacetime types in the documentation.
   • Provide comprehensive examples showing struct visibility.

---

Other Failures (5 failures)

t_003_struct_in_table

1. Generated Code:

   use spacetimedb::{ReducerContext, Table};
   
   #[derive(spacetimedb::SpacetimeType)]
   pub struct Position {
       x: i32,
       y: i32,
   }
   
   #[spacetimedb::table(name = entity)]
   pub struct Entity {
       #[primary_key]
       id: i32,
       pos: Position,
   }
   
   #[spacetimedb::reducer]
   pub fn insert_entity(ctx: &ReducerContext, id: i32, pos: Position) {
       ctx.db.entity().insert(Entity { id, pos });
   }

2. Expected (Golden):

   use spacetimedb::{table, SpacetimeType};
   
   #[derive(SpacetimeType, Clone, Debug)]
   pub struct Position {
       pub x: i32,
       pub y: i32,
   }
   
   #[table(name = entity)]
   pub struct Entity {
       #[primary_key]
       pub id: i32,
       pub pos: Position,
   }

3. Error: schema_parity: reducers differ - expected [], got ["insert_entity()"]

4. Explain the Difference:

   • The generated code includes the reducer insert_entity, which is not expected based on the given schema example.
   • Missing pub modifiers on fields in the Position and Entity structs.

5. Root Cause: Documentation unclear about expected presence/absence of reducers in structure definition.

6. Recommendation:

   • Document clearly whether reducers should be included for specific struct/table combinations.
   • Emphasize the visibility of struct fields to avoid similar errors.

---

C# / docs Failures (4 total)

Other Failures (4 failures)

t_014_elementary_columns

1. Generated Code:

   using SpacetimeDB;
   
   public static partial class Module
   {
       [SpacetimeDB.Table(Name = "Primitive", Public = true)]
       public partial struct Primitive
       {
           [SpacetimeDB.PrimaryKey]
           public int Id;
           public int Count;
           public long Total;
           public float Price;
           public double Ratio;
           public bool Active;
           public string Name;
       }
   
       [SpacetimeDB.Reducer]
       public static void Seed(ReducerContext ctx)
       {
           ctx.Db.Primitive.Insert(new Primitive
           {
               Id = 1,
               Count = 2,
               Total = 3000000000L,
               Price = 1.5f,
               Ratio = 2.25,
               Active = true,
               Name = "Alice"
           });
       }
   }

2. Expected (Golden):

   using SpacetimeDB;
   
   public static partial class Module
   {
       [Table(Name = "Primitive")]
       public partial struct Primitive
       {
           [PrimaryKey] public int Id;
           public int Count;
           public long Total;
           public float Price;
           public double Ratio;
           public bool Active;
           public string Name;
       }
   
       [Reducer]
       public static void Seed(ReducerContext ctx)
       {
           ctx.Db.Primitive.Insert(new Primitive {
               Id = 1,
               Count = 2,
               Total = 3000000000,
               Price = 1.5f,
               Ratio = 2.25,
               Active = true,
               Name = "Alice"
           });
       }
   }

3. Error: elementary_columns_row_parity: spacetime sql failed

4. Explain the Difference:

   • The generated code contains the Public = true attribute in the Table declaration, which is not necessary and not present in the golden example.
   • The generated code incorrectly formats Insert, which leads to issues with SQL execution.

5. Root Cause: The documentation does not specify the need for some attributes in the table structure.

6. Recommendation:

   • Clarify attributes that are essential when declaring tables and reducers.
   • Provide more streamlined examples that focus on minimal structures necessary for typical operations.

---

Summary of Recommendations

1. Update documentation to include clear examples of APIs and expected behavior.
2. Provide a breakdown of required attributes and access modifiers for structs.
3. Enhance understanding of scheduled routines, reducers, and their return types.
4. Include common pitfalls and troubleshooting tips related to SpacetimeDB.