Quick Start

CrabGraph is a Gremlin engine that attaches to your existing DuckDB connection. Define vertices and edges as DuckDB views named V_* and E_*, then traverse them with the full Gremlin language. No separate server, no schema language, no migrations.

<dependency>
  <groupId>net.crabgraph</groupId>
  <artifactId>crabgraph</artifactId>
  <version>0.1.0</version>
</dependency>
<dependency>
  <groupId>org.duckdb</groupId>
  <artifactId>duckdb_jdbc</artifactId>
  <version>1.5.0.0</version>
</dependency>

try (Connection c = DriverManager.getConnection("jdbc:duckdb:/tmp/g.duckdb");
     Statement s = c.createStatement()) {
  s.execute("CREATE SCHEMA IF NOT EXISTS public");
  s.execute("""
      CREATE VIEW public.V_Person AS
        SELECT 1::BIGINT AS \"ID\", 'Alice' AS \"name\" UNION ALL
        SELECT 2::BIGINT,                'Bob'""");
  s.execute("""
      CREATE VIEW public.E_KNOWS AS
        SELECT 1::BIGINT AS \"ID\",
               2::BIGINT AS \"public.Person__I\",
               1::BIGINT AS \"public.Person__O\"""");
}

import net.crabgraph.Crabgraph;
import java.sql.*;

try (Connection c = DriverManager.getConnection("jdbc:duckdb:/tmp/g.duckdb");
     Crabgraph g = Crabgraph.attach(c)) {

  String count   = g.gremlin("g.V().hasLabel('Person').count()");
  String friends = g.gremlin(
      "g.V().has('name','Alice').out('KNOWS').values('name').toList()");
}

pip install crabgraph

import duckdb

conn = duckdb.connect("/tmp/g.duckdb")
conn.execute("CREATE SCHEMA IF NOT EXISTS public")
conn.execute("""
    CREATE VIEW public.V_Person AS
      SELECT 1::BIGINT AS "ID", 'Alice' AS "name" UNION ALL
      SELECT 2::BIGINT,                'Bob'
""")
conn.execute("""
    CREATE VIEW public.E_KNOWS AS
      SELECT 1::BIGINT AS "ID",
             2::BIGINT AS "public.Person__I",
             1::BIGINT AS "public.Person__O"
""")

import crabgraph

with crabgraph.Crabgraph.attach(conn) as g:
    print(g.gremlin("g.V().hasLabel('Person').count()"))
    print(g.gremlin(
        "g.V().has('name','Alice').out('KNOWS').values('name').toList()"))

npm install crabgraph @duckdb/node-api

import { DuckDBInstance } from "@duckdb/node-api";

const inst = await DuckDBInstance.create("/tmp/g.duckdb");
const conn = await inst.connect();
await conn.run("CREATE SCHEMA IF NOT EXISTS public");
await conn.run(`
  CREATE VIEW public.V_Person AS
    SELECT 1::BIGINT AS "ID", 'Alice' AS "name" UNION ALL
    SELECT 2::BIGINT,                'Bob'`);
await conn.run(`
  CREATE VIEW public.E_KNOWS AS
    SELECT 1::BIGINT AS "ID",
           2::BIGINT AS "public.Person__I",
           1::BIGINT AS "public.Person__O"`);

import { Crabgraph } from "crabgraph";

const g = await Crabgraph.attach(conn);
try {
  console.log(g.gremlin("g.V().hasLabel('Person').count()"));
  console.log(g.gremlin(
    "g.V().has('name','Alice').out('KNOWS').values('name').toList()"));
} finally {
  g.close();
}

go get github.com/henneberger/crabgraph/go
go get github.com/duckdb/duckdb-go/v2

package main

import (
    "database/sql"
    "fmt"

    _ "github.com/duckdb/duckdb-go/v2"
    crabgraph "github.com/henneberger/crabgraph/go"
)

