SpacetimeDB 索引实战指南B-tree 与 Direct 索引的声明、查询与设计优化【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB索引Index是 SpacetimeDB 模块开发中加速查询的核心手段。本文基于 SpacetimeDB 1.12.0 官方文档的 Indexes 章节系统讲解索引的作用机制、两种索引类型B-tree 与 Direct的适用场景、Rust / TypeScript / C# 三种语言下的声明语法、基于索引的等值与范围查询、删除操作以及索引设计的核心原则并结合仓库源码如 crates/table/src/table_index/ 下的索引实现剖析其底层原理帮助你在实际模块中做出正确的索引取舍。什么是索引用空间换时间的查询加速器索引通过为表维护额外的有序数据结构来加速查询。没有索引时要找出满足条件的行数据库必须逐行扫描整张表有索引时数据库可以直接定位到匹配的行将全表扫描Full Table Scan降为索引查找Index Lookup。这种牺牲写入、加速读取的权衡是所有索引系统的共性SpacetimeDB 也不例外索引会额外占用内存索引会拖慢插入insert与更新update因为每次数据变更都必须同步维护索引结构。因此应当基于真实查询模式来添加索引而不是投机性地盲目建索引。此外主键Primary Key与唯一约束Unique Constraint会自动创建索引这些列无需再单独添加索引。什么场景该加索引场景典型示例按外键过滤背包inventory表中的player_id列当经常按属于某个玩家的物品查询时范围查询age列当经常查询某个年龄段内的用户时排序出现在ORDER BY子句中的列索引本身维护了有序结构SpacetimeDB 支持两种索引类型类型适用场景支持的键类型多列支持B-tree通用场景任意类型支持Direct稠密整数序列u8、u16、u32、u64不支持从仓库源码也可以印证这两类索引的划分在 crates/table/src/table_index/mod.rs 的TypedIndex枚举中直接索引只存在四个变体UniqueDirectU8、UniqueDirectU16、UniqueDirectU32、UniqueDirectU64外加内部使用的UniqueDirectSumTag而 B-tree 索引则覆盖了从布尔、整数、浮点、字符串到字节键的几乎全部类型。B-tree 索引默认且通用的选择B-tree 以有序方式维护数据因此同时支持等值查找x 5范围查询x 5、x BETWEEN 1 AND 10多列索引的前缀匹配详见下文多列索引一节B-tree 是 SpacetimeDB 的默认索引类型也是绝大多数场景下最稳妥的选择。从源码看B-tree 索引在 crates/table/src/table_index/btree_index.rs 中实现而模块 crates/table/src/table_index/mod.rs 的模块注释说明了其优化思路索引实现按具体的键类型做了特化specialization例如u64::cmp的整数比较远比AlgebraicValue::cmp的通用比较更快从而显著提升整数键的查询性能。Direct 索引直接以键值作数组下标的 O(1) 查找Direct 索引不使用树遍历而是直接用键值作为数组偏移array offset因此对无符号整数键提供O(1) 查找。其底层实现位于 crates/table/src/table_index/unique_direct_index.rs 的UniqueDirectIndexK外层是一个VecOptionInnerIndex每个InnerIndex是按操作系统页大小PAGE_SIZE 4_096字节划分的RowPointer数组KEYS_PER_INNER PAGE_SIZE / size_of::RowPointer()键值被拆分为外键与内键后直接索引到对应槽位——seek_point因此只需要几次数组访问即可返回行指针。Direct 索引在以下条件下表现良好键是稠密的值之间空隙少键从接近 0 开始插入模式是顺序的而非随机的。Direct 索引在以下条件下表现糟糕键是稀疏的值之间空隙大第一个插入的键就很大插入模式高度随机。源码中还体现了一个重要细节当插入的键超过u32::MAX约 42 亿时UniqueDirectIndex::insert_maybe_despecialize会返回Despecialize错误触发索引降级为 B-tree以避免大u64键导致内存溢出OOMUniqueDirectIndex::into_btree方法也提供了将 Direct 索引转换为 B-tree 索引的完整逻辑。Direct 索引的限制仅支持单列索引仅支持无符号整数类型u8、u16、u32、u64。适用建议用于自增主键或其他稠密顺序标识符当你需要极致的查找性能时。注意当前 Direct 索引仅在Rust 与 TypeScript中可用C# 支持正在规划中。以下示例来自 SpacetimeDB 的官方基准测试模块 modules/benchmarks/src/ia_loop.rs它用 Direct 索引存储了百万级实体实体 ID 从 0 开始顺序递增从而在按实体 ID 关联位置与速度数据时获得 O(1) 查找const position table( { name: position, public: true }, { id: t.u32().primaryKey().index(direct), x: t.f32(), y: t.f32(), z: t.f32(), } );#[spacetimedb::table(name position, public)] pub struct Position { #[primary_key] #[index(direct)] id: u32, x: f32, y: f32, z: f32, }多数场景下B-tree 索引在没有这些限制的前提下就能提供良好的性能。建议仅在性能剖析profiling确认索引查找确实是瓶颈、且你的键分布恰好符合上述理想模式时才考虑 Direct 索引。单列索引字段级与表级两种声明方式单列索引加速对某一列的过滤查询既可以在字段级别声明也可以在表级别声明。字段级语法声明直接写在列上const user table( { name: user, public: true }, { id: t.u32().primaryKey(), name: t.string().index(btree), age: t.u8().index(btree), } );[SpacetimeDB.Table(Name User, Public true)] public partial struct User { [SpacetimeDB.PrimaryKey] public uint Id; [SpacetimeDB.Index.BTree] public string Name; [SpacetimeDB.Index.BTree] public byte Age; }#[spacetimedb::table(name user, public)] pub struct User { #[primary_key] id: u32, #[index(btree)] name: String, #[index(btree)] age: u8, }表级语法索引与列分离可显式命名表级语法将索引声明与列定义分开便于显式指定索引名称。表级索引名称会在后续的查询访问器中用到例如by_player_and_level。const user table( { name: user, public: true, indexes: [ { name: idx_age, algorithm: btree, columns: [age] }, ], }, { id: t.u32().primaryKey(), name: t.string(), age: t.u8(), } );[SpacetimeDB.Table(Name User, Public true)] [SpacetimeDB.Index.BTree(Name idx_age, Columns new[] { Age })] public partial struct User { [SpacetimeDB.PrimaryKey] public uint Id; public string Name; public byte Age; }#[spacetimedb::table(name user, public, index(name idx_age, btree(columns [age])))] pub struct User { #[primary_key] id: u32, name: String, age: u8, }从宏定义侧看crates/bindings-macro/src/table.rs 中的IndexType枚举BTree { columns }、Hash { columns }、Direct { column }正是上述语法的解析目标而索引最终以IndexAlgorithm的形式存入模块定义crates/schema/src/def.rs 中的DirectAlgorithm { column: ColId }结构体即对应 Direct 索引只索引单列的约束。模块发布后索引元数据会持久化到系统表见 crates/datastore/src/system_tables.rs 的StIndexAlgorithm其中 Direct 索引以Direct { column: ColId }变体进行 BSATN 序列化往返。多列索引复合索引多列索引Composite Index跨越多个列。索引维护行时先按第一列排序第一列值相同的行再按第二列排序依此类推。多列索引支持三种查询模式全匹配Full match查询条件指定了全部索引列前缀匹配Prefix match查询条件只指定了按顺序的最左侧列尾列范围Range on trailing column前缀为等值条件后续一列是范围条件。以(player_id, level)上的多列索引为例它能加速以下查询player_id 123第一列的前缀匹配player_id 123 AND level 5全匹配player_id 123 AND level 5前缀匹配 范围但该索引无法加速单独针对level的查询因为level不是索引的前缀。const score table( { name: score, public: true, indexes: [ { name: by_player_and_level, algorithm: btree, columns: [player_id, level] }, ], }, { player_id: t.u32(), level: t.u32(), points: t.i64(), } );[SpacetimeDB.Table(Name Score, Public true)] [SpacetimeDB.Index.BTree(Name by_player_and_level, Columns new[] { PlayerId, Level })] public partial struct Score { public uint PlayerId; public uint Level; public long Points; }#[spacetimedb::table(name score, public, index(name by_player_and_level, btree(columns [player_id, level])))] pub struct Score { player_id: u32, level: u32, points: i64, }基于索引的查询类型安全的访问器SpacetimeDB 会为每个索引生成类型安全的访问器方法accessor。这些方法接受过滤参数并返回匹配的行。Rust 侧访问器的类型约束定义在 crates/bindings/src/table.rs 中——等值过滤WithPointArgK与范围过滤IndexScanRangeBoundsIndexType, K分别约束了可用的参数类型从编译期就杜绝了用错误类型查询索引的可能。等值查询传一个值// Find users with a specific name for (const user of ctx.db.user.name.filter(Alice)) { console.log(Found user: ${user.id}); }// Find users with a specific name foreach (var user in ctx.Db.User.Name.Filter(Alice)) { Log.Info($Found user: {user.Id}); }// Find users with a specific name for user in ctx.db.user().name().filter(Alice) { log::info!(Found user: {}, user.id); }范围查询传入 Range 对象传入Range对象可查询索引列落在指定范围内的行。Range构造器接受from与to两个边界每个边界可指定为{ tag: included, value }闭区间、{ tag: excluded, value }开区间或{ tag: unbounded }无界。TypeScript 侧的RangeT类实现在 crates/bindings-typescript/src/server/range.ts其构造器签名为constructor(from?: BoundT | null, to?: BoundT | null)边界缺省即视为unbounded。import { Range } from spacetimedb/server; // Find users aged 18 to 65 (inclusive) for (const user of ctx.db.user.age.filter( new Range({ tag: included, value: 18 }, { tag: included, value: 65 }) )) { console.log(${user.name} is ${user.age}); } // Find users aged 18 or older (from 18 inclusive, unbounded above) for (const user of ctx.db.user.age.filter( new Range({ tag: included, value: 18 }, { tag: unbounded }) )) { console.log(${user.name} is an adult); } // Find users younger than 18 (unbounded below, to 18 exclusive) for (const user of ctx.db.user.age.filter( new Range({ tag: unbounded }, { tag: excluded, value: 18 }) )) { console.log(${user.name} is a minor); }// Find users aged 18 or older foreach (var user in ctx.Db.User.Age.Filter(new Boundbyte.Inclusive(18), null)) { Log.Info(${user.Name} is an adult); }// Find users aged 18 to 65 (inclusive) for user in ctx.db.user().age().filter(18..65) { log::info!({} is {}, user.name, user.age); } // Find users aged 18 or older for user in ctx.db.user().age().filter(18..) { log::info!({} is an adult, user.name); } // Find users younger than 18 for user in ctx.db.user().age().filter(..18) { log::info!({} is a minor, user.name); }Rust 直接使用原生RangeBounds语法18..65、18..、..18C# 使用BoundT.Inclusive(18)/null表示边界三种语言的语义完全一致。多列查询元组传参对于多列索引传入一个元组。前缀列可指定精确值尾列最后一个位置可选地传入范围import { Range } from spacetimedb/server; // Find all scores for player 123 (prefix match on first column) for (const score of ctx.db.score.by_player_and_level.filter(123)) { console.log(Level ${score.level}: ${score.points} points); } // Find scores for player 123 at levels 1-10 (inclusive) for (const score of ctx.db.score.by_player_and_level.filter([ 123, new Range({ tag: included, value: 1 }, { tag: included, value: 10 }) ])) { console.log(Level ${score.level}: ${score.points} points); } // Find the exact score for player 123 at level 5 for (const score of ctx.db.score.by_player_and_level.filter([123, 5])) { console.log(Points: ${score.points}); }// Find all scores for player 123 foreach (var score in ctx.Db.Score.by_player_and_level.Filter(123u)) { Log.Info($Level {score.Level}: {score.Points} points); }// Find all scores for player 123 (prefix match) for score in ctx.db.score().by_player_and_level().filter(123u32) { log::info!(Level {}: {} points, score.level, score.points); } // Find scores for player 123 at levels 1-10 for score in ctx.db.score().by_player_and_level().filter((123u32, 1u32..10u32)) { log::info!(Level {}: {} points, score.level, score.points); } // Find the exact score for player 123 at level 5 for score in ctx.db.score().by_player_and_level().filter((123u32, 5u32)) { log::info!(Points: {}, score.points); }基于索引的删除避免全表扫描索引同样能加速删除操作无需扫描整张表定位待删除的行可以直接按索引值删除。delete方法返回被删除的行数import { Range } from spacetimedb/server; // Delete all users named Alice const deleted ctx.db.user.name.delete(Alice); console.log(Deleted ${deleted} user(s)); // Delete users younger than 18 const deletedMinors ctx.db.user.age.delete( new Range({ tag: unbounded }, { tag: excluded, value: 18 }) ); console.log(Deleted ${deletedMinors} minor(s));// Delete all users named Alice var deleted ctx.Db.User.Name.Delete(Alice); Log.Info($Deleted {deleted} user(s));// Delete all users named Alice let deleted ctx.db.user().name().delete(Alice); log::info!(Deleted {} user(s), deleted); // Delete users in an age range let deleted ctx.db.user().age().delete(..18); log::info!(Deleted {} minor(s), deleted);索引设计指南基于查询模式选择列。索引应覆盖出现在 WHERE 子句与 JOIN 条件中的列。未被使用的索引只会浪费内存。仓库基准测试 modules/benchmarks/src/ia_loop.rs 展示了两种典型取舍用于范围扫描的quad: i64与location_x: i32采用#[index(btree)]而稠密自增的实体主键则采用 Direct 索引两者各取所长。考虑多列索引中的列顺序。将选择性最高能最大程度缩小结果集的列放在最前面随后是用于范围条件的列。例如(country, city)上的索引对仅查country或查country AND city都有效但对仅查city无效。避免冗余索引。(a, b)上的多列索引会让单独针对(a)的索引变得冗余多列索引已能处理前缀查询但如果独立查询b那么针对(b)的索引并不冗余。平衡读写性能。每个索引都加速读取、拖慢写入。写入量大、读取少的表应尽量减少索引数量。延伸阅读学习 主键与唯一约束Constraints——约束会自动创建索引理解二者关系有助于避免重复建索引查看 访问权限Access Permissions了解在 reducer 中查询表的权限模型如需进一步了解表定义的整体结构可阅读同目录下的 列类型 与 自增列 文档。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考