C# client typed query builder #3982

rekhoff · 2026-01-09T00:05:38Z

Description of Changes

This PR implements the C# client-side typed query builder, as assigned in #3759.

Key pieces:

Added a small C# runtime query-builder surface in the client SDK (sdks/csharp/src/QueryBuilder.cs):
- Query (wraps the generated SQL string)
- Table<TRow, TCols, TIxCols> (entry point for All() / Where(...))
- Col<TRow, TValue> and IxCol<TRow, TValue> (typed column references)
- BoolExpr (typed boolean expression composition)
- SQL identifier quoting + literal formatting helpers (SqlFormat)
Extended C# client bindings codegen (crates/codegen/src/csharp.rs) to generate:
- Per-table/view *Cols and *IxCols helper classes used by the typed query builder.
- A generated per-module QueryBuilder with a From accessor for each table/view, producing Table<...> values.
- A generated TypedSubscriptionBuilder which collects Query<TRow>.Sql values and calls the existing subscription API.
- An AddQuery(Func<QueryBuilder, Query> build) entry point off SubscriptionBuilder, mirroring the proposal’s Rust API.
Fixed a codegen naming collision found during regression testing:
- *Cols/*IxCols helpers are now named after the table/view accessor name (PascalCase) instead of the row type, since multiple tables/views can share the same row type (e.g. alias tables / views returning an existing product type).
  C# usage examples (mirroring the proposal’s Rust examples)

Typed subscription flow (no raw SQL)

void Subscribe(SpacetimeDB.Types.DbConnection conn)
{
    conn.SubscriptionBuilder()
        .OnApplied(ctx => { /* ... */ })
        .OnError((ctx, err) => { /* ... */ })
        .AddQuery(qb => qb.From.Users().All())
        .AddQuery(qb => qb.From.Players().All())
        .Subscribe();
}

Typed WHERE filters and boolean composition

conn.SubscriptionBuilder()
    .OnApplied(ctx => { /* ... */ })
    .OnError((ctx, err) => { /* ... */ })
    .AddQuery(qb =>
        qb.From.Players().Where(p =>
            p.Name.Eq("alice")
                .And(p.IsOnline.Eq(true))
        )
    )
    .Subscribe();

“Admin can see all, otherwise only self” (proposal’s “player” view logic, but client-side)

Identity self = /* ... */;

conn.SubscriptionBuilder()
    .AddQuery(qb =>
        qb.From.Players().Where(p =>
            p.Identity.Eq(self)
        )
    )
    .Subscribe();

Index-column access for query construction (IxCols)

conn.SubscriptionBuilder()
    .AddQuery(qb =>
        qb.From.Players().Where(
            qb.From.Players().IxCols.Identity.Eq(self)
        )
    )
    .Subscribe();

API and ABI breaking changes

None.

Additive client SDK runtime types.
Additive client bindings codegen output.
No wire-format changes.

Expected complexity level and risk

2 - Low to moderate

Mostly additive code + codegen.
The main risk is correctness/compat of generated SQL strings and name/casing conventions across languages; this is mitigated by targeted unit tests + full C# regression test runs.

Testing

Ran run-regression-tests.sh successfully after regenerating C# bindings.
Ran C# unit tests using dotnet test sdks/csharp/tests~/tests.csproj -c Release
Added a new unit test suite (sdks/csharp/tests~/QueryBuilderTests.cs) validating:
- Identifier quoting / escaping
- Literal formatting (strings, bools, enums, SpacetimeDB primitive types)
- NULL semantics for Eq/Neq
- Boolean expression parenthesization (And/Or/Not)

Signed-off-by: Ryan <[email protected]>

joshua-spacetime

Can we add some end-to-end tests?

joshua-spacetime · 2026-01-14T00:32:46Z

sdks/csharp/src/QueryBuilder.cs

+            return new BoolExpr<TRow>($"{RefSql} = {SqlFormat.FormatLiteral(value)}");
+        }
+
+        public BoolExpr<TRow> Neq(TValue value)


For the rust builder it's ne

joshua-spacetime · 2026-01-14T00:34:16Z

sdks/csharp/src/QueryBuilder.cs

