Skip to content

Commit 61be6e6

Browse files
Update docs for primary key views (#4620)
# Description of Changes Updates the reference docs with the implications of primary key inference for query builder views, implemented in #4572, #4573, #4614. # API and ABI breaking changes None # Expected complexity level and risk 1. Docs only change # Testing N/A
1 parent 90b9e06 commit 61be6e6

4 files changed

Lines changed: 14 additions & 2 deletions

File tree

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1226,6 +1226,14 @@ fn levels_for_high_scorers(ctx: &AnonymousViewContext) -> impl Query<PlayerLevel
12261226
</TabItem>
12271227
</Tabs>
12281228

1229+
### Primary Key Inference for Query Builder Views
1230+
1231+
Query builder views may carry primary-key semantics from their underlying row type.
1232+
When a view's row type maps to a table with a primary key,
1233+
generated client bindings can treat the view like a primary-key table for client-cache updates.
1234+
In particular, update callbacks (`on_update` / `OnUpdate` / `onUpdate`) will be generated for these view handles.
1235+
If a primary key cannot be inferred for the view row type, clients fall back to insert/delete-only behavior for that view handle.
1236+
12291237
## Next Steps
12301238

12311239
- Review [Subscriptions](../00400-subscriptions.md) for real-time client data access

docs/docs/00200-core-concepts/00600-clients/00500-rust-reference.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1059,7 +1059,7 @@ The `on_delete` callback runs whenever a previously-resident row is deleted from
10591059
spacetimedb_sdk::TableWithPrimaryKey
10601060
```
10611061

1062-
Implemented for table handles whose tables have a primary key.
1062+
Implemented for handles whose rows have a known primary key, including query builder views with inferred primary keys.
10631063

10641064
| Name | Description |
10651065
| ------------------------------------------- | ------------------------------------------------------------------------------------ |
@@ -1079,6 +1079,8 @@ trait spacetimedb_sdk::TableWithPrimaryKey {
10791079

10801080
The `on_update` callback runs whenever an already-resident row in the client cache is updated, i.e. replaced with a new row that has the same primary key. Registering an `on_update` callback returns a callback id, which can later be passed to `remove_on_update` to cancel the callback. Newly registered or canceled callbacks do not take effect until the following event.
10811081

1082+
This also applies to query builder views over tables with primary keys.
1083+
10821084
### Unique constraint index access
10831085

10841086
For each unique constraint on a table, its table handle has a method whose name is the unique column name which returns a unique index handle. The unique index handle has a method `.find(desired_val: &Col) -> Option<Row>`, where `Col` is the type of the column, and `Row` the type of rows. If a row with `desired_val` in the unique column is resident in the client cache, `.find` returns it.

docs/docs/00200-core-concepts/00600-clients/00600-csharp-reference.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1031,6 +1031,8 @@ class RemoteTableHandle
10311031

10321032
The `OnUpdate` callback runs whenever an already-resident row in the client cache is updated, i.e. replaced with a new row that has the same primary key. The table must have a primary key for callbacks to be triggered. Newly registered or canceled callbacks do not take effect until the following event.
10331033

1034+
This also applies to query builder views over tables with primary keys.
1035+
10341036
See [the quickstart](../../00100-intro/00200-quickstarts/00600-c-sharp.md) for examples of registering and unregistering row callbacks.
10351037

10361038
### Unique constraint index access

docs/docs/00200-core-concepts/00600-clients/00700-typescript-reference.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -990,7 +990,7 @@ class TableHandle {
990990

991991
The `onUpdate` callback runs whenever an already-resident row in the client cache is updated, i.e. replaced with a new row that has the same primary key.
992992

993-
Only tables with a declared primary key expose `onUpdate` callbacks. Handles for tables without a declared primary key will not have `onUpdate` or `removeOnUpdate` methods.
993+
Only handles with a declared or inferred primary key expose `onUpdate` callbacks. Handles for tables or views without a known primary key will not have `onUpdate` or `removeOnUpdate` methods. Only views over tables with primary keys will expose `onUpdate` callbacks.
994994

995995
The `Row` type will be an autogenerated type which matches the row type defined by the module.
996996

0 commit comments

Comments
 (0)