caracaldb 1.0.2

Embedded, ontology-leaning, Arrow-native analytical GraphDB for KG and GNN MLOps workflows.

CaracalDB

An Embedded, Ontology-Leaning, Arrow-Native Analytical GraphDB for KG and GNN Workflows.

Why CaracalDB | Quickstart | API Overview | Architecture

CaracalDB is an embedded graph database for knowledge graphs, ontology-aware query planning, GNN sampling, and ML feature workflows. The current implementation is a Python reference engine that validates the .crcl storage format, Tuft query language, planner surface, and user-facing API. A Rust core is planned, but it is not part of the current package.

Quickstart

Install

pip install caracaldb

or

uv add caracaldb

For development from a repository checkout:

uv sync --extra dev
uv run pytest

30-Second Quickstart

import caracaldb as cdb

with cdb.connect("examples/data/example_simple.crcl") as db:
    db.define_class("Person")
    db.insert_nodes(
        "Person",
        [
            {"name": "Alice", "age": 28, "city": "New York"},
            {"name": "Bob", "age": 34, "city": "London"},
            {"name": "Charlie", "age": 25, "city": "Paris"},
            {"name": "Diana", "age": 42, "city": "Tokyo"},
        ],
    )

with cdb.connect("examples/data/example_simple.crcl", mode="ro") as db:
    rows = db.sql("MATCH (p:Person) RETURN p.name, p.city LIMIT 2").rows()
    print(rows)

Expected output:

[{'name': 'Alice', 'city': 'New York'}, {'name': 'Bob', 'city': 'London'}]

The current Python reference query path supports a single MATCH (alias:Class) node pattern with WHERE, RETURN, and LIMIT. Broader graph patterns, richer binding, and multi-hop query execution are tracked in the milestone docs.

Start Here

• Language spec: docs/01_language_spec.md
• Engine spec: docs/02_engine_spec.md
• Modeling case study: docs/03_user_modeling_case_study.md
• Implementation plan: docs/04_caracaldb_implementation.md
• Work breakdown: docs/05_wbs.md
• Error index: docs/errors/TF-INDEX.md
• Examples: examples/
• Benchmark CI: .github/workflows/bench.yml

Why CaracalDB

CaracalDB is built around explicit storage, ontology, and execution boundaries:

flowchart LR
    A["Tuft query"] --> B["Parser and diagnostics"]
    B --> C["Binder and ontology catalog"]
    C --> D["Logical plan"]
    D --> E["Physical operators"]
    E --> F["Arrow RecordBatch"]
    G[".crcl bundle or packed file"] --> H["Catalog, WAL, snapshots, stores"]
    H --> E
    H --> I["CSR / CSC graph indexes"]
    I --> J["Traversal, sampling, and ML adapters"]

• Embedded-first operation: no required server process.
• Tuft combines Cypher-like graph patterns with SPARQL-like ontology semantics.
• Arrow is the execution boundary for scan results and downstream analytics.
• CSR and CSC graph layouts support traversal, neighbor sampling, and GNN workflows.
• GraphRAG substrate APIs expose entity linking, graph-aware vector entry, and evidence-path retrieval as reusable database primitives without owning extraction, embedding calls, prompting, answer generation, or reranking policy.
• Snapshot, WAL, and packed .crcl storage paths are tested as first-class engine pieces.
• The Python API is intentionally small; Rust core work is planned after the reference behavior is stable.

Benchmarks

Benchmark automation is scaffolded in the repository:

• CI automation: .github/workflows/bench.yml
• Benchmark harness tests: tests/test_bench_pkg/

The CLI exposes a benchmark command for registered scenarios:

caracal bench NAME

CLI

The CLI is available as caracal:

# Initialise an empty .crcl bundle
caracal init demo

# Run a Tuft query from a file
caracal run demo.crcl --file query.tuft

# Print an explain tree
caracal explain demo.crcl Gene

# Pack and unpack .crcl storage
caracal pack demo.crcl -o demo-packed.crcl
caracal unpack demo-packed.crcl -o restored.crcl

API Overview

Top-level functions and types

API	Description
cdb.connect(path, mode="rw", format="auto")	Open or create a .crcl database
Database.cursor()	Create a query connection
Database.catalog	Access the ontology catalog
Database.bundle	Access the underlying storage bundle
Database.open_node_store(class_iri)	Open a node store for a class
Connection.sql(text, params=None)	Execute supported Tuft query text
Result.arrow()	Return a pyarrow.Table
Result.record_batches()	Iterate pyarrow.RecordBatch results
Database.link_entities(...)	Link query text to graph entity nodes
Database.vector_search(..., graph_boosts=...)	Use semantic entry with graph-aware score boosts
Database.evidence_search(...)	Expand typed paths from seeds to evidence chunks
Database.graphrag_search(...)	Return a GraphRAGResult for fused entity, semantic, evidence, citation, path, and profile artifacts

