kyu-api

Database and Connection API for KyuGraph with Arrow Flight support.

This crate is the internal engine API. Most users should depend on kyu-graph instead, which re-exports the public surface from this crate.

Core Types

Usage

use kyu_api::{Database, Connection};

// In-memory
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("CREATE (p:Person {id: 1, name: 'Alice'})").unwrap();

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

Persistent Database

use kyu_api::Database;

let db = Database::open(std::path::Path::new("./my_graph")).unwrap();
let conn = db.connect();
// Schema + data persisted to disk via WAL + checkpointing.

Parameterized Queries

use std::collections::HashMap;
use kyu_types::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();

Full VM Execution (params + env)

use std::collections::HashMap;
use kyu_types::TypedValue;

let params = HashMap::new();
let env = HashMap::new();
let result = conn.execute("MATCH (n) RETURN n", params, env).unwrap();

Delta Fast Path

Conflict-free idempotent upserts bypassing OCC for high-throughput ingestion:

use kyu_delta::{DeltaBatchBuilder, DeltaValue};

let batch = DeltaBatchBuilder::new("source:my-pipeline", 1000)
    .upsert_node("Person", "1", vec![], [("name", DeltaValue::String("Alice".into()))])
    .build();
let stats = conn.apply_delta(batch).unwrap();

Extensions

use kyu_api::Database;
use kyu_extension::Extension;

let mut db = Database::in_memory();
// db.register_extension(Box::new(my_ext));
let conn = db.connect();

Arrow Flight Server

Expose KyuGraph as an Arrow Flight gRPC endpoint:

use std::sync::Arc;
use kyu_api::{Database, serve_flight};

let db = Arc::new(Database::in_memory());
// serve_flight(db, "0.0.0.0", 50051).await.unwrap();

Convert query results to Arrow RecordBatch:

use kyu_api::to_record_batch;

let result = conn.query("MATCH (p:Person) RETURN p.name, p.age").unwrap();
if let Some(batch) = to_record_batch(&result) {
    println!("Arrow schema: {:?}", batch.schema());
}

Architecture

Application
    │
    ▼
┌─────────┐     ┌────────────┐
│ Database │────▶│ Connection │  ← you are here (kyu-api)
└─────────┘     └────────────┘
    │                │
    ▼                ▼
┌────────┐    ┌──────────────┐
│Catalog │    │ kyu-executor │
└────────┘    └──────────────┘
    │                │
    ▼                ▼
┌──────────────────────────┐
│  kyu-storage (columnar)  │
└──────────────────────────┘
    │
    ▼
┌──────────────────────────┐
│  kyu-transaction (WAL)   │
└──────────────────────────┘

Query Pipeline

1. Parse — kyu-parser lexes and parses Cypher into an AST
2. Bind — kyu-binder resolves names against the catalog
3. Plan — kyu-planner builds and optimizes a logical plan
4. Execute — kyu-executor runs the plan against storage
5. Commit — kyu-transaction persists via WAL + checkpoint

License

MIT