Skip to content

Commit fca10ae

Browse files
docs: Add supported index key types to Index docs page (#4606)
Fixes #4592 Adds a "Supported Column Types" section to the Index documentation page listing: - **Supported types**: integers (all widths), bool, String, Identity, ConnectionId, Uuid, Hash, and no-payload enums with `#[derive(SpacetimeType)]` - **Unsupported types**: floats (no total ordering), ScheduleAt/TimeDuration/Timestamp (not yet supported, links #2650), Vec/arrays, enums with payloads, nested structs - **Workaround tip**: scaled integers for floating-point coordinates - **Direct index restrictions**: only u8/u16/u32/u64 and no-payload enums The list is derived from the `FilterableValue` trait implementations in `crates/lib/src/filterable_value.rs` and the direct index validation in `crates/schema/src/def/validate/v9.rs`. Co-authored-by: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
1 parent cd65a07 commit fca10ae

File tree

1 file changed

+30
-0
lines changed

1 file changed

+30
-0
lines changed

docs/docs/00200-core-concepts/00300-tables/00300-indexes.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,36 @@ SpacetimeDB supports two index types:
3131
| B-tree | General purpose | Any | Yes |
3232
| Direct | Dense integer sequences | `u8`, `u16`, `u32`, `u64` | No |
3333

34+
### Supported Column Types
35+
36+
Not all column types can be used as index keys. The following types are supported for B-tree indexes:
37+
38+
| Category | Types |
39+
|----------|-------|
40+
| Integers | `u8`, `u16`, `u32`, `u64`, `u128`, `u256`, `i8`, `i16`, `i32`, `i64`, `i128`, `i256` |
41+
| Boolean | `bool` |
42+
| Strings | `String` |
43+
| Identifiers | `Identity`, `ConnectionId`, `Uuid`, `Hash` |
44+
| Enums | No-payload (C-style) enums annotated with `#[derive(SpacetimeType)]` |
45+
46+
The following types are **not** supported as index keys:
47+
48+
| Type | Reason |
49+
|------|--------|
50+
| `f32`, `f64` | Floating-point values do not have a total ordering (`NaN` is not comparable) |
51+
| `ScheduleAt`, `TimeDuration`, `Timestamp` | Not yet supported ([#2650](https://github.com/clockworklabs/SpacetimeDB/issues/2650)) |
52+
| `Vec<T>`, arrays | Variable-length collections are not indexable |
53+
| Enums with payloads | Only no-payload (C-style) enums are supported |
54+
| Nested structs | Product types cannot be used as index keys |
55+
56+
If you attempt to use an unsupported type as an index key, you will get a compile error. For multi-column indexes, every column in the index must use a supported type.
57+
58+
:::tip Workaround for floating-point data
59+
If you need to index floating-point coordinates (for example, `x` and `y` positions), consider storing them as scaled integers. For instance, multiply by 1000 and store as `i32` to get three decimal places of precision while remaining indexable.
60+
:::
61+
62+
Direct indexes have additional restrictions: only `u8`, `u16`, `u32`, `u64`, and no-payload enums are supported.
63+
3464
### B-tree Indexes
3565

3666
B-trees maintain data in sorted order, enabling both equality lookups (`x = 5`) and range queries (`x > 5`, `x BETWEEN 1 AND 10`). The sorted structure also supports prefix matching on multi-column indexes. B-tree is the default and most commonly used index type.

0 commit comments

Comments
 (0)