func main() {
    db, err := sql.Open("duckdb", "/tmp/g.duckdb")
    if err != nil { panic(err) }
    defer db.Close()

    db.Exec("CREATE SCHEMA IF NOT EXISTS public")
    db.Exec(`CREATE VIEW public.V_Person AS
        SELECT 1::BIGINT AS "ID", 'Alice' AS "name" UNION ALL
        SELECT 2::BIGINT,                'Bob'`)
    db.Exec(`CREATE VIEW public.E_KNOWS AS
        SELECT 1::BIGINT AS "ID",
               2::BIGINT AS "public.Person__I",
               1::BIGINT AS "public.Person__O"`)

    g, err := crabgraph.Attach(db)
    if err != nil { panic(err) }
    defer g.Close()

    out, _ := g.Gremlin("g.V().hasLabel('Person').count()")
    fmt.Println(out)
}

[dependencies]
crabgraph = { version = "0.1", features = ["duckdb"] }
duckdb    = "1.10"

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conn = duckdb::Connection::open("/tmp/g.duckdb")?;
    conn.execute_batch(r#"
        CREATE SCHEMA IF NOT EXISTS public;
        CREATE VIEW public.V_Person AS
            SELECT 1::BIGINT AS "ID", 'Alice' AS "name" UNION ALL
            SELECT 2::BIGINT,                'Bob';
        CREATE VIEW public.E_KNOWS AS
            SELECT 1::BIGINT AS "ID",
                   2::BIGINT AS "public.Person__I",
                   1::BIGINT AS "public.Person__O";
    "#)?;

    let g = crabgraph::Crabgraph::attach(&conn)?;
    println!("{}", g.gremlin("g.V().hasLabel('Person').count()")?);
    println!("{}", g.gremlin(
        "g.V().has('name','Alice').out('KNOWS').values('name').toList()")?);
    Ok(())
}

Installation

CrabGraph is distributed through each language's native package manager. Install the crabgraph package for your language alongside a DuckDB driver — the engine runs embedded in your process, no separate server to deploy.

Define a Schema

Your schema lives in DuckDB itself, as views in the public schema. There is no separate schema file, no annotations, no migrations. CrabGraph discovers everything from information_schema at attach time.

Vertices: V_<Label>

A view named V_<Label> becomes a vertex label. Each row is a vertex. The view must have a BIGINT column called "ID" as the vertex's primary key; every other column becomes a property.

CREATE VIEW public.V_Person AS
  SELECT id    AS "ID",    -- BIGINT
         name  AS "name",       -- property
         age   AS "age"
  FROM   raw_people;

Edges: E_<EdgeLabel>

A view named E_<EdgeLabel> becomes an edge label. Required columns:

• "ID" — BIGINT, the edge's primary key
• "public.<OutVertexLabel>__O" — BIGINT, the source vertex's ID
• "public.<InVertexLabel>__I" — BIGINT, the target vertex's ID

Any other columns are edge properties. The __O / __I column-name suffixes tell CrabGraph which vertex labels the edge connects.

CREATE VIEW public.E_KNOWS AS
  SELECT id           AS "ID",
         src_person   AS "public.Person__O",   -- out-vertex (Person)
         dst_person   AS "public.Person__I",   -- in-vertex (Person)
         since_year   AS "since"              -- edge property
  FROM   raw_friendships;

Backed by anything DuckDB can read

The view's SELECT is just SQL. It can read parquet files, Iceberg tables (via the iceberg extension), CSVs, PostgreSQL via the postgres extension, MotherDuck — any DuckDB source.

Iceberg (direct warehouse attach)

INSTALL iceberg; LOAD iceberg;
ATTACH 's3://my-bucket/warehouse/' AS cat (TYPE ICEBERG);

CREATE VIEW public.V_Order AS
  SELECT order_id AS "ID", total AS "total"
  FROM   cat.orders;

Apache Polaris catalog

For a Polaris-managed warehouse, register a secret with your OAuth2 credentials and attach via the catalog endpoint. Polaris hands DuckDB the table metadata; reads still go directly to the underlying storage.

INSTALL iceberg; LOAD iceberg;

CREATE SECRET polaris_auth (
    TYPE             ICEBERG,
    CLIENT_ID        '<your-principal-id>',
    CLIENT_SECRET    '<your-principal-secret>',
    OAUTH2_SERVER_URI 'https://<polaris-host>/api/catalog/v1/oauth/tokens',
    OAUTH2_SCOPE     'PRINCIPAL_ROLE:ALL'
);