+        public BoolExpr<TRow> IsNull() => new($"{RefSql} IS NULL");
+        public BoolExpr<TRow> IsNotNull() => new($"{RefSql} IS NOT NULL");


These aren't supported in SpacetimeSQL

joshua-spacetime · 2026-01-14T00:43:25Z

sdks/csharp/src/QueryBuilder.cs

+            IxCols = ixCols;
+        }
+
+        public Query<TRow> All() => new($"SELECT * FROM {SqlFormat.QuoteIdent(tableName)}");


I don't think All is necessary.

joshua-spacetime · 2026-01-14T00:44:17Z

sdks/csharp/src/QueryBuilder.cs

+        {
+            if (value is null)
+            {
+                return "NULL";


We don't support NULL.

joshua-spacetime · 2026-01-14T00:45:22Z

sdks/csharp/src/QueryBuilder.cs

+            }
+
+            var t = value.GetType();
+            if (t.IsEnum)


We also don't currently support enum comparisons

joshua-spacetime · 2026-01-14T00:50:31Z

sdks/csharp/tests~/QueryBuilderTests.cs

+    public void All_QuotesTableName()
+    {
+        var table = MakeTable("My\"Table");
+        Assert.Equal("SELECT * FROM \"My\"\"Table\"", table.All().Sql);


Same as earlier, we don't need All() here. We can just .toSql() the table ref directly.

joshua-spacetime · 2026-01-14T00:51:36Z

sdks/csharp/tests~/QueryBuilderTests.cs

+    public void Where_Eq_Null_UsesIsNull()
+    {
+        var table = MakeTable("T");
+        var sql = table.Where(c => c.Name.Eq(null!)).Sql;


We should make Eq's arg not nullable.

joshua-spacetime · 2026-01-14T00:51:52Z

sdks/csharp/tests~/QueryBuilderTests.cs

+    public void Where_Neq_Null_UsesIsNotNull()
+    {
+        var table = MakeTable("T");
+        var sql = table.Where(c => c.Name.Neq(null!)).Sql;


Same for all of the args

rekhoff added 5 commits January 8, 2026 14:43

Initial add of C# Client Query Builder implementation

00e8789

Updated lint and snapshot

97aa69d

Regenerated Blackholio and quickstart-chat bindings

09301bf

Merge branch 'master' into rekhoff/csharp-client-query-builder

39ab222

Added missing meta file for QueryBuilder.cs

2f29a38

rekhoff self-assigned this Jan 9, 2026

rekhoff requested review from JasonAtClockwork, gefjon and joshua-spacetime January 9, 2026 19:37

rekhoff marked this pull request as ready for review January 9, 2026 20:54

rekhoff added 2 commits January 9, 2026 14:31

Merge branch 'master' into rekhoff/csharp-client-query-builder

39f3305

Signed-off-by: Ryan <[email protected]>

Regenerated C# client regression test module bindings

0b18133

bfops added release-1.12 backward-compatible enhancement New feature or request release-any To be landed in any release window and removed backward-compatible release-1.12 labels Jan 12, 2026

joshua-spacetime reviewed Jan 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

C# client typed query builder #3982

C# client typed query builder #3982

Uh oh!

rekhoff commented Jan 9, 2026 •

edited

Loading

Uh oh!

joshua-spacetime left a comment

Uh oh!

joshua-spacetime Jan 14, 2026

Uh oh!

joshua-spacetime Jan 14, 2026

Uh oh!

joshua-spacetime Jan 14, 2026

Uh oh!

joshua-spacetime Jan 14, 2026

Uh oh!

joshua-spacetime Jan 14, 2026

Uh oh!

joshua-spacetime Jan 14, 2026

Uh oh!

joshua-spacetime Jan 14, 2026

Uh oh!

joshua-spacetime Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		public BoolExpr<TRow> IsNull() => new($"{RefSql} IS NULL");
		public BoolExpr<TRow> IsNotNull() => new($"{RefSql} IS NOT NULL");

C# client typed query builder #3982

Are you sure you want to change the base?

C# client typed query builder #3982

Uh oh!

Conversation

rekhoff commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Changes

API and ABI breaking changes

Expected complexity level and risk

Testing

Uh oh!

joshua-spacetime left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rekhoff commented Jan 9, 2026 •

edited

Loading