Further misc docs changes #4029

cloutiertyler · 2026-01-13T19:30:26Z

Description of Changes

Major documentation overhaul focusing on tables, column types, and indexes.

Quickstart Guides:

Updated React, TypeScript, Rust, and C# quickstarts with table/reducer examples
Fixed CLI syntax (positional --database argument)
Improved template consistency across languages

Tables Documentation:

Added "Why Tables" section explaining table-oriented design philosophy (tables as fundamental unit, system tables, data-oriented design principles)
Added "Physical and Logical Independence" section explaining how subscription queries use the relational model independently of physical storage
Added brief sections linking to related pages (Visibility, Constraints, Schedule Tables)
Renamed "Scheduled Tables" to "Schedule Tables" throughout (tables store schedules; reducers are scheduled)

Column Types:

Split into dedicated page with unified type reference table
Added "Representing Collections" section (Vec/Array vs table tradeoffs)
Added "Binary Data and Files" section for Vec storage patterns
Added "Type Performance" section (smaller types, fixed-size types, column ordering for alignment)
Added complete example struct demonstrating all type categories
Renamed "Structured" category to "Composite"

Indexes:

Complete rewrite with textbook-style documentation
Added "When to Use Indexes" guidance
Documented single-column and multi-column index syntax (field-level and table-level)
Comprehensive range query examples with correct TypeScript Range class syntax
Explained multi-column index prefix matching semantics
Added index-accelerated deletion examples
Included index design guidelines

Styling:

Added CSS for table border radius and row separators
Created Check component for green checkmarks in tables

API and ABI breaking changes

None. Documentation only.

Expected complexity level and risk

1 - Documentation changes only, no code changes.

Testing

Verify docs build without errors
Review rendered pages for formatting issues
Confirm code examples are syntactically correct

In StrictMode, React unmounts and remounts components synchronously to detect side effects. The previous cleanup would disconnect immediately, killing the in-flight WebSocket connection. Fix: defer disconnect with setTimeout(..., 0). Since StrictMode remounts happen in the same JavaScript task, the remount cancels the pending timeout, preserving the connection. Real unmounts proceed normally since no remount occurs to cancel the timeout.

The error now hints that the table may be private, helping users diagnose visibility issues.

For consistency with other CLI commands (publish, call, logs, sql), the database name is now a positional argument instead of a flag. The --database flag is deprecated but still works with a warning.

Add "Understand tables and reducers" step showing template code and "Test with the CLI" step demonstrating spacetime call, sql, and logs commands with example output. Also simplify basic-c-sharp template to match Rust/TypeScript templates (person table with name field only).

- Split "Column Types and Constraints" into three pages: - Column Types: primitive, structured, and special types - Primary Keys: rules, implications, multi-column workarounds - Constraints: unique, auto-increment, default values - Add table styling with border radius and row separators - Add Check component for green checkmark badges in tables - Update functions comparison table to use Check component - Add note about view transaction isolation

Schedule tables store schedules; the reducers they trigger are "scheduled reducers". This naming clarifies that the table itself is a schedule, not something that is scheduled. - Rename file and update slug from /tables/scheduled-tables to /tables/schedule-tables - Update all references throughout docs - Add note explaining why code uses "scheduled" (refers to the scheduled reducer)

- Explain tables as SpacetimeDB's fundamental unit (like files in Unix) - Describe self-describing nature via system tables (st_table, st_column) - Connect to data-oriented design philosophy - Recommend table decomposition by access pattern - Provide concrete game schema example showing decomposed approach - Fix stale link to schedule-tables

…ucture - Add section explaining how tables separate logical queries from physical representation - Explain how indexes improve performance without changing queries - Update Table Visibility to mention view functions and link to access permissions - Add brief Constraints section linking to primary keys and constraints pages - Add brief Schedule Tables section linking to schedule tables page - Remove em dashes throughout

- Combine primitive, structured, and special types into single table per language - Add "Representing Collections" section on Vec/Array vs table tradeoffs - Add "Binary Data and Files" section on storing blobs with Vec<u8> - Add "Type Performance" section covering smaller types, fixed-size types, and column ordering for alignment/padding optimization

Column Types: - Rename "Structured" category to "Composite" for clarity - Add complete example showing all type categories in one table Indexes: - Add "When to Use Indexes" section with practical guidance - Document B-tree index type and its capabilities - Cover single-column indexes with field-level and table-level syntax - Explain multi-column indexes with prefix matching semantics - Add comprehensive query examples: equality, range, and multi-column - Document deletion via indexes - Include index design guidelines for column selection and ordering - Fix TypeScript examples to use correct Range class with Bound objects

- /tables/columns -> /tables/column-types (page was renamed) - /tables/scheduled-tables -> /tables/schedule-tables (page was renamed)