CLI commands

Command	Description
caracal init PATH	Initialise an empty .crcl bundle
caracal run BUNDLE --file QUERY	Execute a Tuft query and emit JSON
caracal explain BUNDLE QUERY	Print a logical explain tree
caracal bench NAME	Run a registered microbenchmark
caracal pack BUNDLE -o FILE	Package a directory bundle into a packed .crcl file
caracal unpack FILE -o DIR	Restore a packed .crcl file into a bundle

Architecture

CaracalDB is organized as a Python package with focused modules for language, planning, execution, storage, graph layout, ontology, and ML interop:

caracaldb/
  api.py                 Public connect / Database / Connection / Result API
  cli/                   Typer command-line interface
  lang/tuft/             Tuft parser, AST, binder, transformer, typing
  plan/                  Logical plan nodes, rules, cost model, pattern compiler
  exec/                  Physical operators and execution context
  storage/               .crcl bundle, WAL, snapshots, pack/unpack, stores
  graph/                 CSR / CSC builders, readers, HNSW support
  onto/                  Catalog, hierarchy, closure, reasoner
  ingest/                Parquet ingestion helpers
  ml/                    Subgraph, neighbor loader, framework adapters
  observability/         Explain, profile, and tracing helpers
  udf/                   Python and Tuft UDF registry

Execution Pipeline

Tuft text
    |
    v
Parser -> Binder -> Logical plan -> Physical pipeline
                                      |
                                      v
NodeScan / Filter / Project / Expand / Join / Aggregate operators
                                      |
                                      v
Arrow RecordBatch -> pyarrow.Table

Storage Pipeline

.crcl path
    |
    +-- packed single file
    |       |
    |       v
    |   temporary working bundle -> repacked on close
    |
    +-- directory bundle
            |
            v
    manifest / catalog / WAL / snapshots / node stores / edge stores / indexes

Repository Layout

caracaldb/   Python package source
tests/       Unit, golden, property, and end-to-end tests
schema/      FlatBuffers and storage/catalog schemas
docs/        Design documents and user documentation
examples/    Runnable examples and case-study notebooks

Project Status

CaracalDB is pre-release and not yet suitable for production use. M0 through M5 are accepted in docs/milestones/, and the engine is currently in the v0.2.x docs and benchmark sweep. Multi-hop pattern matching, rel-type unions, Tuft bounded variable-length paths, vector search calls, and the degree() graph built-in are wired through Connection.sql. Python-level graph ecosystem primitives now include vector index lifecycle, vector search, neighbors, k_hop, bounded paths, shortest_path, Arrow batch upsert, materialized property/text lookup indexes, multi-seed path expansion, idempotent semantic-neighbor upserts, capabilities, and profile/explain telemetry. Multi-label nodes remain a carry-over.

The closest peers — embedded analytical graph engines — are kuzu, DuckPGQ, and Memgraph's embedded library mode. Comparisons against server-tier graph databases (Neo4j Enterprise, Neptune, TigerGraph) are not the right reference frame for an embedded .crcl file.

Non-goals

CaracalDB is deliberately scoped against a small set of features that belong in a different product:

• No server process, no network protocol. No Bolt, no gRPC, no HTTP endpoint. The analogue is DuckDB or SQLite, not Neo4j Enterprise.
• No multi-writer concurrency. A .crcl bundle is opened by one writer; readers can hold older snapshots. Coordinating multiple writers belongs to a layer above the engine.
• No authentication, authorization, or row-level ACLs. Filesystem permissions are the only access boundary. Embedded governance belongs to the host application or a server tier.
• No SPARQL endpoint, no full OWL-DL. CaracalDB supports OWL-RL-style class/property hierarchies and IRI identity; RDF/Turtle is an import concern, not an engine surface (see docs/adr/0005-rdf-as-import-only.md).
• No bundled LLM / GraphRAG framework. CaracalDB is a substrate for GNN and KG workflows; LLM glue is the host application's job. The Arrow record_batches() / arrow() outputs are the integration contract.

The one governance-adjacent feature that does fit the embedded model is deterministic, named snapshots with content-addressable manifests, plus a caracal diff command for auditing graph versions. That lets an outer governance layer pin and diff a database without the engine taking on multi-tenant concerns.

Contributing

Start with docs/04_caracaldb_implementation.md and docs/05_wbs.md. The core project constraints are:

1. Keep the engine embedded-first.
2. Preserve Arrow-native execution boundaries.
3. Treat Tuft diagnostics and golden parser tests as public contract.
4. Keep .crcl storage reproducible through WAL, snapshots, and pack/unpack tests.
5. Measure performance changes before claiming speedups.

License

Apache License 2.0. See LICENSE.