Skip to content

Commit e0fc8f6

Browse files
docs: Add supported index key types to Index docs page (#4592)
Lists which types can and cannot be used as index keys for both B-tree and direct indexes. Includes a workaround tip for floating-point data (scaled integers) and links to the open issue for Timestamp/TimeDuration support (#2650).
1 parent 6d9cf69 commit e0fc8f6

1 file changed

Lines changed: 30 additions & 0 deletions

File tree

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)