ATTACH '<warehouse-name>' AS polaris (
    TYPE     ICEBERG,
    ENDPOINT 'https://<polaris-host>/api/catalog',
    SECRET   polaris_auth
);

CREATE VIEW public.V_Customer AS
  SELECT id AS "ID", email AS "email"
  FROM   polaris.analytics.customers;

SET cache_https = true;

Your First Query

CrabGraph speaks the Apache TinkerPop Gremlin language via the ANTLR parser — every standard Gremlin step works as expected. Pass a query string to g.gremlin(...) and you get a JSON result.

// Count vertices of a label
g.V().hasLabel("Person").count()

// Friends of Alice
g.V().has("Person", "name", "Alice")
 .out("KNOWS")
 .values("name")
 .order()
 .toList()

// Two-hop expansion
g.V().has("Person", "name", "Alice")
 .repeat(__.out("KNOWS").simplePath())
 .times(2)
 .dedup()
 .values("name")
 .toList()

Results are returned JSON-encoded. Vertices and edges materialize as objects with type, id, label, and properties fields:

[
  {"type":"vertex","id":"v[Person][1]","label":"Person",
   "properties":{"name":"Alice","age":34}}
]

Architecture

CrabGraph is embedded. It runs in your application's process as a library call — no daemon, no port to bind, no extra process to supervise. attach opens its own connection to the DuckDB file you pointed at and exposes Gremlin synchronously through whatever language you called it from.

Engine-managed schema

The first time CrabGraph attaches to a database, it creates a small set of internal tables in a reserved schema alongside your views. These hold topology metadata — which V_* / E_* views exist, their column types, and edge endpoints. The tables are created automatically; there's nothing for you to run or migrate.

Subsequent attaches reuse what's already there. If you add, drop, or re-shape a V_* / E_* view, rebuild the internal schema by dropping it and reattaching — CrabGraph rediscovers your views from scratch.

How each binding embeds

Non-Java bindings load a shared library (libcrabgraph) that's bundled with the package. The Java binding is a plain jar — no native load step needed.

Storage

Storage is whatever DuckDB does. Persist by pointing at a .duckdb file. For ephemeral / testing setups, write your views into a temp file. In-memory connections are not yet supported by attach — file-backed DBs work because the engine opens its own link to the same file you did.

Schema Reference

CrabGraph interprets a small set of view-naming and column-naming conventions. Stick to them and the engine handles topology discovery automatically.

View naming

Required columns

Property type mapping

All non-ID, non-endpoint columns are exposed as Gremlin properties. CrabGraph infers the property type from DuckDB's information_schema.columns.data_type:

Gremlin Primer

Gremlin is a functional, data-flow traversal language. A traversal starts at a set of elements and threads through a pipeline of steps. Each step transforms the current traversers.

Starting a traversal

g.V()                          // all vertices
g.E()                          // all edges
g.V().hasLabel("Person")      // vertices of a specific label (V_Person)
g.V().has("Person", "name", "Alice")  // filter by property

Step reference

Predicate reference (P)

Traversal Patterns

Common graph query patterns expressed in Gremlin. Examples assume V_Person and E_KNOWS views.

Neighbourhood queries

// Direct neighbours
g.V().has("Person", "name", "Alice").out("KNOWS").values("name")

// N-hop expansion (BFS up to 3 hops)
g.V().has("Person", "name", "Alice")
  .repeat(__.out("KNOWS").simplePath())
  .times(3)
  .dedup()
  .values("name")

Shortest path

g.V().has("Person", "name", "Alice")
  .repeat(__.bothE().otherV().simplePath())
  .until(__.has("Person", "name", "Bob"))
  .path()
  .limit(1)
  .next()

Aggregation and grouping

// Friend count per person
g.V().hasLabel("Person")
  .project("name", "friends")
  .by("name")
  .by(__.out("KNOWS").count())
  .order().by("friends", Order.desc)
  .limit(10)
  .toList()

// Group people by age, alphabetised within each bucket
g.V().hasLabel("Person")
  .group()
  .by("age")
  .by(__.values("name").order().fold())

Filtering with where

// People who know someone older than them
g.V().hasLabel("Person").as("a")
  .out("KNOWS").as("b")
  .where("a", P.lt("b")).by("age")
  .select("a").values("name")
  .toList()

