jeffhajewski/latticedb

Embedded single-file knowledge graph database with vector search and full-text search for AI/RAG apps

LatticeDB – 임베디드 그래프+벡터 검색 데이터베이스

정의 – LatticeDB는 단일 파일 임베디드 속성 그래프 데이터베이스로, 고차원 벡터(HNSW 경유)와 전문(BM25)도 인덱싱합니다. 로컬 프로그램이 하나의 Cypher 스타일 쿼리 언어를 사용하여 관계, 의미적 유사성 또는 키워드 검색으로 동일한 데이터를 쿼리할 수 있습니다.

주요 장점

단일 파일, 구성 불필요 – 전체 데이터베이스(그래프, 벡터, FTS, WAL)가 휴대용 파일에 저장됩니다. 서버 프로세스가 필요 없습니다.
통합 쿼리 레이어 – MATCH … WHERE node.embedding <=> $vec < 0.3 AND node.text @@ "keyword"가 단일 문에서 작동합니다.
임베디드, 단일 작성자 모델 – 단일 머신에서 실행되는 데스크톱 앱, 도구 또는 에이전트에 이상적입니다.
빠름 – 서브마이크로초 노드 조회, 100만 벡터에서 약 0.8ms의 10-NN 검색(100% 재현율), 19µs의 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µs	7.9M ops/s
10-NN HNSW(100만 벡터)	0.83ms(평균, 100% 재현율)	1.2K 쿼리/s
전문 BM25(100개 문서)	19µs	53K 쿼리/s
2홉 그래프 순회(10만 노드)	39µs	–

인기 있는 대안과 비교할 때, 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는 그래프 순회, 벡터 유사성, 전문 검색을 모두 함께 처리할 수 있는 빠르고 로컬이며 단일 파일 저장소를 원하는 모든 사람을 위한 특수 목적 엔진입니다.