jeffhajewski/latticedb

LatticeDB – 埋め込み型グラフ＋ベクトル検索データベース

概要 – LatticeDB は、単一ファイルの埋め込み型プロパティグラフデータベースで、高次元ベクトル（HNSW 経由）と全文（BM25）もインデックス化します。ローカルプログラムは、1 つの 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 は一度に 1 つのライターのみ許可します。
• 純粋に表形式のデータ – リレーショナルデータベース（SQLite、PostgreSQL）の方が簡単かもしれません。
• 大規模な同時書き込みまたは分散スケーリング – クライアントサーバーシステム（例：Neo4j、Qdrant）がより適切です。

---

次のステップ

• はじめに – docs/getting_started.md で CLI、Python、TS、Go、Java のセットアップを説明しています。
• 例 – examples/cli、examples/go、および言語固有の README を参照して、実行可能なデモを確認してください。
• ベンチマーク – zig build benchmark または特定のベクトル/グラフ/FTS ベンチマークを実行して、数値を再現します。

LatticeDB は、グラフトラバーサル、ベクトル類似性、全文検索をすべて一緒に処理できる、高速でローカルな単一ファイルストアを求める人向けの専用エンジンです。