Java / Kotlin

The Java binding is a plain JVM jar that pulls in its transitive dependencies alongside duckdb_jdbc. JDK 17+. The engine runs embedded in your application's JVM, sharing memory with whatever else is on your classpath — no native library, no external process.

Programmatic vs. string Gremlin

Two equivalent ways to express a query: a Gremlin string via g.gremlin(...), or the typed GraphTraversalSource from g.traversal().

try (Connection c = DriverManager.getConnection("jdbc:duckdb:/var/g.duckdb");
     Crabgraph g = Crabgraph.attach(c)) {

  // String API — returns JSON
  String json = g.gremlin("g.V().hasLabel('Person').count()");

  // Programmatic API — typed TinkerPop traversal
  GraphTraversalSource t = g.traversal();
  List<Object> friends = t.V()
      .has("Person", "name", "Alice")
      .out("KNOWS")
      .values("name")
      .order().toList();
}

Spring Boot

Build a single Crabgraph bean tied to your DuckDB DataSource. Reuse it across requests — traversals are thread-safe.

@Configuration
public class GraphConfig {

  @Bean(destroyMethod = "close")
  public Crabgraph crabgraph(DataSource duckdb) throws SQLException {
    return Crabgraph.attach(duckdb.getConnection());
  }
}

@Service
public class PersonService {

  private final Crabgraph g;

  public PersonService(Crabgraph g) { this.g = g; }

  public String friendsOf(String name) {
    return g.gremlin(
        "g.V().has('Person','name','" + name + "').out('KNOWS').values('name').toList()");
  }
}

Kotlin

DriverManager.getConnection("jdbc:duckdb:/var/g.duckdb").use { conn ->
  Crabgraph.attach(conn).use { g ->
    val friends = g.traversal().V()
      .has("Person", "name", "Alice")
      .out("KNOWS")
      .values<String>("name")
      .toList()
  }
}

Python

The Python package wraps the embedded libcrabgraph via ctypes. Crabgraph.attach(conn) takes any open duckdb.DuckDBPyConnection; Crabgraph.open(path) is a path-based shortcut. Python 3.9+.

Synchronous core API

import duckdb
import crabgraph

conn = duckdb.connect("/var/g.duckdb")

with crabgraph.Crabgraph.attach(conn) as g:
    count = g.gremlin("g.V().hasLabel('Person').count()")
    friends = g.gremlin(
        "g.V().has('Person','name','Alice').out('KNOWS').values('name').toList()")

Using with Flask / FastAPI

Build the Crabgraph instance once at startup and reuse it for the lifetime of the process. The engine is thread-safe; concurrent requests can call gremlin in parallel.

from flask import Flask, jsonify
import duckdb, crabgraph

conn = duckdb.connect("/var/g.duckdb")
g    = crabgraph.Crabgraph.attach(conn)

app  = Flask(__name__)

@app.route("/people")
def people():
    return jsonify(g.gremlin("g.V().hasLabel('Person').values('name').toList()"))

Locating the native lib in development

For non-pip installs (e.g. testing against a workspace-local libcrabgraph), set CRABGRAPH_NATIVE_DIR to the directory containing libcrabgraph.{so,dylib,dll}.

export CRABGRAPH_NATIVE_DIR=/path/to/native/build
python my_app.py

Node.js

Source is TypeScript. The package ships with a small N-API addon (built at install via node-gyp) that bridges to the embedded libcrabgraph. Crabgraph.attach(conn) takes a @duckdb/node-api DuckDBConnection.

TypeScript types

import { DuckDBInstance } from "@duckdb/node-api";
import { Crabgraph } from "crabgraph";

let g: Crabgraph;

export async function initGraph(): Promise<void> {
  const inst = await DuckDBInstance.create(process.env.GRAPH_DB!);
  const conn = await inst.connect();
  g = await Crabgraph.attach(conn);
}

export function getFriends(name: string): string {
  return g.gremlin(
    `g.V().has('Person','name','${name}').out('KNOWS').values('name').toList()`);
}

Path-based attach

If you don't already have a DuckDB connection in scope, attach by path directly. The engine opens its own JDBC link to the file.

const g = Crabgraph.open("/var/g.duckdb");

Go