…ult values - Create dedicated auto-increment page with sequence semantics - Document trigger value (zero activates auto-increment) - Explain sequence parameters, wrapping, and crash recovery - Add concurrency section: gaps can occur, no sequential guarantee - Include manual counter pattern for strict sequential numbering - Merge primary keys into constraints page - Primary key is technically a constraint - Consolidate all constraint documentation in one place - Create dedicated default values page - Extract from constraints page (not actually a constraint) - Document schema evolution use case - Update all cross-references and Next Steps sections

- Document direct indexes as O(1) alternative to B-tree for dense integer keys - Add index types comparison table (B-tree vs Direct) - Expand access permissions with public/private table visibility - Add view examples for filtering rows by caller and hiding sensitive columns - All view examples use index lookups (not table scans) per performance requirements

Cover all CRUD operations with code samples in all three languages: insert, find, filter, update, delete, iter, and count.

…and examples - Explain why anonymous views scale better (shared materialization) - Add per-user view example (my_player) - Add shared leaderboard example - Add region-based design pattern showing how to structure data for sharing

- Note that Rust requires importing the Table trait for methods like try_insert - Expand ViewContext vs AnonymousViewContext with performance guidance - Add examples: per-user view, shared leaderboard, region-based design

- Add TypeScript examples throughout subscriptions documentation - Fix tab groupId from "server-language" to "client-language" for client SDK docs - Fix reducer-context groupId to "server-language" for consistency - Strengthen RLS deprecation warning, recommend views instead

docs/docs/00100-intro/00200-quickstarts/00100-react.md

jdetter

I think there are a lot of small problems here, I'm leaving this review for now but I'd like to have the opportunity to review more tomorrow. I tried to at least compile every rust example, I will do C# and typescript tomorrow if that would be useful.

Please take special note for the changes in templates/basic-c-sharp/spacetimedb/Lib.cs as it does not build.

docs/docs/00100-intro/00200-quickstarts/00600-c-sharp.md

docs/docs/00100-intro/00300-tutorials/00300-unity-tutorial/00400-part-3.md

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

docs/docs/00200-core-concepts/00300-tables/00240-constraints.md

docs/docs/00200-core-concepts/00300-tables/00400-access-permissions.md

templates/basic-c-sharp/spacetimedb/Lib.cs

docs/docs/00200-core-concepts/00300-tables/00230-auto-increment.md

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

jdetter

Ok substantially less issues here - this is a lot better. I found a final few things that are easy to fix.

I think this is ready to go after one more batch of suggested changes @cloutiertyler

Signed-off-by: John Detter <4099508+jdetter@users.noreply.github.com>

cloutiertyler · 2026-01-16T12:40:09Z

/update-llm-benchmark

- Add ci-comment command to generate PR comment markdown locally - Add tab filtering for language-specific context (server-language, client-language) - Improve analyze command with language-grouped output and typed failure extraction - Update GitHub workflow to use generated comment file and show diffs vs master - Add ScoreDetails.failure_reason() for typed extraction of failure info - Document context construction and tab filtering in DEVELOP.md

docs/docs/00200-core-concepts/00300-tables/00200-column-types.md

Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com> Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>

cloutiertyler · 2026-01-16T21:44:14Z

/update-llm-benchmark

Added missing C# tab examples for: - Filtering Rows by Caller (Message table, MyMessages view) - Hiding Sensitive Columns (UserAccount table, PublicUserProfile type, MyProfile view) - Combining Both Techniques (Employee table, TeamMember type, MyTeam view)

jdetter

Last little review on this

docs/docs/00200-core-concepts/00300-tables/00400-access-permissions.md

- Removed the leaderboard example that used .iter() to scan all rows - Added "Why Views Cannot Use .iter()" section explaining: - Views are black boxes that can't be incrementally evaluated - Full table scans create pessimistic read sets requiring full re-evaluation - Index lookups enable targeted invalidation - SQL subscriptions can scan because the query engine can compute incremental updates - The tradeoff is acceptable for indexed access patterns

Signed-off-by: John Detter <4099508+jdetter@users.noreply.github.com>

Changed from .iter() to filtering on a btree-indexed score column to demonstrate how to get high scorers without full table scans.

cloutiertyler · 2026-01-16T22:34:15Z

/update-llm-benchmark

All 21 C# task prompts now use PascalCase table names matching their corresponding golden answers. This fixes the mismatch where prompts used lowercase (e.g., "users", "primitives") but golden answers used PascalCase (e.g., "User", "Primitive").

cloutiertyler · 2026-01-16T23:03:03Z

/update-llm-benchmark

Anthropic: - Add anthropic-beta: prompt-caching-2024-07-31 header - Add cache_control: {"type": "ephemeral"} to static docs prefix - This reduces costs by ~90% for cached tokens after the first request OpenAI: - Added documentation noting automatic caching behavior - OpenAI's Responses API caches repeated prefixes automatically - Static docs prefix placed first to maximize cache hits

