jeffhajewski/latticedb

LatticeDB – 嵌入式图加向量搜索数据库

它是什么 – LatticeDB 是一个单文件、嵌入式的属性图数据库，同时也索引高维向量（通过 HNSW）和全文（BM25）。它让本地程序可以使用一种 Cypher 风格的查询语言，通过关系、语义相似度或关键词搜索来查询相同的数据。

主要卖点

• 单文件，零配置 – 整个数据库（图、向量、FTS、WAL）都存放在一个可移植文件中；不需要服务器进程。
• 统一查询层 – MATCH … WHERE node.embedding <=> $vec < 0.3 AND node.text @@ "keyword" 可以在单个语句中工作。
• 嵌入式、单写入者模型 – 非常适合在单台机器上运行的桌面应用、工具或代理。
• 快速 – 亚微秒节点查找、在 100 万向量上约 0.8 毫秒的 10-NN 搜索（100% 召回率），以及 19 微秒的 BM25 文本搜索。
• 绑定 – 原生 C API，以及 Python、TypeScript/Node、Go 和 Java 的一流库。

---

安装

语言	命令
CLI	curl -fsSL https://raw.githubusercontent.com/jeffhajewski/latticedb/main/dist/install.sh | bash
Python	pip install latticedb
TypeScript / Node	npm install @hajewski/latticedb
Java	通过 bindings/java README 构建 JNI 桥接（JDK 21+）。
Go	遵循 bindings/go/README.md（cgo 工作流程）。

包在支持的平台上捆绑了原生 liblattice 库；您也可以使用 LATTICE_BUNDLE_LIB_DIR 环境变量来暂存自定义构建。

---

快速示例（Python）

from latticedb import Database
from latticedb.embedding import hash_embed

with Database("knowledge.db", create=True, enable_vectors=True, vector_dimensions=128) as db:
    db.create_node_fts_index("Chunk", "text")
    with db.write() as txn:
        alice = txn.create_node(labels=["Person"], properties={"name": "Alice"})
        doc   = txn.create_node(labels=["Document"], properties={"title": "Attention Is All You Need"})
        chunk = txn.create_node(labels=["Chunk"], properties={"text": "The transformer architecture uses self‑attention..."})
        txn.set_vector(chunk.id, "embedding", hash_embed("transformer self‑attention", 128))
        txn.create_edge(chunk.id, doc.id, "PART_OF")
        txn.create_edge(doc.id, alice.id, "AUTHORED_BY")
        txn.commit()

    results = db.query(
        """
        MATCH (c:Chunk)-[:PART_OF]->(d:Document)-[:AUTHORED_BY]->(a:Person)
        WHERE c.embedding <=> $q < 0.5
        RETURN d.title, c.text, a.name
        ORDER BY c.embedding <=> $q
        LIMIT 5
        """,
        parameters={"q": hash_embed("attention mechanism", 128)}
    )
    for r in results:
        print(r["d.title"], "by", r["a.name"])

同样的模式也适用于 TypeScript、Go 和 Java（完整代码片段请参阅 README）。

---

性能亮点（来自仓库的基准测试）

操作	延迟	吞吐量
节点查找（缓存）	0.13 微秒	7.9 百万操作/秒
10-NN HNSW（100 万向量）	0.83 毫秒（平均，100% 召回率）	1.2 千查询/秒
全文 BM25（100 文档）	19 微秒	53 千查询/秒
2 跳图遍历（10 万节点）	39 微秒	–

与流行的替代方案相比，LatticeDB 的节点查找与内存中的 RocksDB 相当，其向量搜索优于 FAISS 单线程 HNSW，并与基于服务器的 Weaviate/Qdrant 相当，而其 BM25 搜索比 SQLite FTS5 快约 300 倍。

---

核心功能

• 图 – 带标签的节点/边、属性索引、ACID 事务、MERGE/UNWIND、聚合。
• 向量搜索 – HNSW ANN、可配置的 M/ef、批量导入、内置哈希嵌入辅助程序或 HTTP 客户端用于真实模型。
• 全文 – BM25 倒排索引、分词、词干提取、模糊 Levenshtein 搜索。
• Cypher 方言 – MATCH、WHERE、RETURN、CREATE、DELETE、ORDER BY、LIMIT，加上自定义运算符 <=>（向量距离）和 @@（文本匹配）。
• 持久性 – 预写日志、时间点备份、热备份、压缩空闲列表。
• 事件流 – 命名变更摘要共享相同的 WAL，适用于反应式代理。
• 内存模式 – :memory: 打开一个没有文件 I/O 的临时数据库。

---

典型使用案例

• 需要图关系和语义搜索的本地知识库、笔记应用或个人搜索工具。
• 代理记忆 / RAG 管道，其中单个进程存储块、嵌入和元数据，并一起查询。
• 在不运行单独服务器的情况下原型化图中心应用（Neo4j 或 Weaviate 的轻量级替代方案）。

---

何时考虑其他方案

• 多进程或网络工作负载 – LatticeDB 一次只允许一个写入者。
• 纯表格数据 – 关系型数据库（SQLite、PostgreSQL）可能更简单。
• 大量并发写入或分布式扩展 – 客户端-服务器系统（例如 Neo4j、Qdrant）更合适。

---

下一步

• 开始使用 – docs/getting_started.md 逐步说明 CLI、Python、TS、Go 和 Java 设置。
• 示例 – 请参阅 examples/cli、examples/go 和语言特定的 README，以获取可运行的演示。
• 基准测试 – 运行 zig build benchmark 或特定的向量/图/FTS 基准测试来重现这些数字。

LatticeDB 是一个专用引擎，适合任何想要一个快速、本地、单文件存储，能够同时处理图遍历、向量相似度和全文搜索的人。