The Go binding is a cgo wrapper around libcrabgraph. Pair it with github.com/duckdb/duckdb-go/v2 (the official DuckDB driver) and you get a graph engine attached to your *sql.DB. Requires Go 1.24+ and CGO_ENABLED=1.

HTTP server example

package main

import (
    "database/sql"
    "net/http"

    _ "github.com/duckdb/duckdb-go/v2"
    crabgraph "github.com/henneberger/crabgraph/go"
)

func main() {
    db, err := sql.Open("duckdb", "/var/g.duckdb")
    if err != nil { panic(err) }
    defer db.Close()

    g, err := crabgraph.Attach(db)
    if err != nil { panic(err) }
    defer g.Close()

    http.HandleFunc("/people", func(w http.ResponseWriter, r *http.Request) {
        out, err := g.Gremlin("g.V().hasLabel('Person').valueMap().toList()")
        if err != nil { http.Error(w, err.Error(), 500); return }
        w.Header().Set("Content-Type", "application/json")
        w.Write([]byte(out))
    })
    http.ListenAndServe(":3000", nil)
}

Locating libcrabgraph

By default the binding looks for libcrabgraph.{so,dylib} at ../native/build/ relative to the Go module. To override, set CGo flags at build time:

CGO_CFLAGS="-I/path/to/include" \
CGO_LDFLAGS="-L/path/to/lib -lcrabgraph" \
go build

Rust

The Rust crate is a thin synchronous wrapper around libcrabgraph. The duckdb feature enables typed integration with the duckdb crate's Connection; without it, only the path-based open entrypoint is available.

Cargo features

[dependencies]
crabgraph = { version = "0.1", features = ["duckdb"] }
duckdb    = "1.10"

Attach to an existing duckdb-rs connection

use crabgraph::Crabgraph;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let conn = duckdb::Connection::open("/var/g.duckdb")?;
    conn.execute_batch(r#"
        CREATE SCHEMA IF NOT EXISTS public;
        CREATE VIEW public.V_Person AS
            SELECT 1::BIGINT AS "ID", 'Alice' AS "name" UNION ALL
            SELECT 2::BIGINT,                'Bob';
        CREATE VIEW public.E_KNOWS AS
            SELECT 1::BIGINT AS "ID",
                   2::BIGINT AS "public.Person__I",
                   1::BIGINT AS "public.Person__O";
    "#)?;

    let g = Crabgraph::attach(&conn)?;
    let friends = g.gremlin(
        "g.V().has('Person','name','Alice').out('KNOWS').values('name').toList()")?;
    println!("{friends}");
    Ok(())
}

Without the duckdb feature

If you don't want a hard dep on duckdb-rs, attach by path:

let g = crabgraph::Crabgraph::open("/var/g.duckdb")?;

CrabGraph Cloud

CrabGraph Cloud is a hosted notebook experience for exploring graphs without setting up a local DuckDB or any of the language bindings. Drop in a DuckDB file or point at an Iceberg catalog, define your V_* / E_* views in the editor, and run Gremlin queries in the browser.

Configuration

The current API surface is intentionally minimal — all you configure is which DuckDB file to attach to. Tuning happens in DuckDB itself (memory limits, threads, extension config) on the connection you pass in.

Build-time / install-time

Tuning DuckDB

CrabGraph executes Gremlin by translating it to SQL and running it through your DuckDB connection. Standard DuckDB tuning applies — set memory limits, thread counts, and any extension config before attaching:

SET memory_limit = '8GB';
SET threads      = 8;

INSTALL iceberg; LOAD iceberg;
ATTACH 's3://...' AS cat (TYPE ICEBERG);
-- now create your V_/E_ views

API Reference

Methods available on every binding's Crabgraph instance. Names and types are language-idiomatic; semantics are identical.

Result format

gremlin(query) returns Jackson-serialized JSON. Primitive results are encoded as scalars ("3", "\"Alice\""). Collection results are JSON arrays. Vertices and edges are JSON objects:

{
  "type": "vertex",
  "id":   "v[Person][1]",
  "label": "Person",
  "properties": { "name": "Alice", "age": 34 }
}

Gremlin steps

Anything in the TinkerPop 3.7 reference grammar parses. See the TinkerPop reference for the complete step library.

Changelog