LatticeDB: The "SQLite" of Graph Databases

LatticeDB is an embedded, single-file property-graph database designed specifically for managing connected, semantic, and textual information. Much like SQLite provides a lightweight relational store, LatticeDB offers a zero-config, local solution for complex data relationships.

🚀 Core Value Proposition

LatticeDB allows developers to perform three distinct types of queries over a single dataset using a unified query layer:

1. Graph Traversal: Navigating complex relationships.
2. Vector Similarity: Performing semantic searches via HNSW.
3. Full-Text Search (FTS): Executing keyword searches via BM25.

While it is an ideal engine for just a database advanced AI applications like Graph RAG, agentic memory, and local knowledge bases, these are simply use cases—not the definition of the engine itself.

Technical Capabilities at a Glance

---

🛠 Architecture & Design

LatticeDB is optimized for a single-writer model on a single machine. It ensures durability through a Write-Ahead Log (WAL), which is shared by both graph writes and durable named streams.

Mathematical Foundation

Vector search in LatticeDB typically relies on calculating the distance between embeddings. For example, the similarity between a query vector $\mathbf{q}$ and a document vector $\mathbf{v}$ can be represented as:

$\text{similarity} = \cos(\theta) = \frac{\mathbf{q} \cdot \mathbf{v}}{\|\mathbf{q}\| \|\mathbf{v}\|}$

---

📦 Installation & Setup

Depending on your environment, you can integrate LatticeDB using the following methods:

• CLI: Install via shell script: curl -fsSL https://raw.githubusercontent.com/jeffhajewski/latticedb/main/dist/install.sh | bash
• Python: Install via pip: pip install latticedb
• TypeScript/Node.js: Install via npm: npm install @hajewski/latticedb

Developer Note: For source installations, you can bundle the native library by setting the environment variable LATTICE_BUNDLE_LIB_DIR=/path/to/lib.

Language-Specific Details

• Node.js: The default path utilizes pkg-config. For in-repo development, use the -tags repolocal flag against zig-out/lib.
• Go: Refer to examples/go for retrieval demonstrations.
• API Updates: Recent updates moved embedding helpers into specialized modules. Please consult docs/client_api_migration.md for current import aliases.

---

💻 Practical Examples

Python Implementation

The following example demonstrates creating a knowledge graph involving authors and documents, then querying it using hybrid search.

from embedding import hash_embed 
from latticedb import Database

# Initialize DB with vector support
with Database("knowledge.db", create=True, enable_vectors=True, vector_dimensions=128) as db:
    # --- Graph Construction ---
    with db.transaction() as txn:
        alice = txn.create_node(labels=["Person"], properties={"name": "Alice", "field": "ML"})
        bob = txn.create_node(labels=["Person"], properties={"name": "Bob", "field": "Systems"})
        txn.create_relationship(alice.id, bob.id, "COLLABORATES_WITH")

        data = [
            ("Attention Is All You Need", "The transformer architecture uses self-attention...", alice),
            ("Scaling Laws for LLMs", "We find that model performance scales predictably...", alice),
            ("Log-Structured Merge Trees", "LSM trees optimize write-heavy workloads...", bob),
        ]

        for title, text, author in data:
            doc = txn.create_node(labels=["Document"], properties={"title": title})
            chunk = txn.create_node(labels=["Chunk"], properties={"text": text})
            txn.create_relationship(chunk.id, doc.id, "PART_OF")
            txn.create_relationship(doc.id, author.id, "AUTHORED_BY")
            # Indexing for Vector Search
            txn.set_property(chunk.id, "embedding", hash_embed(text, dimensions=128))
        
        txn.commit()

    # --- Hybrid Query: Vector + Graph ---
    # Find chunks similar to query, traverse to doc, then to author
    query_vec = hash_embed("transformer attention mechanism", dimensions=128)
    results = db.query("""
        MATCH (chunk:Chunk)-[:PART_OF]-(doc:Document)-[:AUTHORED_BY]-(author:Person)
        WHERE chunk.embedding = $query
        RETURN doc.title, chunk.text, author.name
        ORDER BY chunk.embedding = $query
        LIMIT 5
    """, parameters={"query": query_vec})

    for row in results:
        print(f"{row['doc.title']} by {row['author.name']}")

    # --- Full-Text Search ---
    for r in db.fts_search("self-attention transformer"):
        print(f"Node {r.id} matched text search")

    # --- Graph Analytics ---
    stats = db.query("""
        MATCH (doc:Document)-[:AUTHORED_BY]-(p:Person)
        RETURN p.name, count(doc) AS papers
        ORDER BY papers DESC
    """)
    for row in stats:
        print(f"{row['p.name']}: {row['papers']} papers")

TypeScript Implementation

Basic initialization and node creation in Node.js:

import { Database } from "@hajewski/latticedb";
import { hashEmbed } from "@hajewski/latticedb/embedding";

const db = new Database("knowledge.db", {
    create: true,
    enableVectors: true,
    vectorDimensions: 128,
});

await db.createNode({
    labels: ["Person"],
    properties: { name: "Alice", field: "ML" },
});

const doc = await db.transaction(async (txn) => {
    return await txn.createNode({
        labels: ["Document"],
        properties: { title: "Attention Is All You Need" },
    });
});

📖 Getting Started Path

• Quickest Start: Check the CLI Quickstart for copy-paste examples.
• Learning Path: Visit Getting Started for language-specific guides.
• Deep Dive: Explore the Examples Overview for full-scale retrieval demos.