chimeradb 0.2.0

Knowledge graph + vector search + SQL analytics powered by DuckDB

ChimeraDB

Semantic search + graph queries + SQL analytics. All in one DuckDB file.

The only database that combines vector embeddings, property graphs (SQL/PGQ), and full SQL analytics for LLM apps. No separate vector DB, no separate graph DB, no infrastructure.

Examples • Docs

---

Quick Start

pip install chimeradb duckdb

from chimeradb import KnowledgeGraph

kg = KnowledgeGraph("my.db")  # Auto-embeddings enabled

# Add entities (embeddings generated from 'bio' field)
kg.add_entity("alice", {"name": "Alice", "bio": "ML engineer building LLM agents"}, ["Person"])
kg.add_entity("bob", {"name": "Bob", "bio": "AI researcher focused on NLP"}, ["Person"])
kg.add_entity("acme", {"name": "Acme AI"}, ["Company"])

# Add relationships
kg.add_relationship("alice", "acme", "WORKS_AT")
kg.add_relationship("bob", "acme", "WORKS_AT")

# 1. Semantic search - Find by meaning, not keywords
results = kg.search("who works on language models?", top_k=2)
# Finds both Alice and Bob even though query doesn't match exactly

# 2. Graph traversal - Python API
employees = kg.traverse("acme", direction="incoming")

# 3. SQL/PGQ - Graph pattern matching (SQL:2023 standard)
results = kg.query("""
    SELECT *
    FROM GRAPH_TABLE (knowledge_graph
        MATCH (p:nodes)-[e:edges]->(c:nodes)
        WHERE c.id = 'acme'
        COLUMNS (
            json_extract_string(p.properties, 'name') as person,
            e.edge_type
        )
    )
""")

# 4. SQL analytics - Aggregate, filter, join
stats = kg.query("""
    SELECT
        json_extract_string(n.properties, 'name') as company,
        COUNT(*) as employee_count
    FROM nodes n
    JOIN edges e ON e.to_id = n.id
    WHERE n.labels LIKE '%Company%'
    GROUP BY company
""")

# Combine all three in one query!
results = kg.query("""
    WITH relevant_people AS (
        -- Find semantically similar people (would use search() in practice)
        SELECT id, properties
        FROM nodes
        WHERE labels LIKE '%Person%'
    )
    SELECT
        json_extract_string(p.properties, 'name') as person,
        json_extract_string(c.properties, 'name') as company,
        e.edge_type
    FROM relevant_people p
    JOIN edges e ON e.from_id = p.id
    JOIN nodes c ON e.to_id = c.id
    WHERE c.labels LIKE '%Company%'
""")

Why ChimeraDB?

Three powerful tools, one simple database:

1. Vector embeddings - Search by meaning, not keywords. Find "machine learning expert" when the text says "AI researcher"
2. Property graphs - Express relationships naturally with SQL/PGQ: MATCH (person)-[edge]->(company)
3. Full SQL analytics - Aggregate, filter, join with the full power of DuckDB

The combination is the killer feature:

• RAG systems: Semantic search + relationship context
• AI agents: Graph traversal + analytical reasoning
• Recommendations: Similarity search + collaborative filtering

Zero infrastructure:

• One DuckDB file
• Runs anywhere (laptop, server, edge device)
• 10-100x faster than other embedded options
• Production-ready extensions (duckpgq, vss)

Installation

Python Package

pip install chimeradb duckdb

Platform Support:

• ✅ macOS (Intel x86_64 & Apple Silicon ARM64)
• ✅ Linux (x86_64)
• ✅ Linux ARM64 (with DuckDB v1.1.3)
• ⚠️ Windows: DuckDB extensions may need manual installation

Or from source:

git clone https://github.com/codimusmaximus/chimeradb.git
cd chimeradb
pip install -e .

DuckDB Extensions

ChimeraDB automatically installs these DuckDB extensions:

• duckpgq: Property graph queries with SQL/PGQ
• vss: Vector similarity search with HNSW indexing

Python API

from chimeradb import KnowledgeGraph

# Create database
kg = KnowledgeGraph("my_graph.db")  # Or ":memory:"

# Optional: disable embeddings or use different model
# kg = KnowledgeGraph("my.db", embedding_model=None)
# kg = KnowledgeGraph("my.db", embedding_model="text-embedding-3-small")

# Add nodes
kg.add_entity(
    entity_id="person1",
    properties={"name": "Alice", "bio": "AI researcher"},
    labels=["Person"],
    embed_field="bio"  # Auto-generate embedding from this field
)

# Add relationships
kg.add_relationship(
    from_id="person1",
    to_id="company1",
    relation_type="WORKS_AT",
    properties={"since": 2020}
)

# Semantic search
results = kg.search("machine learning expert", top_k=10)

# Graph traversal (recursive SQL)
network = kg.traverse("person1", direction="outgoing", max_depth=3)

# SQL/PGQ pattern matching
results = kg.query("""
    SELECT *
    FROM GRAPH_TABLE (knowledge_graph
        MATCH (p:nodes)-[w:edges]->(c:nodes)
        WHERE p.labels LIKE '%Person%'
          AND c.labels LIKE '%Company%'
        COLUMNS (p.id, w.edge_type, c.id)
    )
""")

# Raw SQL queries
data = kg.query("""
    SELECT json_extract(properties, '$.name') as name
    FROM nodes
    WHERE json_extract(properties, '$.role') = 'Engineer'
""")

kg.close()

Examples

• 01_getting_started.py: Python API basics
• 02_basic.py: Semantic search + graph traversal + SQL analytics
• 03_advanced.py: Research paper recommendations with graph analysis

Requirements

• Python 3.8+
• DuckDB 1.1.3+ (automatically installed with chimeradb)
• sentence-transformers (for embeddings, auto-installed)

Documentation

• Getting Started Guide
• SQL/PGQ Guide
• DuckDB VSS Extension

Tech Stack

Built on:

• DuckDB - Fast analytical database engine
• duckpgq - SQL/PGQ property graph queries
• vss extension - Vector similarity search

Performance

DuckDB provides 10-100x better performance than traditional embedded databases for analytical queries:

• Columnar storage for fast aggregations
• Vectorized query execution
• Zero-copy data access
• Production-ready HNSW indexing

Migration from v0.1.x (SQLite)

ChimeraDB v0.2.0+ uses DuckDB instead of SQLite for better performance and reliability. Key changes:

Removed:

• cypher() method - Use SQL/PGQ with query() instead
• Cypher query language - Use SQL/PGQ (SQL:2023 standard)
• SQLite extensions - Now use DuckDB extensions

New/Updated:

• Property graphs use SQL/PGQ syntax
• 10-100x faster for analytics
• No corruption bugs from global state
• Same Python API for add_entity(), add_relationship(), search(), traverse()

See SQL/PGQ documentation for graph query syntax.

License

MIT - see LICENSE