Crate kyu_graph 

KyuGraph — high-performance embedded property graph database.

KyuGraph is a pure-Rust embedded graph database implementing the openCypher query language. It uses columnar storage, vectorized execution, and optional Cranelift JIT compilation for analytical graph workloads.

Quick Start

use kyu_graph::{Database, TypedValue};

// In-memory database
let db = Database::in_memory();
let conn = db.connect();

// Create schema
conn.query("CREATE NODE TABLE Person (id INT64, name STRING, age INT64, PRIMARY KEY (id))")
    .unwrap();
conn.query("CREATE REL TABLE KNOWS (FROM Person TO Person)")
    .unwrap();

// Insert data
conn.query("CREATE (p:Person {id: 1, name: 'Alice', age: 30})").unwrap();
conn.query("CREATE (p:Person {id: 2, name: 'Bob', age: 25})").unwrap();

// Query
let result = conn.query("MATCH (p:Person) WHERE p.age > 20 RETURN p.name, p.age").unwrap();
for row in result.iter_rows() {
    println!("{:?}", row);
}

Persistent Database

use kyu_graph::Database;

let db = Database::open(std::path::Path::new("./my_graph")).unwrap();
let conn = db.connect();
conn.query("CREATE NODE TABLE Log (id INT64, msg STRING, PRIMARY KEY (id))").unwrap();
// Data is checkpointed to disk automatically.

Bulk Data Import

use kyu_graph::Database;

let db = Database::in_memory();
let conn = db.connect();
conn.query("CREATE NODE TABLE Person (id INT64, name STRING, PRIMARY KEY (id))").unwrap();
conn.query("COPY Person FROM 'people.csv'").unwrap();

Parameterized Queries

Pass dynamic values safely via $param placeholders instead of string interpolation. Use the re-exported json! macro and BindContext for ergonomic construction from JSON:

use kyu_graph::{Database, BindContext, json};

let db = Database::in_memory();
let conn = db.connect();
conn.query("CREATE NODE TABLE Person (id INT64, name STRING, age INT64, PRIMARY KEY (id))")
    .unwrap();
conn.query("CREATE (p:Person {id: 1, name: 'Alice', age: 30})").unwrap();

// From json! macro
let ctx = BindContext::with_params_json(json!({"min_age": 25}));

// From a JSON string (e.g. read from a config file or HTTP request body)
let ctx = BindContext::with_params_str(r#"{"min_age": 25}"#).unwrap();

// Or use HashMap<String, TypedValue> directly
use std::collections::HashMap;
use kyu_graph::TypedValue;
let mut params = HashMap::new();
params.insert("min_age".to_string(), TypedValue::Int64(25));
let result = conn.query_with_params(
    "MATCH (p:Person) WHERE p.age > $min_age RETURN p.name",
    params,
).unwrap();

For full VM-style execution with both parameters and environment bindings, use Connection::execute.

Extensions

KyuGraph supports pluggable extensions for graph algorithms, full-text search, vector similarity, and more. Extensions are registered on the database instance before creating connections.

use kyu_graph::{Database, Extension};

let mut db = Database::in_memory();
// db.register_extension(Box::new(my_extension));
let conn = db.connect();
// conn.query("CALL ext.procedure(args)").unwrap();

Modules

types

Re-exports of types used less frequently but needed for advanced usage.

Macros

json

Re-export serde_json::json! for ergonomic construction of params and env. Construct a serde_json::Value from a JSON literal.

Structs

ArrowIpcReader

Reads rows from an Arrow IPC file (.arrow / .ipc).

BindContext

Bind-time context: parameter values and environment variables.

Connection

A connection to a KyuGraph database.

CsvReader

Reads rows from a CSV file, parsing each field according to the target schema.

Database

A graph database instance.

DatabaseConfig

Configuration for a KyuGraph database instance.

DeltaBatch

A batch of graph deltas from a single source, committed atomically.

DeltaBatchBuilder

Builder for ergonomic DeltaBatch construction.

DeltaStats

Statistics returned after processing a DeltaBatch.

KafkaReader

Reads rows from a Kafka topic.

NodeGroupStorage

Real columnar storage backed by NodeGroup/ColumnChunk.

NodeKey

A stable, user-defined identifier for a node.

ParquetReader

Reads rows from a Parquet file, converting Arrow arrays to TypedValue rows.

ProcColumn

A procedure result column: name + logical type.

ProcParam

A procedure parameter: name + type description.

ProcedureSignature

Signature of an extension procedure.

QueryResult

The result of executing a query: column metadata + rows of typed values.

VectorClock

Logical vector clock for causal ordering between workers.

Enums

DeltaValue

A typed value used during parsing, binding, and planning.

GraphDelta

A single graph mutation in the delta fast path.

KyuError

Top-level error type for the entire KyuGraph engine. Each variant corresponds to a distinct subsystem, matching the Kuzu/RyuGraph exception hierarchy.

LogicalType

Logical data type representing user-facing type semantics. Multiple logical types may share the same PhysicalType (e.g., Date/Timestamp/TimestampNs all use Int64 physically).

TypedValue

A typed value used during parsing, binding, and planning.

Traits

DataReader

Trait for reading rows from an external data source.

Extension

Trait that every extension must implement.

Functions

open_reader

Open a data reader for the given file path, auto-detecting format by extension.

serve_flight

Start the Arrow Flight server.

to_record_batch

Convert a QueryResult into an Arrow RecordBatch.

Type Aliases

KyuResult

ProcRow

A row of typed results, ordered by column index (matching ProcedureSignature.columns).