Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/docs/00200-core-concepts/00200-functions/00500-views.md
Original file line number Diff line number Diff line change
Expand Up @@ -1226,6 +1226,14 @@ fn levels_for_high_scorers(ctx: &AnonymousViewContext) -> impl Query<PlayerLevel
</TabItem>
</Tabs>

### Primary Key Inference for Query Builder Views

Query builder views may carry primary-key semantics from their underlying row type.
When a view's row type maps to a table with a primary key,
generated client bindings can treat the view like a primary-key table for client-cache updates.
In particular, update callbacks (`on_update` / `OnUpdate` / `onUpdate`) will be generated for these view handles.
If a primary key cannot be inferred for the view row type, clients fall back to insert/delete-only behavior for that view handle.

## Next Steps

- Review [Subscriptions](../00400-subscriptions.md) for real-time client data access
Original file line number Diff line number Diff line change
Expand Up @@ -1059,7 +1059,7 @@ The `on_delete` callback runs whenever a previously-resident row is deleted from
spacetimedb_sdk::TableWithPrimaryKey
```

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

| Name | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------------ |
Expand All @@ -1079,6 +1079,8 @@ trait spacetimedb_sdk::TableWithPrimaryKey {

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.

This also applies to query builder views over tables with primary keys.

### Unique constraint index access

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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1031,6 +1031,8 @@ class RemoteTableHandle

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.

This also applies to query builder views over tables with primary keys.

See [the quickstart](../../00100-intro/00200-quickstarts/00600-c-sharp.md) for examples of registering and unregistering row callbacks.

### Unique constraint index access
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -990,7 +990,7 @@ class TableHandle {

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.

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.
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.

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

Expand Down
Loading