Struct Database 

pub struct Database<T: VectorType> { /* private fields */ }

数据库核心入口实例

Implementations

impl<T: VectorType + Serialize + DeserializeOwned> Database<T>

pub fn commit_tx(&mut self, builder: TxBuilder<T>) -> Result<Vec<NodeId>>

通过 TxBuilder 原子提交事务（FFI 友好入口）

let mut builder = TxBuilder::new();
builder.insert(&[1.0, 0.0], json!({"name": "Alice"}));
let ids = db.commit_tx(builder)?;

impl<T: VectorType + Serialize + DeserializeOwned> Database<T>

pub fn open(path: &str, dim: usize) -> Result<Self>

打开或创建数据库（默认：Mmap 模式，SyncMode::Normal）

pub fn open_with_sync( path: &str, dim: usize, sync_mode: SyncMode, ) -> Result<Self>

打开或创建数据库，指定 WAL 同步模式 (向后兼容)

pub fn open_with_config(path: &str, config: Config) -> Result<Self>

打开或创建数据库（高级配置入口）

pub fn set_sync_mode(&mut self, mode: SyncMode)

运行时切换 WAL 同步模式

pub fn set_hook(&mut self, hook: impl SearchHook + 'static)

注册自定义检索管线 Hook

Hook 允许开发者在检索管线的 6 个关键阶段插入自定义逻辑：

1. on_pre_search — 查询预处理
2. on_custom_recall — 自定义召回（可替代内置）
3. on_post_recall — 召回后处理
4. on_pre_graph_expand — 图扩散前拦截
5. on_rerank — 自定义重排序
6. on_post_search — 最终后处理

示例

struct MyHook;
impl SearchHook for MyHook {
    fn on_post_recall(&self, hits: &mut Vec<SearchHit>, _ctx: &mut HookContext) {
        hits.retain(|h| h.score > 0.5);
    }
}
db.set_hook(MyHook);

pub fn clear_hook(&mut self)

移除当前 Hook，恢复为默认的 NoopHook

pub fn hook(&self) -> &dyn SearchHook

获取当前 Hook 的引用（主要用于测试和调试）

pub fn build_quiver_index(&mut self, config: Option<QuIVerConfig>) -> Result<()>

构建 QuIVer BQ-native HNSW 图索引

从当前所有活跃数据构建 ANN 图索引，替代默认的三级火箭管线。 构建后的搜索将自动使用 QuIVer 的 O(log N) 图搜索。

冷热分离：

• Hot: 2-bit BQ 签名 + HNSW 图拓扑 (~2 bits/dim/node)
• Cold: f32 原始向量（仅精排阶段按需访问）

事务安全: delete / update_vector 会使索引自动失效，管线回退到三级火箭。

use triviumdb::index::quiver::QuIVerConfig;
db.build_quiver_index(None); // 使用默认配置 (m=16, ef_c=128, α=1.2)

pub fn set_memory_limit(&mut self, bytes: usize)

设置内存上限（字节）

当 MemTable 估算内存超过此值时，写操作后会自动触发 flush 落盘。 设为 0 表示无限制（默认）。

pub fn estimated_memory(&self) -> usize

查询当前 MemTable 估算内存占用（字节）

pub fn enable_auto_compaction(&mut self, interval: Duration)

启动后台自动 Compaction 线程

pub fn disable_auto_compaction(&mut self)

pub fn compact(&mut self) -> Result<()>

主动触发全量重写与压实（Manual Compaction）

pub fn insert(&mut self, vector: &[T], payload: Value) -> Result<NodeId>

pub fn insert_with_id( &mut self, id: NodeId, vector: &[T], payload: Value, ) -> Result<()>

pub fn link( &mut self, src: NodeId, dst: NodeId, label: &str, weight: f32, ) -> Result<()>

pub fn delete(&mut self, id: NodeId) -> Result<()>

pub fn unlink(&mut self, src: NodeId, dst: NodeId) -> Result<()>

pub fn update_payload(&mut self, id: NodeId, payload: Value) -> Result<()>

pub fn update_vector(&mut self, id: NodeId, vector: &[T]) -> Result<()>

pub fn leiden_cluster( &self, min_community_size: usize, max_iterations: Option<usize>, with_centroids: Option<bool>, ) -> Result<LeidenResult>

基于内存图谱进行 Leiden/Louvain 近似快速聚类（无锁设计）

pub fn index_keyword(&mut self, id: NodeId, keyword: &str) -> Result<()>

pub fn index_text(&mut self, id: NodeId, text: &str) -> Result<()>

pub fn build_text_index(&mut self) -> Result<()>

pub fn get_payload(&self, id: NodeId) -> Option<Value>

pub fn get_edges(&self, id: NodeId) -> Vec<Edge>

pub fn get_all_ids(&self) -> Vec<NodeId>

pub fn search( &self, query_vector: &[T], top_k: usize, expand_depth: usize, min_score: f32, ) -> Result<Vec<SearchHit>>

pub fn search_advanced( &self, query_vector: &[T], config: &SearchConfig, ) -> Result<Vec<SearchHit>>

pub fn search_hybrid_with_context( &self, query_text: Option<&str>, query_vector: Option<&[T]>, config: &SearchConfig, ) -> Result<(Vec<SearchHit>, HookContext)>

带 Hook 上下文的混合检索（完整版）

与 search_hybrid 相同，但额外返回 HookContext， 开发者可以从中读取 Hook 各阶段注入的自定义数据和计时统计。

pub fn search_hybrid( &self, query_text: Option<&str>, query_vector: Option<&[T]>, config: &SearchConfig, ) -> Result<Vec<SearchHit>>

全能混合检索核心引擎 (Hybrid Advanced Pipeline)

包含文本稀疏索引 + 稠密连续向量空间 + 图谱数学约束的真正完全体检索引擎。 具体实现委托给 pipeline::execute_pipeline。

pub fn get(&self, id: NodeId) -> Option<NodeView<T>>

pub fn neighbors(&self, id: NodeId, depth: usize) -> Vec<NodeId>

pub fn create_index(&mut self, field: &str)

创建属性索引：对指定 payload 字段建立倒排索引，加速 MATCH/FIND 查询

db.create_index("name");   // 之后 MATCH (a {name: "Alice"}) 将使用 O(1) 索引
db.create_index("type");   // FIND {type: "event"} 同样受益

pub fn drop_index(&mut self, field: &str)

删除属性索引

pub fn tql(&self, input: &str) -> Result<TqlResult<T>>

TQL (Trivium Query Language) 统一查询入口

支持三种查询模式：

• FIND {type: "event"} RETURN * — 文档过滤
• MATCH (a)-[:knows]->(b) WHERE b.age > 20 RETURN b — 图遍历
• SEARCH VECTOR [...] TOP 10 RETURN * — 向量检索

let results = db.tql("FIND {type: \"event\", heat: {$gte: 0.7}} RETURN * LIMIT 10")?;

pub fn tql_mut(&mut self, input: &str) -> Result<TqlMutResult>

TQL 写操作入口

支持三种写操作：

• CREATE ({name: "Alice", age: 30}) — 创建节点
• MATCH (a) WHERE a.name == "Alice" SET a.age == 31 — 更新字段
• MATCH (a) WHERE a.name == "Alice" DELETE a — 删除节点
• MATCH (a) WHERE a.name == "Alice" DETACH DELETE a — 删除节点及其边
• MATCH (a), (b) WHERE ... CREATE (a)-[:knows]->(b) — 创建边

也兼容读查询（自动降级为 tql()），返回 affected=0。

let result = db.tql_mut(r#"CREATE ({name: "Alice", age: 30})"#)?;
assert_eq!(result.created_ids.len(), 1);

pub fn flush(&mut self) -> Result<()>

将内存数据持久化到磁盘

安全顺序（防止崩溃丢数据）：

1. 原子写入 .tdb（写 .tmp → fsync → rename）
2. 确认 .tdb 写入成功后，才清除 WAL

pub fn close(self) -> Result<()>

pub fn node_count(&self) -> usize

pub fn contains(&self, id: NodeId) -> bool

pub fn dim(&self) -> usize

pub fn all_node_ids(&self) -> Vec<NodeId>

获取所有活跃节点的 ID 列表

pub fn migrate_to( &self, new_path: &str, new_dim: usize, ) -> Result<(Database<T>, Vec<NodeId>)>

where T: Serialize + DeserializeOwned,

维度迁移：从当前数据库导出所有节点和边到一个新维度的数据库。

pub fn begin_tx(&mut self) -> Transaction<'_, T>

开启一个轻量级事务

事务期间所有写操作仅缓冲在内存中，调用 commit() 后原子性写入。

Trait Implementations

impl<T: VectorType> Drop for Database<T>

安全析构：确保 WAL BufWriter 的缓冲数据在 Database 被 drop 时显式落盘。

fn drop(&mut self)

Executes the destructor for this type.