cloutiertyler · 2026-01-17T02:16:40Z

/update-llm-benchmark

cloutiertyler and others added 13 commits January 12, 2026 20:13

Improve error message when table is not found

673a985

The error now hints that the table may be private, helping users diagnose visibility issues.

Make person table public in basic-react template

3c42af9

Replace --database flag with positional argument in spacetime dev

2296443

For consistency with other CLI commands (publish, call, logs, sql), the database name is now a positional argument instead of a flag. The --database flag is deprecated but still works with a warning.

Updated CLI docs

7148ecf

Update LLM benchmark results

7f50121

cloutiertyler marked this pull request as ready for review January 14, 2026 00:29

cloutiertyler requested review from bfops and jdetter as code owners January 14, 2026 00:29

cloutiertyler changed the title ~~Tyler/claude docs 3~~ Further misc docs changes Jan 14, 2026

Fix broken documentation links

acd1d84

- /tables/columns -> /tables/column-types (page was renamed) - /tables/scheduled-tables -> /tables/schedule-tables (page was renamed)

cloutiertyler force-pushed the tyler/claude-docs-3 branch from a1ba53a to acd1d84 Compare January 14, 2026 00:59

cloutiertyler added 7 commits January 13, 2026 23:40

Merge origin/master into tyler/claude-docs-3

e54e7b9

Add table access examples to reducers documentation

1f33925

Cover all CRUD operations with code samples in all three languages: insert, find, filter, update, delete, iter, and count.

jdetter reviewed Jan 15, 2026

View reviewed changes

docs/docs/00100-intro/00200-quickstarts/00100-react.md Outdated Show resolved Hide resolved

jdetter reviewed Jan 15, 2026

View reviewed changes

cloutiertyler commented Jan 15, 2026

View reviewed changes

docs/docs/00200-core-concepts/00300-tables/00230-auto-increment.md Outdated Show resolved Hide resolved

cloutiertyler commented Jan 15, 2026

View reviewed changes

docs/docs/00200-core-concepts/00300-tables/00230-auto-increment.md Outdated Show resolved Hide resolved

jdetter reviewed Jan 16, 2026

View reviewed changes

docs/docs/00200-core-concepts/00400-subscriptions.md Outdated Show resolved Hide resolved

jdetter approved these changes Jan 16, 2026

View reviewed changes

Update Lib.cs

bb6950d

Signed-off-by: John Detter <4099508+jdetter@users.noreply.github.com>

clockwork-labs-bot and others added 2 commits January 16, 2026 13:09

Update LLM benchmark results

f43151b

cloutiertyler commented Jan 16, 2026

View reviewed changes

docs/docs/00200-core-concepts/00300-tables/00200-column-types.md Outdated Show resolved Hide resolved

Fix C# template table names to use PascalCase

b1fb0b7

cloutiertyler commented Jan 16, 2026

View reviewed changes

docs/docs/00200-core-concepts/00300-tables/00200-column-types.md Outdated Show resolved Hide resolved

Apply suggestions from code review

44a5eb3

Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com> Signed-off-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>

cloutiertyler added 4 commits January 16, 2026 16:51

Small fix

376608c

Fixed bug with Rust example

9b6ba56

Fixed typescript bug

ebd5d8f

jdetter reviewed Jan 16, 2026

View reviewed changes

cloutiertyler and others added 7 commits January 16, 2026 17:14

Clarify Query return type as alternative to indexed access in views

fa0edcc

Apply suggestions from code review

77444a8

Signed-off-by: John Detter <4099508+jdetter@users.noreply.github.com>

Add back leaderboard example using btree index filter

0c9debd

Changed from .iter() to filtering on a btree-indexed score column to demonstrate how to get high scorers without full table scans.

Add C# example for Region-Based Design in views.md

4047284

Switched links to use maincloud instead of localhost in examples

30de53b

Fixed the my-spacetime-app problem

6c34fe2

cloutiertyler added 2 commits January 16, 2026 17:39

Always post new PR comment instead of updating existing one

4585f6a

Update LLM benchmark results

201ca8f

Further misc docs changes #4029

Are you sure you want to change the base?

Further misc docs changes #4029

Uh oh!

Conversation

cloutiertyler commented Jan 13, 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!

Uh oh!

jdetter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jdetter left a comment

Choose a reason for hiding this comment

Uh oh!

cloutiertyler commented Jan 16, 2026

Uh oh!

Uh oh!

Uh oh!

cloutiertyler commented Jan 16, 2026

Uh oh!

jdetter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cloutiertyler commented Jan 16, 2026

Uh oh!

cloutiertyler commented Jan 16, 2026

Uh oh!

cloutiertyler commented Jan 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

cloutiertyler commented Jan 13, 2026 •

edited

Loading