Preface

In the rapidly evolving landscape of data systems, we often find ourselves gluing together disparate technologies to build a complete platform. We use Redis for caching, Neo4j for graphs, Qdrant or Pinecone for vectors, and Spark for analytics. This fragmentation leads to “Frankenstein” architectures—complex, fragile, and hard to maintain.

Samyama (Sanskrit for “Integration” or “Binding together”) was born from a desire to collapse this complexity.

Since its inception, Samyama has evolved from a high-performance research prototype into a production-ready ecosystem. To serve both the open-source community and the demanding needs of global industry, Samyama is now offered in two editions:

• Community Edition (OSS): The feature-complete, high-performance core for developers and startups.
• Enterprise Edition: Production-hardened with observability, disaster recovery, and advanced optimization for mission-critical workloads.

This book is the story of building Samyama-Graph, a modern, high-performance graph database written in Rust. It is not just a user manual; it is an architectural deep dive. We will peel back the layers to show you how it works—from the byte-level serialization in RocksDB to the lock-free concurrency of our MVCC engine, and up to the distributed consensus algorithms that keep it alive.

Why Rust?

When building a database in the 2020s, the choice of language is pivotal. We chose Rust not just for its hype, but for its promise: Fearless Concurrency.

A graph database is, by definition, a pointer-chasing engine. It demands random memory access patterns that are notoriously hard to optimize and easy to mess up (hello, segmentation faults!). Rust’s ownership model allowed us to implement complex memory management strategies—like Arena Allocation and localized reference counting—without the overhead of a Garbage Collector or the safety risks of C++.

Who is this book for?

• System Architects who want to understand the internals of a modern database.
• Rust Developers curious about real-world patterns for FFI, concurrency, and distributed systems.
• Data Engineers looking for a unified solution for their graph and AI workloads.

Let’s begin the journey.

About the Project & Author

Samyama.ai: The Vision

Samyama Graph is sponsored and developed by Samyama.ai, a company dedicated to building the future of autonomous, hardware-accelerated knowledge systems. Our mission is to unify the fragmented data landscape of graphs, vectors, and optimization into a single “Mechanical Sympathy” engine.

For enterprise inquiries, partnerships, or support, visit our official website: https://samyama.ai

About the Author: Sandeep Kunkunuru

The architecture and implementation of Samyama Graph, as well as this technical guide, are led by Sandeep Kunkunuru.

Sandeep is a specialist in high-performance Rust systems, distributed consensus, and the application of metaheuristic optimization to large-scale graph data. He is the primary maintainer of the Samyama open-source core and the lead architect behind the Enterprise Hardware-Accelerated edition.

Connect with the Project & Author:

• LinkedIn: https://www.linkedin.com/in/sandeepkunkunuru/
• GitHub: https://github.com/samyama-ai/samyama-graph
• Twitter/X: https://x.com/Samyama_AI

Getting Started with Samyama Graph

A step-by-step guide to install, connect, and explore Samyama Graph using the web visualizer at graph.samyama.cloud.

Demo Video

The demo covers: local Samyama Graph setup, connecting graph.samyama.cloud to a local instance, connecting to the hosted endpoint at api.samyama.dev, running Cypher queries, exploring graph visualizations, and using the Schema Explorer and Dashboard.

Option A — Local Setup (Run on Your Machine)

Step 1 — Install Rust

Open your terminal and run:

Mac / Linux

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Windows

1. Go to https://rustup.rs
2. Download and run rustup-init.exe
3. Follow the installer

After installation, restart your terminal. Verify it worked:

rustc --version
cargo --version

Step 2 — Clone the Repository

git clone https://github.com/samyama-ai/samyama-graph
cd samyama-graph

Step 3 — Build the Engine

cargo build --release

When complete you will see:

Finished `release` profile [optimized] target(s) in Xs

Step 4 — Start the Engine

Mac / Linux

./target/release/samyama

Windows

.\target\release\samyama.exe

You will see:

HTTP server starting on port 8080
Server ready. Press Ctrl+C to stop.

The engine is now running on:

• Port 8080 — HTTP API (for the visualizer)
• Port 6379 — Redis protocol (for redis-cli)

Step 5 — Open the Visualizer

1. Open the Chrome browser

2. Go to graph.samyama.cloud

3. Sign up with your email and password (free)

4. In the connection box, type:

   http://localhost:8080
   

5. Click Connect

You should see:

• Status: healthy ✅
• Version: 1.0.0
• Nodes and Edges count

Note: If you see a Failed to fetch error, go to the Chrome address bar → click the lock icon → Site Settings → Insecure Content → set to Allow → refresh the page.

Option B — No Local Setup (Explore Instantly)

If you do not want to install anything:

1. Go to graph.samyama.cloud

2. Sign up with your email and password (free)

3. In the connection box, type:

   https://api.samyama.dev
   

4. Click Connect

You are immediately connected to a live Samyama instance with real data. No installation required.

Running Your First Query

1. Click Query Console in the left sidebar.

2. Type this query in the editor:

   MATCH (n) RETURN labels(n), count(n)
   

3. Click Run (or press Ctrl+Enter).

You will see results in the Table tab showing all node types and their counts.

Switch to Graph View

1. Click the Graph tab in the results area.
2. You will see an interactive force-directed graph:
   • Hover over any node to see its properties.
   • Drag nodes to rearrange.
   • Scroll to zoom in or out.

More Queries to Try

-- See all relationships
MATCH ()-[r]->() RETURN type(r), count(r)

-- Browse nodes with their properties
MATCH (n) RETURN n LIMIT 25

-- Find connected nodes
MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 20

Schema Explorer

The Schema Explorer shows you the complete structure of your graph.

Click Schema Explorer in the left sidebar. You will see:

• Total Nodes — total count across all labels
• Total Edges — total count across all relationship types
• Node Types — each label with its count
• Edge Types — each relationship type with its count

This is useful for understanding what data is in your graph before writing queries.

Dashboard

The Dashboard auto-generates charts from your graph schema — no configuration needed.

Click Dashboard in the left sidebar. You will see panels including:

• Total Nodes — big number card
• Total Edges — big number card
• Node Label Distribution — pie chart
• Edge Type Distribution — pie chart
• Top Labels by Count — bar chart
• Graph Health — connected components, isolated nodes, average degree

Click Open in Console on any panel to see and edit the underlying Cypher query. Every chart is backed by a real Cypher query — you can modify and re-run them in the Query Console.

My Queries (Query History)

All queries you run are automatically saved.

Click My Queries in the left sidebar. You will see three tabs:

• Recent — all queries grouped by date
• Bookmarked — queries you starred
• Frequent — queries you run most often

You can:

• Click Run on any saved query to execute it again
• Click the star icon to bookmark a query

Plan Visualizer

See how the query engine executes your query.

1. Click Plan Visualizer in the left sidebar.
2. Type a Cypher query.
3. Click Explain to see the execution plan as a visual tree.
4. Click Profile to see actual execution times per operator.

Common Issues

Failed to fetch on graph.samyama.cloud

Chrome → Lock Icon → Site Settings → Insecure Content → Allow

Port 8080 already in use

lsof -ti :8080 | xargs kill -9

Then restart Samyama.

Build takes too long

The first build normally takes 5–15 minutes on a typical laptop. Subsequent builds are much faster.

No data after connecting

Your graph is empty. Create a sample node:

CREATE (n:Person {name: 'Alice'}) RETURN n

Next Steps

• Read the full documentation: graph.samyama.cloud/book
• Star the repository: github.com/samyama-ai/samyama-graph
• Join the community: Samyama-Graph-OSS-Support WhatsApp Group
• Need help? Message us in the WhatsApp group

That’s it — you’re up and running with Samyama Graph. Happy querying!

Knowledge Graph Catalog

Samyama ships with 8 pre-built knowledge graphs spanning biomedicine, public health, sports, and industrial operations — the 8 packaged snapshots cataloged below total ~8.7M nodes / ~30M edges of curated, open-license content. Each KG is available as a portable .sgsnap snapshot that loads in seconds, stored on S3 (s3://samyama-data/snapshots/) and GitHub Releases, and cataloged in the Supabase kg_registry table.

For the federated mega-benchmark workload — the 8 packaged KGs plus PubMed, OpenFDA FAERS, and OHDSI OMOP — the combined graph reaches ~138M nodes / 1.3B edges across 11 sources. See the Mega Benchmark for the full federated query suite.

Catalog Overview

graph TB
    subgraph "Biomedical Trifecta"
        PKG["🧬 Pathways KG<br/>119K nodes · 835K edges"]
        CTKG["💊 Clinical Trials KG<br/>7.8M nodes · 27M edges"]
        DIKG["💉 Drug Interactions KG<br/>245K nodes · 388K edges"]
    end

    subgraph "Public Health Trifecta"
        DSKG["🦠 Disease Surveillance KG<br/>217K nodes · 241K edges"]
        HDKG["📊 Health Determinants KG<br/>286K nodes · 286K edges"]
        HSKG["🏥 Health Systems KG<br/>20K nodes · 19K edges"]
    end

    subgraph "Sports"
        CKG["🏏 Cricket KG<br/>36K nodes · 1.4M edges"]
    end

    subgraph "Industrial"
        AOKG["🏭 AssetOps KG<br/>781 nodes · 955 edges"]
    end

    PKG -.->|"Gene · Protein"| DIKG
    DIKG -.->|"Drug · Intervention"| CTKG
    DSKG -.->|"Disease · Condition"| CTKG
    DSKG -.->|"Drug · AMR"| DIKG
    DSKG -.->|"Region"| HDKG
    DSKG -.->|"Region"| HSKG

    style CKG fill:#3b82f6,stroke:#333,color:#fff
    style PKG fill:#10b981,stroke:#333,color:#fff
    style CTKG fill:#8b5cf6,stroke:#333,color:#fff
    style DIKG fill:#ec4899,stroke:#333,color:#fff
    style AOKG fill:#f59e0b,stroke:#333,color:#fff
    style DSKG fill:#06b6d4,stroke:#333,color:#fff
    style HDKG fill:#84cc16,stroke:#333,color:#fff
    style HSKG fill:#f97316,stroke:#333,color:#fff

Cross-KG Federation

The biomedical trifecta (Pathways + Clinical Trials + Drug Interactions) enables queries spanning molecular biology, translational medicine, and pharmacogenomics. With PubMed: 74.3M nodes, 1.07B edges — 96/100 queries pass. BiomedQA benchmark: 98% accuracy with MCP tools.

The public health trifecta (Disease Surveillance + Health Determinants + Health Systems) enables queries from disease outbreaks to population vulnerability to health system capacity — 40/40 queries pass. Bridges to the biomedical trifecta via Country.iso_code, Drug.drugbank_id, and Gene.gene_name.

Together, the 6-KG federation spans molecular biology to population health in a single OpenCypher query. See Cross-KG Federation for details.

Cricket KG

21K international cricket matches from Cricsheet — ball-by-ball data spanning T20, ODI, and Test formats.

Click for full demo (1:56) — Dashboard, Cypher Queries, and Graph Simulation

Schema

graph LR
    Player -->|BATTED_IN| Match
    Player -->|BOWLED_IN| Match
    Player -->|DISMISSED| Player
    Player -->|FIELDED_DISMISSAL| Player
    Player -->|PLAYED_FOR| Team
    Player -->|PLAYER_OF_MATCH| Match
    Team -->|COMPETED_IN| Match
    Team -->|WON| Match
    Team -->|WON_TOSS| Match
    Match -->|HOSTED_AT| Venue
    Match -->|IN_SEASON| Season
    Match -->|PART_OF| Tournament

    style Player fill:#3b82f6,stroke:#333,color:#fff
    style Match fill:#8b5cf6,stroke:#333,color:#fff
    style Team fill:#ef4444,stroke:#333,color:#fff
    style Venue fill:#f59e0b,stroke:#333,color:#fff
    style Tournament fill:#10b981,stroke:#333,color:#fff
    style Season fill:#ec4899,stroke:#333,color:#fff

Example Queries

-- Top 10 run scorers across all formats
MATCH (p:Player)-[b:BATTED_IN]->(m:Match)
RETURN p.name AS player, sum(b.runs) AS total_runs
ORDER BY total_runs DESC LIMIT 10

-- Bowler-batsman rivalries
MATCH (bowler:Player)-[d:DISMISSED]->(victim:Player)
RETURN bowler.name, victim.name, count(d) AS times
ORDER BY times DESC LIMIT 10

-- Venue-team affinity (home advantage)
MATCH (t:Team)-[:WON]->(m:Match)-[:HOSTED_AT]->(v:Venue)
WITH t, v, count(m) AS wins WHERE wins >= 5
RETURN t.name, v.name, wins ORDER BY wins DESC LIMIT 15

Repository: samyama-ai/cricket-kg Snapshot: kg-snapshots-v1 (cricket.sgsnap, 21 MB)

Pathways KG

Biological pathways knowledge graph combining 5 open-license data sources — Reactome, STRING, Gene Ontology, WikiPathways, and UniProt. Human-only (organism 9606).

Click for full demo (2:06) — Dashboard, Cypher Queries, and Graph Simulation

Schema

graph LR
    Protein -->|PARTICIPATES_IN| Pathway
    Protein -->|CATALYZES| Reaction
    Protein -->|COMPONENT_OF| Complex
    Protein -->|ANNOTATED_WITH| GOTerm
    Protein -->|INTERACTS_WITH| Protein
    Pathway -->|CHILD_OF| Pathway
    GOTerm -->|IS_A| GOTerm
    GOTerm -->|PART_OF| GOTerm
    GOTerm -->|REGULATES| GOTerm

    style Protein fill:#3b82f6,stroke:#333,color:#fff
    style Pathway fill:#10b981,stroke:#333,color:#fff
    style GOTerm fill:#8b5cf6,stroke:#333,color:#fff
    style Reaction fill:#f59e0b,stroke:#333,color:#fff
    style Complex fill:#ef4444,stroke:#333,color:#fff

Repository: samyama-ai/pathways-kg Snapshot: kg-snapshots-v3 (pathways.sgsnap, 9 MB)

Clinical Trials KG

575K+ clinical studies from ClinicalTrials.gov enriched with MeSH disease hierarchy, RxNorm drug normalization, ATC drug classification, OpenFDA adverse events, and PubMed publications.

Schema

graph LR
    ClinicalTrial -->|STUDIES| Condition
    ClinicalTrial -->|TESTS| Intervention
    ClinicalTrial -->|HAS_ARM| ArmGroup
    ClinicalTrial -->|MEASURES| Outcome
    ClinicalTrial -->|SPONSORED_BY| Sponsor
    ClinicalTrial -->|CONDUCTED_AT| Site
    ClinicalTrial -->|REPORTED| AdverseEvent
    ClinicalTrial -->|PUBLISHED_IN| Publication
    ArmGroup -->|USES| Intervention
    Intervention -->|CODED_AS_DRUG| Drug
    Condition -->|CODED_AS_MESH| MeSHDescriptor
    Drug -->|TARGETS| Protein
    Drug -->|CLASSIFIED_AS| DrugClass
    Drug -->|TREATS| Condition
    Gene -->|ENCODES| Protein
    Gene -->|ASSOCIATED_WITH| Condition
    MeSHDescriptor -->|BROADER_THAN| MeSHDescriptor

    style ClinicalTrial fill:#8b5cf6,stroke:#333,color:#fff
    style Condition fill:#ef4444,stroke:#333,color:#fff
    style Intervention fill:#3b82f6,stroke:#333,color:#fff
    style Drug fill:#10b981,stroke:#333,color:#fff
    style Protein fill:#f59e0b,stroke:#333,color:#fff
    style Gene fill:#ec4899,stroke:#333,color:#fff
    style MeSHDescriptor fill:#06b6d4,stroke:#333,color:#fff
    style Publication fill:#84cc16,stroke:#333,color:#fff

Repository: samyama-ai/clinicaltrials-kg (private) Snapshot: kg-snapshots-v1 (clinical-trials.sgsnap, 711 MB)

Drug Interactions KG

Drug-gene interactions, side effects, indications, bioactivities, and adverse events from 5 open pharmacology databases. Bridges to Pathways KG (via gene name) and Clinical Trials KG (via DrugBank ID).

Schema

graph LR
    Drug -->|INTERACTS_WITH_GENE| Gene
    Drug -->|HAS_SIDE_EFFECT| SideEffect
    Drug -->|HAS_INDICATION| Indication
    Drug -->|HAS_BIOACTIVITY| Bioactivity
    Drug -->|HAS_ADVERSE_EVENT| AdverseEvent
    Drug -->|CLASSIFIED_AS| DrugClass
    Bioactivity -->|BIOACTIVITY_TARGET| Target

    style Drug fill:#ec4899,stroke:#333,color:#fff
    style Gene fill:#3b82f6,stroke:#333,color:#fff
    style SideEffect fill:#ef4444,stroke:#333,color:#fff
    style Indication fill:#10b981,stroke:#333,color:#fff

Performance

• Rust native loader: 245,000 nodes + 388,000 edges in 7.7s
• Snapshot: 8.1 MB (druginteractions.sgsnap)
• BiomedQA benchmark: 98% accuracy with MCP tools

Sources (5 of 6)

Repository: samyama-ai/druginteractions-kg Rust loader: examples/druginteractions_loader.rs in samyama-graph Snapshot: druginteractions.sgsnap (8.1 MB)

Disease Surveillance KG

WHO Global Health Observatory data — disease case/death counts, vaccine coverage, and health indicators across 234 countries.

Schema

graph LR
    Country -->|IN_REGION| Region
    Country -->|REPORTED| DiseaseReport
    DiseaseReport -->|REPORT_OF| Disease
    Country -->|HAS_COVERAGE| VaccineCoverage
    Country -->|HAS_INDICATOR| HealthIndicator

    style Country fill:#06b6d4,stroke:#333,color:#fff
    style Region fill:#84cc16,stroke:#333,color:#fff
    style Disease fill:#ef4444,stroke:#333,color:#fff
    style DiseaseReport fill:#8b5cf6,stroke:#333,color:#fff
    style VaccineCoverage fill:#f59e0b,stroke:#333,color:#fff
    style HealthIndicator fill:#ec4899,stroke:#333,color:#fff

Repository: samyama-ai/surveillance-kg Rust loader: examples/surveillance_loader.rs in samyama-graph Snapshot: surveillance.sgsnap (5.7 MB) Data source: WHO GHO OData API — 30 indicators across infectious diseases, vaccines, and health metrics

Health Determinants KG

Population vulnerability indicators from World Bank WDI, WHO Air Quality, and WHO Water/Sanitation — 80 curated indicators across 211 countries (1990–2024).

Schema

graph LR
    Country -->|IN_REGION| Region
    Country -->|HAS_INDICATOR| SocioeconomicIndicator
    Country -->|ENVIRONMENT_OF| EnvironmentalFactor
    Country -->|NUTRITION_STATUS| NutritionIndicator
    Country -->|DEMOGRAPHIC_OF| DemographicProfile
    Country -->|WATER_RESOURCE_OF| WaterResource

    style Country fill:#84cc16,stroke:#333,color:#fff
    style Region fill:#06b6d4,stroke:#333,color:#fff
    style SocioeconomicIndicator fill:#f59e0b,stroke:#333,color:#fff
    style EnvironmentalFactor fill:#ef4444,stroke:#333,color:#fff
    style NutritionIndicator fill:#10b981,stroke:#333,color:#fff
    style DemographicProfile fill:#8b5cf6,stroke:#333,color:#fff
    style WaterResource fill:#3b82f6,stroke:#333,color:#fff

Performance

• Rust native loader: 285,635 nodes + 285,628 edges in 2.4s
• Snapshot: 6.5 MB (health-determinants.sgsnap)
• Benchmark: 40/40 queries pass (median 15ms)

Sources

Repository: samyama-ai/health-determinants-kg Rust loader: examples/health_determinants_loader.rs in samyama-graph-enterprise Snapshot: health-determinants.sgsnap (6.5 MB)

Health Systems KG

Health system capacity — IHR emergency preparedness and health workforce density from WHO, across 233 countries.

Schema

graph LR
    EmergencyResponse -->|CAPACITY_FOR| Country
    HealthWorkforce -->|SERVES| Country

    style Country fill:#f97316,stroke:#333,color:#fff
    style EmergencyResponse fill:#ef4444,stroke:#333,color:#fff
    style HealthWorkforce fill:#3b82f6,stroke:#333,color:#fff

Performance

• Rust native loader: 19,661 nodes + 19,428 edges in 149ms
• Snapshot: 0.5 MB (health-systems.sgsnap)
• Benchmark: 40/40 queries pass (cross-KG with Health Determinants)

Sources

Pending sources (loaders built, data not yet downloaded): GAVI vaccine supply, Global Fund disbursements, IHME health expenditure

Repository: samyama-ai/health-systems-kg Rust loader: examples/health_systems_loader.rs in samyama-graph-enterprise Snapshot: health-systems.sgsnap (0.5 MB)

AssetOps KG

Synthetic industrial operations graph from the AssetOpsBench benchmark. Models assets, sensors, maintenance schedules, and failure modes for industrial IoT.

Repository: samyama-ai/assetops-kg (private)

Quick Start — Loading Any Snapshot

All snapshots follow the same load pattern:

# 1. Start Samyama Graph (v1.0.0+)
./target/release/samyama

# 2. Create a tenant
curl -X POST http://localhost:8080/api/tenants \
  -H 'Content-Type: application/json' \
  -d '{"id":"TENANT_ID","name":"TENANT_NAME"}'

# 3. Import snapshot into the tenant
curl -X POST http://localhost:8080/api/tenants/TENANT_ID/snapshot/import \
  -F "file=@snapshot.sgsnap"

# 4. Query
curl -X POST http://localhost:8080/api/query \
  -H 'Content-Type: application/json' \
  -d '{"query":"MATCH (n) RETURN labels(n), count(n)","graph":"TENANT_ID"}'

# 5. Explore in Insight
cd samyama-insight && npm run dev
# → http://localhost:5173 (select tenant from dropdown)
# → http://localhost:5173/simulation/TENANT_ID

Note: Use /api/tenants/:id/snapshot/import (tenant-specific endpoint), NOT /api/snapshot/import. The generic endpoint always loads into the default tenant.

Cross-KG Federation

When multiple knowledge graphs share entity types — the same proteins, drugs, or genes appear in different datasets — loading them into the same Samyama tenant creates a federated graph where a single Cypher query can traverse across data sources.

This chapter shows how to combine the Pathways KG and Clinical Trials KG into a single biomedical graph and answer questions that neither KG can answer alone.

Why Federation?

The Pathways KG knows molecular biology — which proteins interact, what pathways they participate in, which GO processes they’re annotated with. The Clinical Trials KG knows translational medicine — which drugs are in trials, what conditions they treat, what adverse events they cause.

Neither KG alone can answer:

“Which biological pathways are disrupted by drugs currently in Phase 3 trials for breast cancer?”

This query requires traversing:

ClinicalTrial (phase='Phase 3') → STUDIES → Condition (name contains 'breast cancer')
ClinicalTrial → TESTS → Intervention → CODED_AS_DRUG → Drug
Drug → TARGETS → Protein
Protein → PARTICIPATES_IN → Pathway

The first two hops live in the Clinical Trials KG. The last two hops live in the Pathways KG. The Drug → TARGETS → Protein edge is the bridge.

graph LR
    subgraph "Clinical Trials KG"
        CT["ClinicalTrial<br/>(Phase 3)"]
        COND["Condition<br/>(Breast Cancer)"]
        INT["Intervention"]
        DRUG_CT["Drug"]
    end

    subgraph "Bridge Entities"
        DRUG["Drug<br/>(drugbank_id)"]
        PROT["Protein<br/>(uniprot_id)"]
        GENE["Gene<br/>(gene_id)"]
    end

    subgraph "Pathways KG"
        PROT_PW["Protein"]
        PATHWAY["Pathway"]
        GOTERM["GOTerm"]
    end

    CT -->|STUDIES| COND
    CT -->|TESTS| INT
    INT -->|CODED_AS_DRUG| DRUG_CT
    DRUG_CT -.->|"same drugbank_id"| DRUG
    DRUG -->|TARGETS| PROT
    PROT -.->|"same uniprot_id"| PROT_PW
    GENE -->|ENCODES| PROT
    GENE -->|ASSOCIATED_WITH| COND
    PROT_PW -->|PARTICIPATES_IN| PATHWAY
    PROT_PW -->|ANNOTATED_WITH| GOTERM

    style CT fill:#8b5cf6,stroke:#333,color:#fff
    style COND fill:#ef4444,stroke:#333,color:#fff
    style INT fill:#3b82f6,stroke:#333,color:#fff
    style DRUG_CT fill:#10b981,stroke:#333,color:#fff
    style DRUG fill:#10b981,stroke:#333,color:#fff
    style PROT fill:#f59e0b,stroke:#333,color:#fff
    style GENE fill:#ec4899,stroke:#333,color:#fff
    style PROT_PW fill:#f59e0b,stroke:#333,color:#fff
    style PATHWAY fill:#10b981,stroke:#333,color:#fff
    style GOTERM fill:#8b5cf6,stroke:#333,color:#fff

Join Points

Three entity types appear in both KGs with matching identifiers:

Loading Multiple Snapshots into One Tenant

Step 1: Start the server

./target/release/samyama

Step 2: Create a combined tenant

curl -X POST http://localhost:8080/api/tenants \
  -H 'Content-Type: application/json' \
  -d '{"id":"biomedical","name":"Biomedical (Pathways + Clinical Trials)"}'

Step 3: Load snapshots sequentially

Load the smaller snapshot first, then the larger one. Each import appends to the existing graph — nodes and edges accumulate.

# Pathways first (9 MB, ~119K nodes)
curl -X POST http://localhost:8080/api/tenants/biomedical/snapshot/import \
  -F "file=@pathways.sgsnap"
# Expected: 118,686 nodes, 834,785 edges

# Clinical Trials second (711 MB, ~7.7M nodes)
curl -X POST http://localhost:8080/api/tenants/biomedical/snapshot/import \
  -F "file=@clinical-trials.sgsnap"
# Expected: 7,711,965 nodes, 27,069,085 edges

Step 4: Verify the combined graph

curl -X POST http://localhost:8080/api/query \
  -H 'Content-Type: application/json' \
  -d '{"query":"MATCH (n) RETURN labels(n) AS label, count(n) AS count ORDER BY count DESC","graph":"biomedical"}'

You should see labels from both KGs:

Important: Snapshot import creates new nodes — it does not merge on matching properties. This means a Protein like TP53 may exist as two separate nodes (one from each snapshot) with the same uniprot_id. Cross-KG queries must join on properties, not on node identity.

Cross-KG Federated Queries

Since nodes from different snapshots are not merged, cross-KG queries use property-based joins — matching on shared identifiers like uniprot_id or drugbank_id.

Query 1: Pathways disrupted by drugs in Phase 3 breast cancer trials

-- Find drugs in Phase 3 breast cancer trials
MATCH (ct:ClinicalTrial)-[:STUDIES]->(cond:Condition)
WHERE ct.phase = 'Phase 3'
  AND cond.name CONTAINS 'Breast'
WITH ct
MATCH (ct)-[:TESTS]->(int:Intervention)-[:CODED_AS_DRUG]->(drug:Drug)
WITH DISTINCT drug

-- Bridge to pathways via protein targets (property join)
MATCH (drug)-[:TARGETS]->(prot1:Protein)
MATCH (prot2:Protein)-[:PARTICIPATES_IN]->(pw:Pathway)
WHERE prot1.uniprot_id = prot2.uniprot_id

RETURN pw.name AS pathway,
       count(DISTINCT drug.name) AS drugs_targeting,
       collect(DISTINCT drug.name) AS drug_names
ORDER BY drugs_targeting DESC
LIMIT 15

Query 2: GO processes affected by trial drugs

-- Drugs being tested in active trials
MATCH (ct:ClinicalTrial)-[:TESTS]->(int:Intervention)-[:CODED_AS_DRUG]->(drug:Drug)
WHERE ct.overall_status = 'RECRUITING'
WITH DISTINCT drug

-- Bridge to GO annotations via protein targets
MATCH (drug)-[:TARGETS]->(prot1:Protein)
MATCH (prot2:Protein)-[:ANNOTATED_WITH]->(go:GOTerm)
WHERE prot1.uniprot_id = prot2.uniprot_id
  AND go.namespace = 'biological_process'

RETURN go.name AS biological_process,
       count(DISTINCT drug.name) AS drugs,
       count(DISTINCT prot2.name) AS proteins
ORDER BY drugs DESC
LIMIT 10

Query 3: PPI neighbors of clinical drug targets

-- Find proteins targeted by a specific drug
MATCH (drug:Drug {name: 'Trastuzumab'})-[:TARGETS]->(target:Protein)
WITH target

-- Find interaction partners in pathways PPI network
MATCH (pw_prot:Protein)-[:INTERACTS_WITH]-(partner:Protein)
WHERE pw_prot.uniprot_id = target.uniprot_id

RETURN target.name AS drug_target,
       partner.name AS ppi_neighbor,
       count(*) AS interaction_strength
ORDER BY interaction_strength DESC
LIMIT 20

Query 4: Disease ↔ Pathway connections through genes

-- Genes associated with a disease (from clinical trials KG)
MATCH (gene:Gene)-[:ASSOCIATED_WITH]->(cond:Condition)
WHERE cond.name CONTAINS 'Diabetes'
WITH gene

-- Gene's protein → pathways (from pathways KG)
MATCH (gene)-[:ENCODES]->(prot1:Protein)
MATCH (prot2:Protein)-[:PARTICIPATES_IN]->(pw:Pathway)
WHERE prot1.uniprot_id = prot2.uniprot_id

RETURN pw.name AS pathway,
       count(DISTINCT gene.symbol) AS genes,
       collect(DISTINCT gene.symbol) AS gene_list
ORDER BY genes DESC
LIMIT 10

Query 5: Adverse events linked to pathway disruption

-- Drugs with serious adverse events
MATCH (drug:Drug)<-[:CODED_AS_DRUG]-(int:Intervention)<-[:TESTS]-(ct:ClinicalTrial)
MATCH (ct)-[:REPORTED]->(ae:AdverseEvent)
WHERE ae.is_serious = true
WITH drug, count(DISTINCT ae.term) AS ae_count
WHERE ae_count >= 5

-- What pathways do these drugs target?
MATCH (drug)-[:TARGETS]->(prot1:Protein)
MATCH (prot2:Protein)-[:PARTICIPATES_IN]->(pw:Pathway)
WHERE prot1.uniprot_id = prot2.uniprot_id

RETURN drug.name AS drug,
       ae_count AS serious_adverse_events,
       collect(DISTINCT pw.name) AS targeted_pathways
ORDER BY ae_count DESC
LIMIT 10

Testing Instructions

Prerequisites

• Samyama Graph Enterprise v1.0.0+ running on localhost:8080
• Snapshots downloaded:
  • pathways.sgsnap from kg-snapshots-v3
  • clinical-trials.sgsnap from kg-snapshots-v1
• At least 8 GB free RAM (Clinical Trials KG is large)

Step-by-step test script

#!/bin/bash
# test_cross_kg_federation.sh
# Tests cross-KG federation between Pathways and Clinical Trials

set -e
API="http://localhost:8080"

echo "=== Step 1: Create biomedical tenant ==="
curl -s -X POST "$API/api/tenants" \
  -H 'Content-Type: application/json' \
  -d '{"id":"biomedical","name":"Biomedical Federation"}' | python3 -m json.tool

echo -e "\n=== Step 2: Load Pathways KG ==="
curl -s -X POST "$API/api/tenants/biomedical/snapshot/import" \
  -F "file=@pathways.sgsnap" | python3 -c "
import sys,json; d=json.load(sys.stdin)
print(f'  Pathways: {d[\"nodes_imported\"]:,} nodes, {d[\"edges_imported\"]:,} edges')"

echo -e "\n=== Step 3: Load Clinical Trials KG ==="
echo "  (This may take 1-2 minutes for the 711 MB snapshot)"
curl -s -X POST "$API/api/tenants/biomedical/snapshot/import" \
  -F "file=@clinical-trials.sgsnap" | python3 -c "
import sys,json; d=json.load(sys.stdin)
print(f'  Clinical Trials: {d[\"nodes_imported\"]:,} nodes, {d[\"edges_imported\"]:,} edges')"

echo -e "\n=== Step 4: Verify combined graph ==="
curl -s -X POST "$API/api/query" \
  -H 'Content-Type: application/json' \
  -d '{"query":"MATCH (n) RETURN labels(n) AS label, count(n) AS count ORDER BY count DESC","graph":"biomedical"}' | python3 -c "
import sys,json
for r in json.load(sys.stdin)['records']:
    print(f'  {r[0][0]:20s} {r[1]:>10,}')"

echo -e "\n=== Step 5: Check join points ==="

echo "  Proteins with uniprot_id (Pathways):"
curl -s -X POST "$API/api/query" \
  -H 'Content-Type: application/json' \
  -d '{"query":"MATCH (p:Protein) WHERE p.uniprot_id IS NOT NULL RETURN count(p) AS proteins_with_uid","graph":"biomedical"}' | python3 -c "
import sys,json; print(f'    {json.load(sys.stdin)[\"records\"][0][0]:,}')"

echo "  Drugs with drugbank_id:"
curl -s -X POST "$API/api/query" \
  -H 'Content-Type: application/json' \
  -d '{"query":"MATCH (d:Drug) WHERE d.drugbank_id IS NOT NULL RETURN count(d) AS drugs_with_dbid","graph":"biomedical"}' | python3 -c "
import sys,json; print(f'    {json.load(sys.stdin)[\"records\"][0][0]:,}')"

echo -e "\n=== Step 6: Cross-KG query — Pathways disrupted by Phase 3 breast cancer drugs ==="
curl -s -X POST "$API/api/query" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "MATCH (ct:ClinicalTrial)-[:STUDIES]->(cond:Condition) WHERE ct.phase = '\"'\"'Phase 3'\"'\"' AND cond.name CONTAINS '\"'\"'Breast'\"'\"' WITH ct MATCH (ct)-[:TESTS]->(int:Intervention)-[:CODED_AS_DRUG]->(drug:Drug) WITH DISTINCT drug MATCH (drug)-[:TARGETS]->(prot1:Protein) MATCH (prot2:Protein)-[:PARTICIPATES_IN]->(pw:Pathway) WHERE prot1.uniprot_id = prot2.uniprot_id RETURN pw.name AS pathway, count(DISTINCT drug.name) AS drugs ORDER BY drugs DESC LIMIT 10",
    "graph": "biomedical"
  }' | python3 -c "
import sys,json
d=json.load(sys.stdin)
if 'error' in d:
    print(f'  Error: {d[\"error\"]}')
else:
    print(f'  Columns: {d[\"columns\"]}')
    for r in d.get('records',[])[:10]:
        print(f'    {r}')"

echo -e "\n=== Step 7: Simpler cross-KG validation — shared proteins ==="
curl -s -X POST "$API/api/query" \
  -H 'Content-Type: application/json' \
  -d '{"query":"MATCH (p1:Protein)-[:PARTICIPATES_IN]->(pw:Pathway) MATCH (p2:Protein)<-[:TARGETS]-(d:Drug) WHERE p1.uniprot_id = p2.uniprot_id RETURN count(DISTINCT p1.uniprot_id) AS shared_proteins, count(DISTINCT d.name) AS drugs, count(DISTINCT pw.name) AS pathways","graph":"biomedical"}' | python3 -c "
import sys,json
d=json.load(sys.stdin)
if 'error' in d:
    print(f'  Error: {d[\"error\"]}')
else:
    r=d['records'][0]; print(f'  Shared proteins: {r[0]}, Drugs: {r[1]}, Pathways: {r[2]}')"

echo -e "\n=== Done ==="

Expected results

If both snapshots loaded correctly:

1. Label distribution should show labels from both KGs (Pathway, GOTerm, Protein from Pathways; ClinicalTrial, Condition, Intervention from Clinical Trials)
2. Join points should show thousands of proteins with uniprot_id and hundreds of drugs with drugbank_id
3. Cross-KG query should return pathways like “Signal Transduction”, “Immune System”, “Disease” that are targeted by Phase 3 breast cancer drugs
4. Shared proteins count should be > 0, confirming the bridge works

Troubleshooting

Architecture Notes

Why Property Joins (Not Node Merging)?

Snapshot import creates fresh nodes with auto-assigned IDs. Two Protein nodes from different snapshots with the same uniprot_id are distinct graph nodes. We join them via WHERE p1.uniprot_id = p2.uniprot_id.

Trade-offs:

For production workloads, consider building a dedicated cross-KG ETL that uses MERGE on shared identifiers during loading. For exploration and prototyping, property joins work well.

Future: Native Cross-Tenant Queries

A future Samyama release may support cross-tenant query federation natively, allowing:

-- Hypothetical future syntax
MATCH (drug:Drug)-[:TARGETS]->(p:Protein)
  ON TENANT 'clinical'
MATCH (p2:Protein)-[:PARTICIPATES_IN]->(pw:Pathway)
  ON TENANT 'pathways'
WHERE p.uniprot_id = p2.uniprot_id
RETURN pw.name, drug.name

Until then, loading into a single tenant with property joins is the recommended approach.

Ontology & Standards Catalog

This catalog surveys 147 publicly available ontologies, knowledge graphs, and standards relevant to Samyama Graph’s knowledge graph ecosystem — organized by domain, ranked by relevance tier.

Source of truth: data/ontology_catalog.csv — machine-readable, importable into any tool or pipeline.

Relevance Tiers

A. Public Health & Epidemiology (31)

Core ontologies for disease classification, surveillance, epidemiology, and LMIC health systems.

B. Social Determinants & Environmental Health (14)

Ontologies mapping environmental exposures, social factors, and their health impacts.

C. Biomedical & Clinical (32)

Disease, drug, genomics, clinical, and anatomy ontologies plus major biomedical knowledge graphs.

D. AI Safety, Ethics & Evaluation (24)

Risk taxonomies, regulatory frameworks, fairness definitions, and adversarial threat models.

E. Human Rights & Humanitarian (19)

Human rights instruments, humanitarian standards, GBV taxonomies, and crisis data.

F–J. Additional Domains

F. Agriculture & Food Security (8)

G. Accessibility & Disability (6)

H. Education & Workforce (5)

I. Legal & Governance (5)

J. Geospatial & Infrastructure (4)

How These Connect to Samyama KGs

Currently Loaded (code-verified)

graph LR
    subgraph "Samyama KGs"
        PKG["Pathways KG"]
        CTKG["Clinical Trials KG"]
        DIKG["Drug Interactions KG"]
        DSKG["Surveillance KG"]
    end

    subgraph "Loaded via API/Download"
        GO["Gene Ontology<br/>go.json.gz + annotations"]
        Reactome["Reactome<br/>5 data files"]
        STRING["STRING v12<br/>PPI, score≥700"]
        UniProt["UniProt<br/>REST API, human reviewed"]
        WikiP["WikiPathways<br/>.gmt file"]
        MeSH["MeSH<br/>NLM API"]
        RxNorm["RxNorm<br/>rxnav.nlm.nih.gov API"]
        ATC["ATC<br/>from RxNorm properties"]
        OpenFDA["OpenFDA<br/>api.fda.gov"]
        PubMed["PubMed<br/>NCBI E-utilities"]
        DrugBank["DrugBank CC0<br/>vocabulary CSV"]
        DGIdb["DGIdb<br/>interactions TSV"]
        SIDER["SIDER<br/>MedDRA side effects"]
        GHO["WHO GHO<br/>OData API"]
    end

    GO -->|"47K terms"| PKG
    Reactome -->|"pathways"| PKG
    STRING -->|"PPI"| PKG
    UniProt -->|"proteins"| PKG
    WikiP -->|"pathways"| PKG
    MeSH -->|"conditions"| CTKG
    RxNorm -->|"drugs"| CTKG
    ATC -->|"drug classes"| CTKG
    OpenFDA -->|"adverse events"| CTKG
    PubMed -->|"publications"| CTKG
    DrugBank -->|"drug vocab"| DIKG
    DGIdb -->|"drug-gene"| DIKG
    SIDER -->|"side effects"| DIKG
    GHO -->|"indicators"| DSKG

    style PKG fill:#10b981,stroke:#333,color:#fff
    style CTKG fill:#8b5cf6,stroke:#333,color:#fff
    style DIKG fill:#ec4899,stroke:#333,color:#fff
    style DSKG fill:#06b6d4,stroke:#333,color:#fff

Logical Map (full vision including planned)

graph LR
    subgraph "Live KGs"
        PKG["Pathways KG<br/>119K nodes"]
        CTKG["Clinical Trials KG<br/>7.7M nodes"]
        DIKG["Drug Interactions KG<br/>245K nodes"]
        DSKG["Surveillance KG<br/>217K nodes"]
        HDKG["Health Determinants KG<br/>286K nodes"]
        HSKG["Health Systems KG<br/>20K nodes"]
    end

    subgraph "Loaded"
        GO["Gene Ontology"]
        Reactome["Reactome"]
        STRING["STRING"]
        UniProt["UniProt"]
        MeSH["MeSH"]
        RxNorm["RxNorm"]
        ATC["ATC"]
        DrugBank["DrugBank"]
        DGIdb["DGIdb"]
        SIDER["SIDER"]
        GHO["WHO GHO"]
    end

    subgraph "Planned Integrations"
        SNOMED["SNOMED CT"]
        ICD["ICD-11"]
        LOINC["LOINC"]
        UMLS["UMLS"]
        WDI["World Bank WDI"]
        AQUASTAT["FAO AQUASTAT"]
        GAVI["GAVI"]
        SPAR["WHO SPAR"]
    end

    GO --> PKG
    Reactome --> PKG
    STRING --> PKG
    UniProt --> PKG
    MeSH --> CTKG
    RxNorm --> CTKG
    ATC --> CTKG
    DrugBank --> DIKG
    DGIdb --> DIKG
    SIDER --> DIKG
    GHO --> DSKG

    SNOMED -.->|"planned"| CTKG
    ICD -.->|"planned"| DSKG
    LOINC -.->|"planned"| CTKG
    UMLS -.->|"planned"| CTKG
    WDI -.->|"planned"| HDKG
    AQUASTAT -.->|"planned"| HDKG
    GAVI -.->|"planned"| HSKG
    SPAR -.->|"planned"| HSKG

    DSKG -.->|"Region"| HDKG
    DSKG -.->|"Region"| HSKG
    DSKG -.->|"Disease"| CTKG
    DIKG -.->|"Gene"| PKG
    DIKG -.->|"Drug"| CTKG

    style PKG fill:#10b981,stroke:#333,color:#fff
    style CTKG fill:#8b5cf6,stroke:#333,color:#fff
    style DIKG fill:#ec4899,stroke:#333,color:#fff
    style DSKG fill:#06b6d4,stroke:#333,color:#fff
    style HDKG fill:#84cc16,stroke:#333,color:#fff,stroke-dasharray: 5 5
    style HSKG fill:#f97316,stroke:#333,color:#fff,stroke-dasharray: 5 5

Not Yet Loaded

Data source: data/ontology_catalog.csv — 147 entries across 10 categories.

Real-world Use Cases

Samyama is not just a research project; it is designed to solve complex, real-world problems. We include several fully functional demos in the examples/ directory of the repository.

Here are three key scenarios where Samyama shines.

1. Banking: Fraud Detection

Source: examples/banking_demo.rs

Financial fraud often involves complex networks of transactions that traditional SQL databases struggle to uncover.

The Scenario: A money laundering ring moves illicit funds through a series of “mule” accounts to hide the origin, eventually depositing it back into a clean account. This creates a cycle.

The Solution: We model the data as:

• Nodes: Account
• Edges: TRANSFER (with properties amount, date)

The Query:

MATCH (a:Account)-[t1:TRANSFER]->(b:Account)-[t2:TRANSFER]->(c:Account)-[t3:TRANSFER]->(a)
WHERE t1.amount > 10000 
  AND t2.amount > 9000 
  AND t3.amount > 8000
RETURN a.id, b.id, c.id

This simple query instantly reveals circular transaction patterns that would require massive, slow JOINs in SQL.

2. Supply Chain: Dependency Analysis

Source: examples/supply_chain_demo.rs

Modern supply chains are fragile. Knowing “who supplies my supplier” is critical for risk management.

The Scenario: A factory produces a “Car”. It needs an “Engine”, which needs “Pistons”, which needs “Steel”. If a strike hits the Steel mill, how does it affect Car production?

The Solution: We use the Graph Algorithms module (specifically Breadth-First Search or custom traversal).

The Logic:

1. Start at the “Steel Mill” node.
2. Traverse all outgoing SUPPLIES edges recursively.
3. Identify all downstream Factory nodes.
4. Calculate the “Risk Score” based on the dependency depth.

Developer Tip: You can run this exact scenario locally: cargo run --example supply_chain_demo. It builds the graph, calculates risks, and outputs a JSON tree of cascading failures.

3. Knowledge Graph: Clinical Trials

Source: examples/clinical_trials_demo.rs + examples/knowledge_graph_demo.rs

Medical research is unstructured. Trials, drugs, and conditions are buried in text documents.

The Scenario: A researcher wants to find “Drugs used for Hypertension that have a mechanism similar to ACE inhibitors.”

The Solution (Graph RAG):

1. Ingest: Load ClinicalTrials.gov data into Samyama.
2. Embed: Use the “Auto-Embed” pipeline to turn the “Mechanism of Action” text into vectors.
3. Query:
   • Vector Search: Find drugs with description similar to “ACE inhibitor”.
   • Graph Filter: MATCH (drug)-[:TREATS]->(c:Condition {name: 'Hypertension'}).

4. Smart Manufacturing: Production Optimization

Source: examples/smart_manufacturing_demo.rs

In a modern factory, thousands of variables must be balanced: machine speed, energy cost, and maintenance schedules.

The Solution: Samyama uses its built-in Jaya or GWO (Grey Wolf Optimizer) to adjust production rates across the graph. The objective is to maximize output while keeping total energy consumption below a specific threshold (the constraint).

5. Enterprise SOC: Threat Hunting

Source: examples/enterprise_soc_demo.rs

Security Operations Centers (SOC) deal with millions of events (logins, file access, network traffic).

The Solution: By modeling logs as a graph, security analysts can run Pathfinding algorithms to trace the “Lateral Movement” of an attacker.

• Graph RAG: Use vector search to find “unusual login behavior” semantically similar to known attack patterns.

6. Healthcare: Resource Allocation

Source: examples/clinical_trials_demo.rs (Resource management variant)

Hospitals must constantly balance budget constraints with patient wait times across departments like ER, ICU, and Surgery.

The Solution: Samyama models each department as a node with properties for current staffing (Doctors, Nurses) and equipment (Beds).

• Optimization: Using the Jaya algorithm, Samyama calculates the optimal distribution of 1,000+ staff members across the entire hospital network.
• The Result: Minimize “Total Weighted Wait Time” while ensuring no department falls below “Minimum Staffing” regulations.

7. Social Network Analysis

Source: examples/social_network_demo.rs

Model and analyze social graphs with community detection, influence propagation, and friend-of-friend recommendations. Demonstrates how PageRank and CDLP algorithms identify key influencers and natural communities within large networks.

8. PCA & Dimensionality Reduction

Source: examples/pca_demo.rs

Demonstrates Principal Component Analysis on node feature vectors. Reduces high-dimensional property data (e.g., user profiles with 10+ numeric attributes) down to 2-3 principal components for visualization and clustering. Showcases both the Randomized SVD and Power Iteration solvers.

The Interactive Experience: run_all_examples.sh

To make these use cases accessible, Samyama includes a comprehensive, menu-driven script: scripts/run_all_examples.sh. This script allows users to:

1. Build the entire engine and its dependencies.
2. Start the Samyama server with a single keystroke.
3. Run any of the embedded Rust demos (Banking, Supply Chain, etc.).
4. Execute the new Python Client Demo (examples/simple_client_demo.py), which showcases the high-performance Python bindings over the RESP protocol.

This interactive tool, combined with our Graph Visualizer (scripts/visualize.py), allows developers to see the graph structure and optimization results in real-time, bridging the gap between abstract algorithms and concrete business value.

Mega Benchmark: 500 Queries Across 11 Knowledge Graphs

500 queries. 11 knowledge graphs. 138 million nodes. 1.22 billion edges. One graph, one query language, one server.

Samyama Graph Enterprise v1.0.0 runs the full 500-query mega benchmark across eleven independently-sourced knowledge graphs loaded into a single federated graph — on a single commodity EC2 spot instance.

Headline

500 / 500 pass (100%) — 468 full-pass + 32 data_dependent zero-row matches whose corpus-gap reasons are recorded in the oracle (NCT bridge absent, drug-name casing, no Depression cohort in the OMOP slice, etc.). 0 errors. 0 unexplained empties.

• Total runtime 78 min; query runtime 28 min; load ~50 min
• Six prefixes hit 100% including all three cross-KG categories (XK, PH, MB)

Reproduction caveat: this result was obtained by importing per-KG .sgsnap files via the binary’s startup load path. The HTTP /api/snapshot/import endpoint is capped at 2 GB and cannot ingest pubmed-v2.sgsnap (11 GB) or trifecta-pubmed.sgsnap (12 GB). Reproducing via the HTTP path requires the body-limit fix tracked in samyama-graph.

The Dataset

How the engine clears the workload

Three execution patterns carry the bulk of the 500 queries:

• Adjacency-aware aggregation (ADR-017) — count(neighbor) over a degree-bounded match set walks per-node adjacency lists rather than scanning every edge. Without this, top-N degree queries time out on PubMed-scale data.
• Streaming WITH … LIMIT — WithBarrier stops scanning upstream after N rows when no ORDER BY / WHERE / DISTINCT follows. Pipeline stages no longer materialize their full input when the next stage only needs a few rows.
• Cypher three-valued logic — IS NOT NULL AND <bool> short-circuits per spec; chained WHERE clauses AND-combine cleanly. The query author can write what they mean without the engine silently dropping predicates.

Together these shift the bottleneck from engine correctness to corpus coverage. The expected_rows.yaml oracle records each data_dependent empty with a specific corpus reason — so the remaining work is loader, not engine.

What data_dependent covers (32 queries)

These return zero rows but are expected to — the dataset, not the engine, is the constraint:

Infrastructure

Reproducing

# On r7i.16xlarge ap-south-1, AMI ami-0d219aaceb19e2c84
./target/release/examples/unified_benchmark \
  --pubmed-snap ~/snapshots/pubmed-v2.sgsnap \
  --ct-snap ~/snapshots/clinical-trials.sgsnap \
  --pw-snap ~/snapshots/pathways.sgsnap \
  --faers-snap ~/snapshots/faers-full.sgsnap \
  --uniprot-snap ~/snapshots/uniprot.sgsnap \
  --omop-snap ~/snapshots/omop-115k.sgsnap \
  --di-snap ~/snapshots/druginteractions.sgsnap \
  --surv-snap ~/snapshots/surveillance.sgsnap \
  --hd-snap ~/snapshots/health-determinants.sgsnap \
  --hs-snap ~/snapshots/health-systems.sgsnap \
  --study-refs ~/study_references.txt \
  --queries ~/benchmark-queries

Snapshots are public at s3://samyama-data/snapshots/. Query CSVs and the raw run output live in this repo under src/data/benchmark/ (benchmark-v100-results.csv).

Hero Run — 187.5M nodes, 1.29B edges, 99% pass (2026-04-30)

Two weeks after the 500/500 mega-benchmark, we ran a larger sweep: a 1000-query corpus against a 187.5M-node / 1.29B-edge graph stitched from the same 11 KGs at full scale (PubMed at 100%, FAERS at full extract, OMOP via Synthea-generated synthetic patients).

Two engine fixes landed during the run (2026-05-01) and are now in main:

• String-fn NULL-property handling (a small surfaced gap in 3VL coverage).
• Snapshot multi-label index rebuild after import (closed a latent bug when bridge-loading multiple snapshots into one tenant).

The hero run also produced our first cross-KG entity dedup in production — ChEMBL ↔ UniProt joined on the accession property via ADR-019’s import_tenant_with_dedup path.

The hero run is the workload that validates the v1.0 architectural decisions at the scale we care about. The 500-query mega benchmark is the correctness floor (must hit 100% on a curated set); the 1000-query hero run is the stress ceiling (pass rate under real-world noise on a >1B-edge graph).

Biomedical Knowledge Graph Benchmark

100 queries. 4 knowledge graphs. 74 million nodes. 1 billion edges. One query language.

Samyama’s biomedical benchmark demonstrates real-world cross-knowledge-graph queries across the largest open biomedical dataset we know of — unified in a single queryable graph on commodity hardware.

The 100-query workload below is the four-KG biomedical subset. The Mega Benchmark extends it to 500 queries across 11 KGs (adding FAERS, OMOP, UniProt, and the public-health trifecta), with 500/500 passing on the current engine.

The Dataset

Results Summary

100 queries executed. 96 returned data. 3 returned empty (specific data not in snapshot). 1 timed out.

Infrastructure

• Instance: r6a.8xlarge (32 vCPU, 256 GB RAM, AMD EPYC)
• Cost: ~$2.50 (AWS spot, ap-south-1)
• Import time: 31 minutes from v2 snapshots
• NCT bridge: 1,018,483 REFERENCED_IN edges created in 109 seconds
• Index creation: 10 indexes in ~320 seconds

PubMed Queries (35)

Point Lookups

1-Hop Traversals

Multi-Hop Analytics

Aggregations

Clinical Trials Queries (20)

Sample Queries

Aggregations

Complex Queries

Pathways Queries (15)

Drug Interactions Queries (15)

Cross-Knowledge-Graph Queries (15)

These traverse REFERENCED_IN edges connecting 747,505 PubMed articles to clinical trials via PMID↔NCT ID mapping from AACT study_references.

The Headline Results

-- XK02: What drugs are tested in cancer research trials?
-- Spans: MeSH → Article → ClinicalTrial → Intervention (3 KGs)
MATCH (m:MeSHTerm)<-[:ANNOTATED_WITH]-(a:Article)
      -[:REFERENCED_IN]->(t:ClinicalTrial)-[:TESTS]->(i:Intervention)
WHERE m.name = 'Neoplasms'
RETURN i.name, count(DISTINCT t) AS trials ORDER BY trials DESC LIMIT 10

Time: 5.2s — Pembrolizumab (Keytruda) is the most-tested non-placebo cancer drug.

-- XK03: What drugs are tested in diabetes research trials?
MATCH (m:MeSHTerm)<-[:ANNOTATED_WITH]-(a:Article)
      -[:REFERENCED_IN]->(t:ClinicalTrial)-[:TESTS]->(i:Intervention)
WHERE m.name = 'Diabetes Mellitus'
RETURN i.name, count(DISTINCT t) AS trials ORDER BY trials DESC LIMIT 10

Time: 2.4s

-- XK04: What adverse events appear in heart disease trials?
MATCH (m:MeSHTerm)<-[:ANNOTATED_WITH]-(a:Article)
      -[:REFERENCED_IN]->(t:ClinicalTrial)-[:REPORTED]->(ae:AdverseEvent)
WHERE m.name = 'Heart Diseases'
RETURN ae.term, count(DISTINCT t) AS trials ORDER BY trials DESC LIMIT 10

Time: 2.0s

-- XK06: What adverse events appear in Metformin-linked trials?
-- Spans: Chemical → Article → ClinicalTrial → AdverseEvent (4 entities)
MATCH (c:Chemical)<-[:MENTIONS_CHEMICAL]-(a:Article)
      -[:REFERENCED_IN]->(t:ClinicalTrial)-[:REPORTED]->(ae:AdverseEvent)
WHERE c.name = 'Metformin'
RETURN ae.term, count(DISTINCT t) AS trials ORDER BY trials DESC LIMIT 10

Time: 2.1s — Diarrhoea is a known Metformin side effect, confirmed across PubMed + ClinicalTrials.gov.

All Cross-KG Results

What These Results Mean

1. Pembrolizumab dominates cancer trials — The immunotherapy revolution is visible in the data. Across all PubMed articles annotated with “Neoplasms” that link to clinical trials, Keytruda appears in 137 trials, more than any classic chemotherapy agent.

2. Metformin’s GI side effects confirmed cross-database — Diarrhoea ranks 4th in Metformin-linked trial adverse events (185 trials), consistent with clinical knowledge. This was found by traversing Chemical → Article → Trial → AdverseEvent — four entities across two databases.

3. The US conducts 45% of global clinical trials — 190,879 of ~420K total trials. China is second at 1,170 cancer-specific trials.

4. Nature has 140,152 articles in PubMed — making it the most-indexed journal. DNA is its most-mentioned chemical (3,726 articles).

5. TP53 is the most connected protein — 571 interaction partners in Reactome, confirming its role as the “guardian of the genome.”

6. NCI NIH funds 46,137 cancer research papers — and those papers link to 933 placebo-controlled trials.

Query Files

The full query catalog and results are available as CSV for automated benchmarking:

• pubmed-queries.csv — 35 PubMed queries
• clinical-trials-queries.csv — 20 Clinical Trials queries
• pathways-queries.csv — 15 Pathways queries
• drug-interactions-queries.csv — 15 Drug Interactions queries
• cross-kg-queries.csv — 15 Cross-KG queries
• verified-results.csv — All 100 results with timings

Reproducing

All knowledge graph snapshots and the benchmark runner are included in Samyama Graph Enterprise Edition. Contact us to access the pre-built snapshots and benchmark tooling.

Public Health Knowledge Graph Benchmark

40 queries. 2 knowledge graphs. 305K nodes. 305K edges. Cross-KG federation with health system capacity data.

The public health benchmark demonstrates Samyama’s ability to load, query, and cross-correlate population health determinants with health system capacity data — answering questions from “Why are populations vulnerable?” to “What capacity exists to respond?”

See also: the public-health KGs are also part of the 11-KG Mega Benchmark federation — the HD/HS/PH prefixes there contribute 40 queries to the 500/500-pass v1.0 result, alongside biomedical, FAERS, OMOP, and UniProt content.

The Dataset

Data coverage:

• 211 countries with World Bank indicators across 5 categories (1990–2024)
• 233 countries with IHR SPAR v2 capacity scores + health workforce density (2020–2023)
• 80 curated WDI indicators: socioeconomic (16), environmental (10), nutrition (10), demographic (15), water (10)
• 1,880 country-year PM2.5 air quality records from WHO GHO
• 47,531 water/sanitation records (safely managed + basic water/sanitation)
• 11,008 health workforce density records (physicians, nurses, dentists, pharmacists)
• 15 IHR capacities: legislation, coordination, financing, laboratory, surveillance, human resources, emergency management, health services, IPC, risk communication, points of entry, zoonotic, food safety, chemical, radiation

Results Summary

40 queries executed. 40 returned data. 0 empty. 0 errors.

Performance

Infrastructure: MacBook Pro M-series, single process, in-memory graph loaded from .sgsnap snapshots.

Query Categories

Health Determinants (HD01–HD20)

Point lookups, indicator traversals, cross-category analysis, and regional aggregations over World Bank WDI data.

Health Systems (HS01–HS10)

IHR SPAR capacity queries — country profiles, rankings, gaps, and trends.

Cross-KG / Cross-Indicator (PH01–PH10)

Queries spanning multiple indicator categories or joining determinants with health system capacity data.

Sample Query Results

PH02: High poverty countries — do they have health capacity?

MATCH (c1:Country)-[:HAS_INDICATOR]->(pov:SocioeconomicIndicator)
WHERE pov.indicator_code = 'SI.POV.DDAY' AND pov.value > 20
WITH c1.iso_code AS iso, pov.value AS poverty
ORDER BY poverty DESC LIMIT 5
MATCH (e:EmergencyResponse)-[:CAPACITY_FOR]->(c2:Country)
WHERE c2.iso_code = iso AND e.year = 2023
RETURN c2.name, poverty, e.capacity_code, e.score
ORDER BY poverty DESC

This query identifies countries with >20% extreme poverty and correlates with their IHR emergency preparedness scores — answering “Are the most vulnerable populations in countries with the least health system capacity?”

PH07: Under-5 mortality + safe water access

MATCH (c:Country)-[:DEMOGRAPHIC_OF]->(d:DemographicProfile)
WHERE d.indicator_code = 'SH.DYN.MORT' AND d.year = 2022
WITH c, d.value AS u5_mortality
MATCH (c)-[:WATER_RESOURCE_OF]->(w:WaterResource)
WHERE w.indicator_code = 'SH.H2O.SMDW.ZS' AND w.year = 2022
RETURN c.name, u5_mortality, w.value AS safe_water_pct
ORDER BY u5_mortality DESC LIMIT 10

Central African Republic tops both worst lists: 387 under-5 deaths per 1,000 and only 6.1% safely managed drinking water.

6-KG Federation Vision

These two KGs complete the public health trifecta alongside the existing Surveillance KG (217K nodes). Together with the biomedical trifecta (Pathways + Clinical Trials + Drug Interactions), Samyama now supports queries spanning molecular biology to population health:

PUBLIC HEALTH TRIFECTA              BIOMEDICAL TRIFECTA
Surveillance (217K)  ←──────────→  Clinical Trials (7.7M)
         ↓ Country.iso_code               ↑ Drug
Health Determinants (240K)         Drug Interactions (245K)
         ↓ Country.iso_code               ↑ Gene
Health Systems (8.7K) ←─────────→  Pathways (119K)

Bridge property: Country.iso_code (ISO 3166-1 alpha-3) links all public health KGs. Cross-trifecta bridges use Disease.icd_code, Drug.drugbank_id, and Pathogen → Gene mappings.

Data Files

Snapshots

Available for download:

Performance & Benchmarks

Samyama is designed for “Mechanical Sympathy”—aligning software data structures with the physical reality of modern CPU caches and high-speed NVMe storage.

Micro-Benchmarks (Mac Mini M4)

All benchmarks run on Mac Mini M4, 16GB RAM, macOS. Comparison between the Community (CPU-only) and Enterprise (GPU-accelerated via wgpu) builds. For workload-level numbers across the full 11-KG federated dataset (138M nodes, 1.22B edges, 500 queries) see the Mega Benchmark.

Ingestion Throughput

Samyama achieves industry-leading ingestion rates on commodity hardware:

Note: Edge ingestion is significantly faster because it primarily involves appending to adjacency lists and updating the WAL.

Cypher Query Throughput (OLTP)

For transactional workloads, Samyama’s index-driven execution delivers consistent sub-millisecond latencies:

Index-driven lookups achieve O(1) or O(log n) access. QPS is measured with simple MATCH ... WHERE ... RETURN queries on indexed properties.

These numbers demonstrate that Samyama scales almost linearly—throughput at 1M nodes is comparable to 100K because index-based access eliminates full scans.

GPU Acceleration: The Crossover Point

A key finding from these benchmarks is the impact of memory transfer overhead on GPU acceleration.

Conclusion: For subgraphs smaller than 100,000 nodes, the CPU remains faster. Once the scale exceeds this “crossover point,” the GPU parallelism overcomes the memory transfer cost, leading to massive speedups.

Vector Search (HNSW, k=10)

Vector search utilizes hnsw_rs (CPU) for graph traversal. GPU acceleration in Enterprise is used for batch re-ranking after retrieval.

Note: The slight slowdown in the GPU build for small vector searches is due to the initialization overhead of the GPU context.

GPU at Scale: S-Size Datasets

On LDBC Graphalytics S-size datasets (millions of vertices), the GPU crossover becomes significant:

Note: Extremely dense graphs (e.g., 68M edges on datagen-7_5-fb) trigger CPU fallback due to the 256MB GPU buffer limit on Apple Silicon. Dedicated GPUs with larger VRAM can handle these datasets.

LDBC Graphalytics Validation

Samyama has achieved 100% validation against the LDBC Graphalytics benchmark suite—the industry standard for graph analytics correctness:

S-size datasets include cit-Patents (3.8M vertices), datagen-7_5-fb (633K vertices, 68M edges), and wiki-Talk (2.4M vertices). All results match LDBC reference outputs exactly.

Developer Tip: Run the validation yourself with cargo bench --bench graphalytics_benchmark. LDBC datasets are available in data/graphalytics/.

LDBC SNB Interactive & BI Workloads

Beyond Graphalytics (which validates algorithm correctness), Samyama includes benchmark harnesses for the LDBC Social Network Benchmark (SNB) — the industry-standard workload for graph database query performance.

SNB Interactive Workload

21 queries adapted for Samyama’s OpenCypher engine, plus 8 update operations:

cargo bench --bench ldbc_benchmark                    # All 21 queries
cargo bench --bench ldbc_benchmark -- --query IC6     # Single query
cargo bench --bench ldbc_benchmark -- --updates       # Include writes

SNB Business Intelligence (BI) Workload

20 complex analytical queries testing OLAP-style aggregation over the social network graph:

Note: Several BI queries require features beyond current OpenCypher coverage (APOC, CASE, list comprehensions). These are adapted to simplified Cypher that captures the analytical intent using supported constructs.

cargo bench --bench ldbc_bi_benchmark
cargo bench --bench ldbc_bi_benchmark -- --query BI-1

Both workloads operate on the LDBC SF1 dataset loaded via cargo run --example ldbc_loader.

LDBC FinBench Workload

Samyama also includes a harness for the LDBC Financial Benchmark (FinBench) — modeling financial transaction networks with accounts, persons, companies, loans, and mediums.

40+ queries total, covering both OLTP and analytical patterns for financial graph workloads.

cargo bench --bench finbench_benchmark
cargo bench --bench finbench_benchmark -- --query CR-1
cargo bench --bench finbench_benchmark -- --writes    # Include write operations

Data is loaded via cargo run --example finbench_loader, which can generate synthetic FinBench-compatible datasets.

The Power of Late Materialization

One of our most impactful architectural choices remains Late Materialization.

Latency Impact (1M nodes)

Bottleneck Analysis

Profiling our query engine reveals a shift in where time is spent:

Conclusion: The actual execution of the graph traversal is sub-millisecond. The remaining overhead is in the language frontend (parsing and planning). Our roadmap includes AST Caching and Plan Memoization to bring warm-query latency down to the ~10ms range.

Note: These timings reflect cold-start conditions (first query execution). Subsequent queries benefit from OS-level page cache and instruction cache warmth, reducing total latency significantly.

The Query Engine

The heart of Samyama is its query engine. It translates the user’s intent (expressed in OpenCypher) into actionable operations on the GraphStore.

From String to Execution Plan

When a user sends a query, it travels through a meticulously optimized pipeline:

graph TD
    Query["MATCH (p:Person)-[:KNOWS]->(f) WHERE p.age > 30 RETURN f.name"]
    Query --> Parser[pest Parser]
    Parser -- "Abstract Syntax Tree (AST)" --> Logical[QueryPlanner]
    
    subgraph "Cost-Based Optimizer"
        Logical -- "Generates Logical Plan" --> CBO[Optimizer]
        CBO -. "Reads GraphStatistics" .-> Stats["GraphStatistics"]
        CBO -- "Chooses Index over Full Scan" --> Physical["Physical Execution Plan"]
    end
    
    Physical --> Exec[QueryExecutor]

1. Parsing (cypher.pest): The query string is converted into an Abstract Syntax Tree (AST).
2. Logical Planning: The QueryPlanner processes the AST into an ExecutionPlan.
3. Optimization: The planner uses GraphStatistics to perform cost-based optimization (CBO), such as choosing the correct IndexManager scan instead of a full sequential scan.

Execution Model: The Volcano Iterator & Vectorized Processing

Samyama implements a hybrid Volcano Iterator model utilizing Vectorized Execution.

graph LR
    subgraph "Vectorized Pipeline"
        Scan[IndexScanOperator] -- "Batch of 1024 NodeIds" --> Expand[ExpandOperator]
        Expand -- "Batch of (SrcId, DstId)" --> Filter[FilterOperator]
        Filter -- "Filtered Batch" --> Project[ProjectOperator]
    end

#![allow(unused)]
fn main() {
pub struct QueryExecutor<'a> {
    store: &'a GraphStore,
    planner: QueryPlanner,
}

pub trait PhysicalOperator {
    /// High-performance batch path
    fn next_batch(&mut self, store: &GraphStore, batch_size: usize) -> Option<RecordBatch>;
}
}

(Simplified for clarity; the actual trait includes error handling via ExecutionResult and additional methods like describe() and name() for plan introspection.)

Instead of fetching one row at a time, each PhysicalOperator processes a RecordBatch.

All 35 Physical Operators

Samyama implements 35 physical operators, organized by function:

By processing batches:

• Amortized Overhead: Calling virtual functions per batch instead of per row drops L1 instruction cache misses significantly.
• Late Materialization: We pass lightweight NodeId arrays within RecordBatch columns. Actual properties are fetched from ColumnStore at the very end of the pipeline (ProjectOperator).

Advanced Profiling (EXPLAIN)

A key enterprise feature is the ability to inspect the Execution Plan without executing it. When a query starts with EXPLAIN, the QueryExecutor intercepts it:

#![allow(unused)]
fn main() {
if query.explain {
    return Ok(Self::explain_plan_with_stats(&plan, Some(self.store)));
}
}

The system returns a detailed tree of OperatorDescription instances combined with current GraphStatistics (null fractions, selectivity estimations). This allows database administrators to visualize exactly why the query planner chose a specific index over a graph traversal, enabling deep query tuning.

Query Optimization (Explain)

As queries grow in complexity—involving multiple hops, filters, and vector searches—it becomes impossible to optimize performance by guessing. Samyama provides EXPLAIN for query introspection, backed by a cost-based optimizer that uses graph statistics to choose efficient execution plans.

The Cost-Based Optimizer

Before a query is executed, the QueryPlanner transforms the AST into a physical execution plan. This involves selecting operators, ordering joins, and choosing between index scans and full scans—all based on real-time statistics.

graph TD
    AST["Parsed AST"] --> CBO["Cost-Based Optimizer"]
    CBO -. "Reads" .-> Stats["GraphStatistics"]

    subgraph "GraphStatistics"
        LC["Label Counts<br>Person: 10,000"]
        EC["Edge Type Counts<br>KNOWS: 50,000"]
        PS["Property Stats<br>age: 2% null, selectivity 0.01"]
    end

    CBO --> Plan["Optimized Physical Plan"]

    Plan --> IndexScan["IndexScan<br>(if selective filter)"]
    Plan --> NodeScan["NodeScan<br>(if no useful index)"]

How Statistics Are Gathered

GraphStore::compute_statistics() builds a GraphStatistics struct with:

Property stats include null_fraction, distinct_count, and selectivity—enabling the optimizer to predict how many rows survive a WHERE filter.

Cost Estimation Formulas

The optimizer uses these key estimation methods:

• estimate_label_scan(label): Returns the number of nodes with that label. For :Person with 10,000 nodes, cost = 10,000.
• estimate_expand(edge_type): Returns the number of edges of that type. For :KNOWS with 50,000 edges, cost = 50,000.
• estimate_equality_selectivity(label, property): Returns the fraction of nodes that match a given property value. For age = 30 on a label with 100 distinct age values, selectivity ≈ 0.01.

The planner multiplies these estimates through the operator tree to predict row counts at each stage.

Index Selection Heuristics

The optimizer decides between scan strategies based on selectivity:

Join Ordering

When a query involves multiple MATCH patterns (e.g., MATCH (a)-[:R]->(b)-[:S]->(c)), the optimizer orders joins to minimize intermediate result sizes:

1. Start with the pattern that produces the fewest rows (most selective label + filter)
2. Expand along edges with the lowest fan-out first
3. Apply filters as early as possible (predicate pushdown)

EXPLAIN: Visualizing the Plan

The EXPLAIN prefix tells the engine to parse and plan the query, but not execute it. It returns the operator tree that the physical executor will follow.

Example 1: Simple Traversal

EXPLAIN MATCH (n:Person)-[:KNOWS]->(m:Person)
WHERE n.age > 30
RETURN m.name

Output:

+----------------------------------+----------------+
| Operator                         | Estimated Rows |
+----------------------------------+----------------+
| ProjectOperator (m.name)         |             50 |
|   FilterOperator (n.age > 30)    |             50 |
|     ExpandOperator (-[:KNOWS]->) |            500 |
|       NodeScanOperator (:Person) |            100 |
+----------------------------------+----------------+

--- Statistics ---
Label 'Person': 100 nodes
Edge type 'KNOWS': 500 edges
Property 'age': null_fraction=0.02, distinct=40, selectivity=0.025

Example 2: Index-Driven Lookup

EXPLAIN MATCH (n:Person {name: 'Alice'})-[:KNOWS]->(m)
RETURN m.name

Output:

+----------------------------------------------+----------------+
| Operator                                     | Estimated Rows |
+----------------------------------------------+----------------+
| ProjectOperator (m.name)                     |              5 |
|   ExpandOperator (-[:KNOWS]->)               |              5 |
|     IndexScanOperator (:Person, name='Alice') |              1 |
+----------------------------------------------+----------------+

Notice the optimizer chose IndexScanOperator instead of NodeScanOperator + FilterOperator because name has an index and high selectivity.

Example 3: Aggregation with Sort

EXPLAIN MATCH (n:Person)-[:KNOWS]->(m:Person)
RETURN m.name, count(*) AS friends
ORDER BY friends DESC
LIMIT 10

Output:

+----------------------------------+----------------+
| Operator                         | Estimated Rows |
+----------------------------------+----------------+
| LimitOperator (10)               |             10 |
|   SortOperator (friends DESC)    |            100 |
|     AggregateOperator (count)    |            100 |
|       ExpandOperator (-[:KNOWS]->)|            500 |
|         NodeScanOperator (:Person)|            100 |
+----------------------------------+----------------+

Reading EXPLAIN Output

Key things to look for:

• Operator ordering: Filters should appear as close to the scan as possible (predicate pushdown)
• IndexScan vs. NodeScan: If you have an indexed property in your WHERE clause and see NodeScanOperator instead of IndexScanOperator, the optimizer may lack statistics—run a query first to populate stats
• Estimated Rows: Large drops between operators indicate selective filters. If estimated rows increase at an ExpandOperator, the graph has high fan-out at that relationship type
• Statistics section: Shows the raw data the optimizer used for its decisions

Optimization Techniques Applied

Samyama’s optimizer applies several rule-based and cost-based optimizations:

Future: PROFILE (Runtime Statistics)

Status: Planned — PROFILE is on the roadmap but not yet implemented. Currently, only EXPLAIN is available.

A future PROFILE command would execute the query and collect timing and row-count data for every operator, adding Actual Rows and Time (ms) columns alongside the estimates. This would enable:

• Identifying the actual bottleneck operator (not just estimated)
• Comparing estimated vs. actual cardinality to detect stale statistics
• Measuring late materialization savings at the ProjectOperator

Developer Tip: Use EXPLAIN before running expensive queries. If the plan looks suboptimal, try adding a property index with CREATE INDEX ON :Label(property) and re-run EXPLAIN to see if the optimizer switches to an IndexScanOperator.

Picasso — Plan-Space Visualisation

Picasso is the plan-space visualiser for Samyama Graph. Given a Cypher pattern (or template), it sweeps a parameter or schema dimension, runs EXPLAIN at every grid point, colours each cell by the plan signature the planner chose, and reports a plan-stability score for the sweep.

Picasso ships as a page in samyama-insight at /picasso, backed by the engine’s HTTP EXPLAIN endpoint. No JDBC, no separate tool — it is part of the management UI.

What it answers

• Does the planner change its mind across a selectivity range? A stable plan-diagram means the cost model produces consistent decisions across the parameter space.
• Where are the plan boundaries? Adjacent cells with different signatures expose the selectivity points where the planner flips between strategies.
• How many physical plans does the planner actually consider for this pattern? The “Distinct Plans” metric counts the unique plan signatures observed during the sweep.

Two modes

Graph Pattern Mode

Sweep schema dimensions for a fixed Cypher pattern.

• Inputs: Label, EdgeType, optional second Label.
• Per grid cell, the page sends EXPLAIN MATCH (a:Label1)-[:EdgeType]->(b:Label2) ... and records the plan signature.
• Useful for understanding which label/edge-type combinations the planner treats as “the same plan shape” vs. distinct.

Parameter Sweep Mode

Sweep a numeric range for $param1 (and optionally $param2) in a Cypher template.

• Input: a Cypher template like MATCH (n:Person) WHERE n.age > $param1 RETURN n and a (min, max, step) range.
• 1D sweep produces a line; 2D sweep produces a heatmap.
• Useful for stressing the planner’s selectivity estimation: at low $param1 the predicate is highly selective and IndexScan should fire; at high $param1 it should fall back to NodeScan + filter. The grid makes the transition visible.

Metrics surfaced

Why we did not adopt IISc Picasso

The original Picasso project at IISc (Bangalore) is a JDBC-driven plan-diagram tool for PostgreSQL / Oracle / SQL Server / DB2. It runs a sweep, pulls each EXPLAIN over JDBC, and renders the result.

A JDBC adapter for a RESP/HTTP Rust engine would have meant a multi-week protocol-bridge project. The native alternative — connect the Picasso UI directly to the existing HTTP EXPLAIN endpoint — was simpler, kept the toolchain Rust-end-to-end, and ships every time the management UI ships. So Picasso lives in samyama-insight, talks HTTP, and inherits the planner improvements from each release without a separate integration step.

What’s behind the plan diversity

The planner enumerates up to 64 candidate plans per MATCH via plan_enumerator.rs (ADR-015). For each pattern node it tries that node as the entry point, picks a traversal direction by comparing avg_out_degree vs avg_in_degree from GraphCatalog, and chooses Expand vs ExpandInto based on which endpoints are bound at expansion time. Selectivity-aware predicate pushdown via the IndexManager (ADR-029) further differentiates plans.

So the plan diagram Picasso paints is not a single “this is the only plan” verdict — it’s a window into the cost-driven choice across the candidate space.

Remaining gaps

• Histograms / MCV lists — range and inequality predicates today fall back to default selectivity constants (0.33 and 0.1). Adding equi-depth histograms would tighten the cost-driven plan choice and make Picasso’s reduction-factor analysis (the ratio of chosen-plan-cost to cheapest-plan-cost) meaningful.
• Cost-vs-actual annotations — PROFILE produces actual row counts per operator; the Picasso grid does not yet overlay that delta on the plan diagram.
• 3D cost surface — the classic IISc Picasso renders a 3D surface of estimated cost across selectivity space; the Samyama page surfaces distinct-plan count and stability score but not the cost surface itself.
• Plan-diagram regression tests — there is no test today that asserts “this schema/parameter grid produces exactly N distinct plans”. Worth adding to catch silent planner regressions.

Pointers

• UI: samyama-insight/src/pages/Picasso.tsx
• E2E: samyama-insight/e2e/06-picasso.spec.ts
• Planner: samyama-graph/src/query/executor/plan_enumerator.rs
• ADRs: ADR-015 (graph-native query planning), ADR-017 (adjacency-aware aggregation), ADR-027 (aggregation pushdown), ADR-029 (IndexManager)
• Deeper assessment: samyama-cloud/papers/picasso-assessment.md

Persistence at Scale

Every database must answer a fundamental question: How do we not lose data?

For an in-memory graph database like Samyama, this is doubly critical. While we prioritize speed by keeping the active dataset in RAM, we need a robust, battle-tested persistence layer to ensure durability (the ‘D’ in ACID) and to support datasets larger than memory.

We chose RocksDB.

Why RocksDB?

RocksDB, originally forked from Google’s LevelDB by Facebook, is an embedded key-value store based on a Log-Structured Merge-Tree (LSM-Tree). It is the industry standard for high-performance storage engines, powering systems like CockroachDB, TiKV, and Kafka Streams.

The LSM-Tree Advantage

Graph workloads are write-heavy. Creating a single “relationship” between two nodes might involve updating adjacency lists on both ends, updating indices, and writing to the transaction log.

Traditional B-Tree storage suffers from Write Amplification—changing a few bytes can require rewriting entire 4KB or 8KB pages.

LSM-Trees solve this by turning random writes into sequential ones. Here is how Samyama flows data into RocksDB:

graph TD
    Client[Client Write Request] --> WAL[(Write-Ahead Log)]
    WAL --> MemTable[In-Memory MemTable]
    MemTable -- "Flushes when full (64MB)" --> L0[SSTable Level 0]
    L0 -- "Background Compaction" --> L1[SSTable Level 1]
    L1 -- "Background Compaction" --> L2[SSTable Level 2]
    
    style WAL fill:#f9f,stroke:#333,stroke-width:2px
    style MemTable fill:#bbf,stroke:#333,stroke-width:2px
    style L0 fill:#dfd,stroke:#333
    style L1 fill:#dfd,stroke:#333
    style L2 fill:#dfd,stroke:#333

This architecture allows Samyama to sustain massive ingestion rates, as seen in benches/full_benchmark.rs where we achieve over 250,000 nodes/second (CPU) and over 400,000 nodes/second (GPU-accelerated) in raw write throughput.

Schema Design: Mapping Graphs to Key-Value

How do you store a graph (nodes and edges) in a Key-Value store? We use Column Families (logical partitions within RocksDB) to separate different types of data, preventing them from slowing each other down during compaction.

graph LR
    DB[(RocksDB Instance)]
    DB --> CF_Default["CF: default <br> Metadata & Versioning"]
    DB --> CF_Nodes["CF: nodes <br> NodeId -> StoredNode"]
    DB --> CF_Edges["CF: edges <br> EdgeId -> StoredEdge"]
    DB --> CF_Indices["CF: indices <br> B-Tree Property Indices"]

Key Structure

We use a simple, efficient binary encoding for keys. All IDs are u64 integers.

• Node Key: [u8; 8] -> Big-Endian representation of NodeId.
• Edge Key: [u8; 8] -> Big-Endian representation of EdgeId.

Value Serialization

For the values (the actual data), we need a format that is compact and fast to deserialize. We chose Bincode.

Bincode is a Rust-specific binary serialization format that effectively dumps the memory representation of a struct to disk. It is significantly faster than JSON, Protobuf, or MsgPack for Rust-to-Rust communication.

#![allow(unused)]
fn main() {
#[derive(Serialize, Deserialize)]
struct StoredNode {
    id: u64,
    labels: Vec<String>,
    properties: Vec<u8>, // Compressed property map
    created_at: i64,
    updated_at: i64,
}
}

The Persistence Code

The integration lives in src/persistence/storage.rs. Here is a simplified view of how we initialize RocksDB with optimal settings for graph workloads:

#![allow(unused)]
fn main() {
pub fn open(path: impl AsRef<Path>) -> StorageResult<Self> {
    let mut opts = Options::default();
    opts.create_if_missing(true);
    
    // Performance Tuning
    opts.set_write_buffer_size(64 * 1024 * 1024); // 64MB batches
    opts.set_compression_type(rocksdb::DBCompressionType::Lz4);

    let cf_descriptors = vec![
        ColumnFamilyDescriptor::new("default", Options::default()),
        ColumnFamilyDescriptor::new("nodes", Self::node_cf_options()),
        ColumnFamilyDescriptor::new("edges", Self::edge_cf_options()),
        ColumnFamilyDescriptor::new("indices", Self::index_cf_options()),
    ];

    let db = DB::open_cf_descriptors(&opts, &path, cf_descriptors)?;
    Ok(Self { db: Arc::new(db), /* ... */ })
}
}

Developer Tip: Check out examples/persistence_demo.rs to see a full working example of how to configure Samyama to persist data to disk, write millions of edges, shut down the server, and seamlessly recover state on the next boot.

Durability vs. Performance

We allow users to configure the sync behavior.

• Strict Mode: Every write calls fsync, guaranteeing data is on disk. Slower but safest.
• Background Mode: Writes are acknowledged once in the OS buffer cache. Faster, but risks data loss on power failure (process crash is still safe).

In Samyama, we default to a balanced approach: the Raft log (for consensus) is always fsync’d, while the RocksDB state machine catches up asynchronously. This ensures cluster-wide consistency even if a single node fails.

Managing State (MVCC & Memory)

In a high-performance database, “State” is the enemy of speed. Managing it requires locks, and locks kill concurrency.

If User A is reading a graph to compute a shortest path between two cities, and User B updates a road in the middle of that calculation, what should happen?

1. Locking: User B waits until User A finishes. Safe but slow.
2. Dirty Read: User A sees the half-updated state and crashes. Fast but broken.
3. MVCC: User A sees the old version of the road, while User B writes the new version. Both proceed in parallel.

Samyama implements Multi-Version Concurrency Control (MVCC) with cache-friendly, arena-style storage for nodes and copy-on-write semantics for edges, giving lock-free reads under concurrent writes.

The data model

GraphStore (in src/graph/store.rs) is the single authority for graph state. Two design choices shape everything else:

• The ID is the index. A NodeId is a direct u64 index into the node arena — not a hash key, not a UUID. NodeId(5) means “slot 5”. This is O(1) without hashing and keeps adjacency walks contiguous in memory.
• Topology is separated from properties. The arena holds the structural skeleton (id, label, version chain); property values live in column-oriented storage (ColumnStore) keyed by id. Traversals can scan adjacency lists for millions of edges without ever touching property bytes.

graph TD
    subgraph "GraphStore"
        Nodes["nodes: NodeArena<br/>(versioned slots)"]
        EdgeStore["edge store<br/>(COW, EdgeView)"]
        Outgoing["outgoing: Vec&lt;Vec&lt;EdgeId&gt;&gt;"]
        Incoming["incoming: Vec&lt;Vec&lt;EdgeId&gt;&gt;"]
        NodeCols["node_columns: ColumnStore"]
        EdgeCols["edge_columns: ColumnStore"]
    end

    subgraph "Node version chain"
        V1["v1 (old)"] --> V2["v2"]
        V2 --> V3["v3 (latest)"]
    end

    Nodes -.-> V1

Snapshot Isolation for reads

Each node slot keeps a short version chain. When a query begins, it captures the current MVCC version Vq. To read a node, the engine walks the chain backward until it finds the newest version ≤ Vq. No locks. No coordination with writers. Reads at any concurrency level cost a vector indirection plus a tiny linear scan over recent versions.

Edges follow a complementary pattern: the engine no longer keeps a per-edge in-memory arena. Edges are addressed through EdgeView — a lightweight handle that resolves endpoints and properties on demand from columnar storage and the node-side adjacency lists. Edge updates use copy-on-write: an in-flight update produces a new view; readers continue to see the old one until they advance to a fresh snapshot.

The combination — versioned node arena plus COW edges — keeps steady-state memory close to the data’s information-theoretic minimum and makes reads cache-friendly even under sustained write load.

Isolation levels and write-write conflicts

BEGIN ... COMMIT transactions support two isolation levels:

• Read Committed — each statement sees the latest committed state at statement start. Cheap and the right default for write-heavy workloads.
• Snapshot Isolation — the entire transaction sees the snapshot taken at BEGIN. Concurrent writers to the same node or edge are detected at commit time; the later committer aborts with a write-write conflict and can retry.

Long-running readers don’t block writers and writers don’t block readers; the only synchronization is the conflict check at commit, which touches just the keys that the transaction wrote.

Version GC

Old versions don’t accumulate forever. A background reclaimer drops node versions older than the oldest live snapshot, and the WAL itself is versioned so log replay can reconstruct the right state on restart. The result is bounded memory regardless of write rate.

Columnar properties

graph LR
    subgraph "ColumnStore (per label)"
        Age["age: Vec<i64>"]
        Name["name: Vec<String>"]
        Salary["salary: Vec<f64>"]
    end

    Query[Query Engine] -- "SIMD aggregation" --> Age
    Query -- "Late materialization" --> Name

Property columns are stored once per label, indexed by node id. The query engine reads them only when the user explicitly references them in WHERE or RETURN. The same column layout supports SIMD-friendly aggregation paths (SUM, AVG, COUNT(*) WHERE ...) without per-row dispatch.

Statistics for the optimizer

GraphStore maintains label counts, edge-type counts, and per-property statistics (null fraction, distinct count, selectivity). The cost-based planner consults these to choose join orders, pick between adjacency walks and edge scans, and decide whether to use an index. See Query Optimization for how the planner uses them.

ACID guarantees

CAP trade-off

Samyama’s Raft-based clustering chooses CP — consistency and partition tolerance:

• During a network partition, the minority partition refuses writes.
• Reads from the majority partition remain consistent.
• Availability is sacrificed during partitions in favor of correctness.

Analytical Power (CSR & Algorithms)

Transactional queries (OLTP) usually touch a small subgraph: “Find Alice’s friends.” Analytical queries (OLAP) touch the entire graph: “Rank every webpage by importance (PageRank).”

The pointer-chasing structure of a standard graph database (Adjacency Lists) is excellent for OLTP but suboptimal for OLAP due to cache misses.

Samyama solves this by introducing a dedicated Analytics Engine in the samyama-graph-algorithms crate. This crate is decoupled from the core storage engine, allowing it to iterate independently and even be used as a standalone library.

The CSR (Compressed Sparse Row) Format

When you run an algorithm like PageRank or Weakly Connected Components, Samyama doesn’t run it directly on the GraphStore. Instead, it “projects” the relevant subgraph into a highly optimized read-only structure called CSR.

A Graph $G=(V, E)$ in CSR format is represented by three contiguous arrays:

1. out_offsets: Indices indicating where each node’s neighbor list starts in the out_targets array.
2. out_targets: A massive, flat array containing all neighbor NodeIds.
3. weights: (Optional) Edge weights corresponding to the out_targets list.

#![allow(unused)]
fn main() {
pub struct GraphView {
    pub out_offsets: Vec<usize>,
    pub out_targets: Vec<NodeId>,
    pub weights: Vec<f32>,
}
}

graph LR
    subgraph "GraphStore (OLTP)"
        AdjList["Adjacency Lists<br>Vec of Vec of EdgeId"]
        Props["Property Maps<br>HashMap per Node"]
    end

    Project["Project to CSR<br>(read-only snapshot)"]

    subgraph "GraphView (OLAP)"
        Offsets["out_offsets: [0, 2, 5, 7, ...]"]
        Targets["out_targets: [1, 3, 0, 2, 4, 1, 3, ...]"]
        Weights["weights: [1.0, 0.5, 1.0, ...]"]
    end

    AdjList --> Project --> Offsets
    Project --> Targets
    Project --> Weights

Why CSR?

• Memory Efficiency: CSR eliminates the memory overhead of adjacency lists (which are Vec<Vec<EdgeId>> in the core engine).
• Sequential Memory Access: Iterating through a node’s neighbors becomes a simple sequential scan of the out_targets array, which the CPU can prefetch with nearly 100% accuracy.
• Zero-Lock Parallelism: Since the CSR structure is immutable once built, algorithms can scale across all available CPU cores using Rayon without a single mutex or atomic lock.

The Algorithm Library (samyama-graph-algorithms)

The samyama-graph-algorithms crate includes an extensive range of graph analytical operations. Every algorithm accesses the graph through the GraphView representation (CSR Format).

Supported algorithms currently include:

1. Centrality & Importance:

   • pagerank: Global node importance ranking.
   • lcc (Local Clustering Coefficient): Measuring “tight-knitness” around individual nodes.

2. Community Detection & Connectivity:

   • weakly_connected_components (WCC): Identifying isolated clusters ignoring edge direction.
   • strongly_connected_components (SCC): Finding subgraphs where every node is mutually reachable.
   • cdlp (Community Detection via Label Propagation): Discovering overlapping and non-overlapping dense networks.
   • count_triangles: Analyzing social cohesion.

3. Pathfinding & Network Flow:

   • bfs: Breadth-first traversal.
   • dijkstra: Finding shortest paths with edge weights.
   • bfs_all_shortest_paths: Resolving every potential path of minimum distance between entities.
   • edmonds_karp: Calculating the absolute maximum flow rate between a source and a sink node.
   • prim_mst: Determining the Minimum Spanning Tree of the graph.

4. Statistical & Dimensionality Reduction:

   • pca (Principal Component Analysis): Reduces high-dimensional node features to their principal components. Supports two solvers:
     • Randomized SVD (default): Uses the Halko-Martinsson-Tropp algorithm for efficient dimensionality reduction on large datasets. Automatically selected when n > 500.
     • Power Iteration (legacy): Deflation-based eigenvector computation with Gram-Schmidt re-orthogonalization.

PCA Configuration

#![allow(unused)]
fn main() {
pub struct PcaConfig {
    pub n_components: usize,      // Number of components (default: 2)
    pub max_iterations: usize,    // For Power Iteration only (default: 100)
    pub tolerance: f64,           // Convergence threshold (default: 1e-6)
    pub center: bool,             // Subtract column means (default: true)
    pub scale: bool,              // Divide by std dev (default: false)
    pub solver: PcaSolver,        // Auto, Randomized, or PowerIteration
}
}

The PcaResult includes principal components, explained variance ratios, and transform() / transform_one() methods for projecting new data points.

Enterprise Note: GPU-accelerated PCA is available in Samyama Enterprise for datasets exceeding 50,000 nodes (see the Enterprise Edition chapter).

SDK Integration

The same CSR-based algorithms are accessible through the Samyama SDK ecosystem. The Rust SDK’s AlgorithmClient trait provides direct method access, while the Python and TypeScript SDKs execute algorithms via Cypher queries.

from samyama import SamyamaClient

# Embedded mode: algorithms run in-process at Rust speeds
client = SamyamaClient.embedded()

# Execute PageRank via Cypher
result = client.query("""
    MATCH (n:Person)-[:KNOWS]->(m:Person)
    RETURN n.name, n.pagerank
""")

Note: The Rust SDK’s AlgorithmClient provides direct Rust API access to all algorithms (e.g., client.page_rank(config, "Person", "KNOWS")) without going through Cypher. See the SDKs, CLI & API chapter for details.

This architecture allows Samyama to replace dedicated graph analytics frameworks like NetworkX (which is slow) or GraphFrames (which requires Spark), providing a single engine for storage and analysis.

In-Database Optimization (Metaheuristics)

Most graph databases stop at “Retrieval.” They help you find data. Samyama goes a step further into Prescription.

By integrating a suite of highly concurrent metaheuristic solvers directly into the engine via the samyama-optimization crate, we allow users to solve complex Operation Research (OR) problems where the graph is the model.

Supported Solvers

Unlike exact solvers (like CPLEX), metaheuristics are nature-inspired algorithms that search for “good enough” solutions in massive, complex search spaces. The samyama-optimization crate implements an exhaustive list of state-of-the-art algorithms:

• Metaphor-less: Jaya, QOJAYA (Quasi-Oppositional), RAO (Variants 1, 2, 3), TLBO (Teaching-Learning), ITLBO (Improved TLBO), GOTLBO.
• Swarm & Evolutionary: PSO (Particle Swarm), DE (Differential Evolution), GA (Genetic Algorithms), GWO (Grey Wolf Optimizer), ABC (Artificial Bee Colony), BAT, Cuckoo, Firefly, GSA (Gravitational Search), FPA (Flower Pollination Algorithm).
• Physics-based & Other: SA (Simulated Annealing), HS (Harmony Search), BMR, BWR.
• Multi-Objective: NSGA-II and MOTLBO for determining Pareto frontiers when solving problems with conflicting goals (e.g., “Minimize Cost” vs. “Maximize Safety”).

The Graph-to-Optimization Bridge

Samyama allows you to define an optimization problem directly using Cypher. The database seamlessly maps node properties to decision variables and edges to constraints.

// Example: Optimize Factory production using Particle Swarm Optimization
CALL algo.or.solve({
  algorithm: 'PSO',
  label: 'Factory',
  property: 'production_rate',
  min: 10.0,
  max: 100.0,
  cost_property: 'unit_cost',
  budget: 50000.0,
  population_size: 50,
  iterations: 200
}) 
YIELD fitness, variables

Developer Tip: You can explore the raw performance of these native solvers by running the optimization benchmarks: cargo bench --bench graph_optimization_benchmark. This benchmarks algorithms like PSO and Jaya running concurrently via Rayon.

Solver Convergence

All solvers follow a common iterative pattern: initialize a population, evaluate fitness, evolve, and converge:

graph TD
    Init["Initialize Population<br>(random candidates)"] --> Eval["Evaluate Fitness<br>(against graph properties)"]
    Eval --> Converge{"Converged?<br>OR max iterations?"}
    Converge -- "No" --> Evolve["Evolve Population<br>(algorithm-specific rules)"]
    Evolve --> Eval
    Converge -- "Yes" --> Result["Return Best Solution<br>(YIELD fitness, variables)"]

Each algorithm differs in the “Evolve” step: PSO uses velocity vectors, GWO uses wolf hierarchy, Jaya uses best/worst comparisons, and NSGA-II uses non-dominated sorting with crowding distance.

Parallel Evolution: The Power of Rust

Metaheuristic algorithms are computationally intensive as they evaluate entire populations of candidate solutions. Samyama’s engine handles this at the Rust level:

• Rayon Integration: Evaluates all candidate solutions in a population in parallel across all CPU cores.
• SIMD Fitness: Calculates the “fitness” of multiple solutions simultaneously.
• Zero-Copy Execution: Solutions are directly evaluated against the in-memory GraphStore structures without intermediate mapping.

This unique integration makes Samyama the ideal choice for Smart Manufacturing, Logistics, and Healthcare Management.

Constrained Multi-Objective Optimization

The samyama-optimization crate (included in the open-source Community Edition) provides full support for multi-objective optimization, including NSGA-II and MOTLBO with the Constrained Dominance Principle for handling complex real-world constraints.

Note: All 22 metaheuristic solvers—including the multi-objective solvers NSGA-II and MOTLBO—are available in the OSS edition. The Enterprise edition adds GPU-accelerated constraint evaluation for large-scale problems.

The Reality of Constraints

In academic problems, objectives like “Minimize Cost” and “Maximize Quality” are often explored in a vacuum. In industry, these objectives must be solved while adhering to hard physical or regulatory constraints:

• Supply Chain: Minimize lead time AND maximize profit, but total warehouse volume cannot exceed 5,000m³.
• Energy: Maximize grid stability AND minimize carbon output, but no single plant can operate at >95% capacity for more than 4 hours.

Constrained Dominance Principle

The samyama-optimization crate implements this principle in the NSGA-II and MOTLBO solvers. Instead of a simple “penalty” approach (which often struggles to find feasible solutions in tight spaces), the selection logic follows a strict hierarchy:

graph TD
    Compare["Compare Solution A vs B"] --> FeasCheck{"Both<br>Feasible?"}

    FeasCheck -- "Yes" --> Pareto["Standard Pareto<br>Dominance"]
    FeasCheck -- "No" --> MixCheck{"One Feasible,<br>One Not?"}

    MixCheck -- "Yes" --> FeasWins["Feasible Solution<br>Always Wins"]
    MixCheck -- "No (both infeasible)" --> Violation["Lower Total<br>Constraint Violation Wins"]

    Pareto --> Select["Selected for<br>Next Generation"]
    FeasWins --> Select
    Violation --> Select

1. Feasibility First: A solution that satisfies all constraints is always preferred over one that violates any constraint.
2. Comparative Violation: Between two infeasible solutions, the one with the lower total constraint violation is preferred.
3. Standard Dominance: Between two feasible solutions, standard Pareto dominance rules apply.

Defining Constraints in Cypher

The algo.or.solve procedure allows for explicit constraint definitions:

CALL algo.or.solve({
  algorithm: 'NSGA2',
  label: 'Generator',
  objectives: ['cost', 'emissions'],
  constraints: [
    { property: 'load', max: 500.0 },
    { property: 'temperature', max: 100.0 }
  ],
  population_size: 100
})
YIELD pareto_front

This advanced logic ensures that the “Pareto Front” returned by the solver contains solutions that are not only optimal but also physically executable, making Samyama a powerful tool for industrial decision-making.

Technology Choices (The “Why”)

Building a database is an exercise in trade-offs. In this chapter, we explore the specific technology choices that define Samyama and why we chose them over popular alternatives.

Rust vs. The World

Why not C++? Why not Go?

As documented in our internal benchmarks, Rust provides a unique combination of Memory Safety and Zero-Cost Abstractions.

The Performance Gap

In a pure graph traversal benchmark on 1 million nodes (execution only, excluding parse/plan overhead):

• Rust: 12ms (with 450MB RAM)
• Go: 45ms (with 850MB RAM + GC Pauses)
• Java: 38ms (with 1200MB RAM + GC Pauses)

Note: These numbers measure raw traversal execution time. End-to-end Cypher query latency (including parsing and planning) is higher—see the Performance & Benchmarks chapter for full breakdowns.

The “Cautionary Tale of InfluxDB” served as a warning to us. Originally written in Go, the InfluxDB team eventually rewrote their core query engine in Rust to eliminate unpredictable garbage collection pauses that were impacting P99 latencies. We chose to start with Rust to avoid that “technical debt” from day one.

RocksDB vs. B-Trees

We chose an LSM-Tree (RocksDB) over a B-Tree (LMDB).

Graph workloads are naturally write-heavy—every relationship creation involves multiple index updates. B-Trees suffer from “Write Amplification,” where changing a few bytes requires rewriting entire pages. RocksDB turns these random writes into sequential appends, allowing Samyama to sustain over 255,000 node writes per second (CPU) and over 412,000 node writes per second (GPU-accelerated), significantly outperforming LMDB in write-heavy scenarios.

Optimized Serialization: Bincode

Traditional serialization formats like JSON or Protobuf introduce significant overhead. For a performance-first database like Samyama, we needed a format that could serialize and deserialize data with minimal CPU cycles.

We chose Bincode.

Bincode is a compact, binary serialization format specifically optimized for Rust-to-Rust communication. It effectively takes the memory layout of a Rust struct and dumps it to disk.

• Speed: Deserializing a StoredNode from RocksDB takes nanoseconds.
• Compactness: No field names or metadata overhead; only the raw values are stored.
• Safety: Integrated with serde, it ensures that even if the disk format is corrupted, the database won’t crash on invalid memory access.

Mechanical Sympathy: Custom Columnar Storage

For property-heavy analytical queries, even Bincode is too slow because it still requires “hydrating” a full node object. To solve this, Samyama uses a custom Columnar Property Storage for high-performance property access.

By storing properties in a columnar format (e.g., all “ages” together), we achieve Mechanical Sympathy:

1. Cache Locality: The CPU can prefetch thousands of values at once into the L1 cache.
2. SIMD-Friendly Layout: The columnar layout is designed to be SIMD-friendly, enabling auto-vectorization by the Rust compiler and future integration with explicit SIMD intrinsics.
3. Late Materialization: We avoid fetching properties from disk until the very last stage of a query, reducing I/O and CPU overhead by orders of magnitude.

Hardware Acceleration: Why wgpu?

When deciding how to add GPU acceleration to Samyama, we evaluated several options including CUDA, OpenCL, and Vulkan. We ultimately chose wgpu, the Rust implementation of the WebGPU API.

The Portability Advantage

Unlike CUDA (limited to NVIDIA) or OpenCL (which can be temperamental across platforms), wgpu offers a common abstraction layer that targets the most performant native API of the host system:

• Metal on macOS and iOS.
• Vulkan on Linux and Android.
• DirectX 12 on Windows.

Native Performance with WGSL

By writing our compute shaders in WGSL (WebGPU Shading Language), we can offload intensive graph algorithms like PageRank and community detection to the GPU’s thousands of cores. This allows Samyama to remain “Hardware Agnostic” while still delivering hardware-native performance on any modern cloud instance or local machine with a GPU.

Samyama vs. The Giants: A Comparison

How does Samyama compare to industry leaders like Neo4j (the veteran) and FalkorDB (the high-performance alternative, formerly RedisGraph)?

Why Samyama Wins on Modern Hardware

• Neo4j suffers from the “GC Tax”—large heaps lead to long garbage collection pauses. Its pointer-heavy structure is also prone to cache misses during multi-hop traversals.
• FalkorDB (formerly RedisGraph, which was deprecated in 2023) is fast but its dependence on GraphBLAS (Matrix Math) makes it less flexible for complex property-based Cypher queries. It also lacks native AI/Vector capabilities.
• Samyama represents a “Third Way”: The flexibility of a property graph, the speed of native Rust, and the analytical power of a dedicated CSR-based engine. By focusing on Mechanical Sympathy (aligning with CPU cache lines), Samyama delivers 10x the performance with 1/4 the memory footprint of traditional engines.

Distributed Consensus & Sharding

A single node can only go so far. To scale beyond a single machine’s memory and CPU, Samyama employs a distributed architecture built on the Raft consensus algorithm.

Consistency via Raft

We use the openraft crate, a modern, asynchronous implementation of the Raft protocol.

Raft provides Strong Consistency by ensuring that a cluster of nodes agrees on the order of operations (the Log) before applying them to the state machine (the Graph).

The Raft Cluster Architecture

sequenceDiagram
    participant Client
    participant Leader
    participant Follower1
    participant Follower2

    Client->>Leader: "Write: CREATE (n:Node)"
    Leader->>Leader: "Append to Local Log"
    Leader->>Follower1: "AppendEntries RPC"
    Leader->>Follower2: "AppendEntries RPC"
    
    Follower1-->>Leader: "Ack (Log Appended)"
    
    Note over Leader: "Quorum Reached (2/3)"
    
    Leader->>Leader: "Commit to GraphStore"
    Leader-->>Client: "OK"
    
    Follower2-->>Leader: "Ack (Log Appended)"
    Leader->>Follower1: "Commit RPC (Async)"
    Leader->>Follower2: "Commit RPC (Async)"

The Raft Loop

1. Leader Election: Nodes elect a Leader.
2. Log Replication: All write requests go to the Leader. The Leader appends the request to its log and sends it to Followers.
3. Commit: Once a majority (Quorum) acknowledges the log entry, the Leader commits it.
4. Apply: The committed entry is applied to the GraphStore.

This ensures that if a client receives an “OK” response, the data is durable on at least $N/2 + 1$ nodes.

Developer Tip: You can run a fully functional 3-node in-memory cluster locally to observe Leader Election and Log Replication by running cargo run --example cluster_demo.

Sharding Strategy

Samyama implements Tenant-Level Sharding.

In a multi-tenant environment (e.g., a SaaS platform serving many companies), data from different tenants is naturally isolated.

• Shard: A logical partition of the data.
• Routing: The Router component (src/sharding/router.rs) maps a TenantId to a specific Raft Cluster (Shard).

#![allow(unused)]
fn main() {
// Simplified Routing Logic
pub fn route(&self, tenant_id: &str) -> ClusterId {
    let hash = seahash::hash(tenant_id.as_bytes());
    hash % self.num_shards
}
}

This approach avoids the complexity of distributed graph partitioning (cutting edges across machines) while offering infinite horizontal scale for multi-tenant workloads.

Failure Modes & Recovery

Raft provides well-defined behavior for common failure scenarios:

See also: The Production-Grade High Availability chapter for Enterprise-specific hardening (HTTP/2 transport, snapshot streaming, cluster metrics).

Future: Graph Partitioning

For single-tenant graphs that exceed one machine, we are researching “Graph-Aware Partitioning” using METIS, but for now, Tenant Sharding is the production-ready strategy.

Production-Grade High Availability

Building a distributed consensus cluster that works in a controlled environment is easy. Building one that survives network partitions, flapping connections, and storage corruption in a production data center is much harder.

Samyama Enterprise builds upon the core Raft implementation with several production-hardened enhancements.

Hardened Network Transport

While the OSS version uses a simulated or basic TCP transport, Enterprise implements a high-performance HTTP/2 based RPC layer (via Axum and Hyper).

• Encryption: All inter-node traffic is encrypted with TLS by default, ensuring that data replicated across the cluster is safe from interception.
• Multiplexing: HTTP/2 allows multiple concurrent Raft messages (heartbeats, append entries, votes) to share a single connection, significantly reducing latency and overhead.
• Keep-Alive: Intelligent probing detects “silent” network failures faster, triggering leader re-election before the application layer experiences a timeout.

Robust Snapshot Synchronization

In a large cluster, a node that has been offline for a long time cannot catch up by replaying millions of individual log entries. It needs a Snapshot.

Samyama Enterprise automates the entire snapshot lifecycle:

graph LR
    subgraph "Leader"
        L1["1. Generate Snapshot<br>(RocksDB + GraphStore)"]
        L2["2. Compress (LZ4)"]
        L3["3. Stream Chunks<br>(HTTP/2 chunked transfer)"]
    end

    subgraph "Lagging Follower"
        F1["4. Receive Chunks"]
        F2["5. Verify Checksum"]
        F3["6. Atomic Install<br>(replace old state)"]
        F4["7. Resume Log<br>Replication"]
    end

    L1 --> L2 --> L3 --> F1 --> F2 --> F3 --> F4

1. Generation: The Leader creates a consistent point-in-time image of the GraphStore and RocksDB.
2. Streaming: The snapshot is compressed and streamed to the lagging Follower using a chunked transfer protocol to avoid memory spikes.
3. Atomic Installation: The Follower installs the snapshot atomically, replacing its old state only after verifying the snapshot’s checksum.

Cluster Metrics & Health

Maintaining a healthy Raft cluster requires deep visibility into node roles and replication lag. Enterprise exports specific metrics for each node:

• raft_role: Is this node a Leader, Follower, or Candidate?
• raft_term: The current logical clock value.
• raft_replication_lag: The distance (in sequence numbers) between the Leader’s log and this node’s log.

By monitoring these metrics, SREs can proactively identify lagging nodes or cluster instability before they impact service availability.

AI & Vector Search

The “Vector Database” hype train has led to many specialized tools (Pinecone, Weaviate). But a vector is just a property of a node. Separating vectors from the graph creates data silos.

Samyama treats Vectors as First-Class Citizens.

The HNSW Index & VectorIndexManager

We use the Hierarchical Navigable Small World (HNSW) algorithm (via the hnsw_rs crate) to index high-dimensional vectors. In Samyama, this is orchestrated by the VectorIndexManager defined in src/vector/manager.rs.

• Storage: Vectors are stored persistently via ColumnStore or a dedicated RocksDB column family.
• Indexing: The HNSW graph (VectorIndex) is maintained in memory for millisecond-speed nearest neighbor search.

#![allow(unused)]
fn main() {
pub struct VectorIndex {
    dimensions: usize,
    metric: DistanceMetric, // Cosine, L2, or DotProduct
    hnsw: Hnsw<'static, f32, CosineDistance>,
}
}

The system natively supports multiple distance metrics out-of-the-box (Cosine, L2, DotProduct) depending on the embedding model used, automatically matching the metric type to the specific index (IndexKey).

Developer Tip: See benches/vector_benchmark.rs to observe how Samyama achieves over 15,000 queries per second (QPS) for 128-dimensional Cosine distance searches on commodity hardware.

Graph RAG (Retrieval Augmented Generation)

The true power of Samyama comes from combining Vector Search with Graph Traversal in a single query.

Scenario: You want to find legal precedents that are semantically similar to a case file AND cited by a specific judge.

If using a pure Vector DB:

1. Query Vector DB -> Get top 100 docs.
2. Filter in application -> Keep only those cited by Judge X.
3. Problem: You might filter out all 100 docs!

The Samyama Graph RAG Architecture

graph TD
    Query["Query Vector: 'Breach of Contract'"] --> HNSW[HNSW Vector Index]
    HNSW -- "Returns Top K NodeIds (Pre-filtering)" --> Engine[Query Engine]
    
    Engine -- "Traverse Outgoing Edges" --> Adjacency[GraphStore Adjacency List]
    Adjacency -- "Filter by Label/Property" --> Filter["Judge = 'Scalia'"]
    
    Filter -- "Yield Results" --> LLM[LLM Context Window]

Samyama achieves this efficiently using the VectorSearchOperator intertwined with standard graph operators:

// 1. Vector Search finds the entry points
CALL db.index.vector.queryNodes('Precedent', 'embedding', $query_vector, 100)
YIELD node, score

// 2. Graph Pattern filters them immediately
MATCH (node)<-[:CITED]-(j:Judge {name: 'Scalia'})

// 3. Return best matches
RETURN node.summary, score
ORDER BY score DESC LIMIT 5

This “Pre-filtering” happens directly inside the execution engine, minimizing memory transfers and enabling highly efficient Retrieval-Augmented Generation workflows.

Embedding Providers

Samyama stores and indexes vectors — but generating them (turning text, images, or other data into vectors) is a separate concern. The database is intentionally embedding-model-agnostic: you choose the provider that fits your stack.

Provider Options

Why Mock is the Default

Samyama ships with a Mock embedding provider that generates random vectors. This is deliberate:

• Zero dependencies: No model downloads, no Python, no GPU drivers
• Fast CI: Tests and benchmarks run without external services
• Small binary: No +30MB ONNX Runtime or ML framework bundled
• Your choice: Embedding models evolve fast — we don’t lock you in

For production, you bring your own embeddings. The database doesn’t care how the vectors were generated — it indexes and searches them the same way.

Python SDK with sentence-transformers

The most common path for Python applications. Install sentence-transformers alongside the Samyama Python SDK:

pip install samyama sentence-transformers

from samyama import SamyamaClient
from sentence_transformers import SentenceTransformer

# Load embedding model (downloads ~80MB on first run)
model = SentenceTransformer("all-MiniLM-L6-v2")  # 384 dimensions

client = SamyamaClient.embedded()

# Create vector index
client.create_vector_index("Document", "embedding", 384, "cosine")

# Generate and store embeddings
texts = ["Graph databases unify structure and search",
         "Knowledge graphs power industrial operations"]
embeddings = model.encode(texts)

for i, emb in enumerate(embeddings):
    node_id = client.query("default",
        f"CREATE (d:Document {{title: '{texts[i]}'}}) RETURN id(d)")[0][0]
    client.add_vector("Document", "embedding", node_id, emb.tolist())

# Semantic search
query_emb = model.encode("How do graph databases work?").tolist()
results = client.vector_search("Document", "embedding", query_emb, 5)
# Returns: [(node_id, distance), ...]

Rust with ONNX Runtime

For Rust applications that need in-process embeddings without Python, use the ort crate with ONNX-exported models:

# Export a sentence-transformers model to ONNX (one-time, requires Python)
python -c "
from optimum.onnxruntime import ORTModelForFeatureExtraction
model = ORTModelForFeatureExtraction.from_pretrained(
    'sentence-transformers/all-MiniLM-L6-v2', export=True)
model.save_pretrained('./model_onnx')
"

#![allow(unused)]
fn main() {
// In your Rust application
use ort::{Session, Value};

let session = Session::builder()?
    .with_model_from_file("model_onnx/model.onnx")?;

// Tokenize and run inference (simplified — real code needs a tokenizer)
let embeddings = session.run(inputs)?;

// Store in Samyama
client.create_vector_index("Document", "embedding", 384, DistanceMetric::Cosine).await?;
client.add_vector("Document", "embedding", node_id, &embedding_vec).await?;
}

HTTP Embedding Providers

Any service that exposes an embedding endpoint works. Generate vectors externally, store them in Samyama:

# OpenAI
curl -s https://api.openai.com/v1/embeddings \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model":"text-embedding-3-small","input":"Graph databases"}' \
  | jq '.data[0].embedding'

# Ollama (local)
curl -s http://localhost:11434/api/embeddings \
  -d '{"model":"nomic-embed-text","prompt":"Graph databases"}' \
  | jq '.embedding'

Then store via Samyama’s HTTP API or SDK. The database is agnostic to the source.

Choosing a Provider

Need real embeddings?
├── Python app? → sentence-transformers (easiest, best model selection)
├── Rust app?   → ort crate + ONNX model (fastest, no Python dep)
├── Any language, cloud OK? → OpenAI API (simplest, pay-per-use)
├── Any language, local/private? → Ollama (free, runs anywhere)
└── Just testing? → Mock (default, zero setup)

See also: The Agentic Enrichment chapter for how vector search powers autonomous knowledge graph expansion, and the SDKs, CLI & API chapter for the VectorClient API.

Agentic Enrichment

Traditional databases are passive. They store what you give them. If you ask a question and the data isn’t there, you get an empty result.

Samyama introduces Agentic Enrichment—a paradigm shift where the database becomes an active participant in building its own knowledge.

From RAG to GAK

We are all familiar with Retrieval-Augmented Generation (RAG): using a database to help an LLM. Samyama implements Generation-Augmented Knowledge (GAK): using an LLM to help build the database.

The Autonomous Enrichment Loop

Samyama can be configured with Enrichment Policies via AgentConfig. When a new node is created or a specific property is queried, an autonomous agent (managed by AgentRuntime) can “wake up” to fill in the gaps.

sequenceDiagram
    participant User
    participant Engine as Query Engine
    participant Agent as AgentRuntime
    participant LLM as LLM Provider
    participant Web as Web Search

    User->>Engine: "CREATE (d:Drug {name: 'Semaglutide'})"
    Engine->>Engine: Node created
    Engine->>Agent: Event Trigger fires

    Agent->>LLM: "Find clinical trials for Semaglutide"
    LLM->>Agent: Tool call - WebSearchTool

    Agent->>Web: Search "Semaglutide clinical trials"
    Web-->>Agent: Unstructured results

    Agent->>LLM: "Parse results into structured JSON"
    LLM-->>Agent: JSON entities + relationships

    Agent->>Engine: "CREATE (t:Trial {...})-[:STUDIES]->(d)"
    Engine-->>User: Graph enriched automatically

The Runtime Architecture

Inside the engine, the agent loop is implemented in src/agent/mod.rs using a tool-based architecture.

#![allow(unused)]
fn main() {
pub struct AgentRuntime {
    config: AgentConfig,
    llm_client: Arc<NLQClient>,
    tools: HashMap<String, Box<dyn AgentTool>>,
}

#[async_trait]
pub trait AgentTool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    async fn execute(&self, input: &Value) -> Result<Value, AgentError>;
}
}

Example: The Research Assistant

Imagine you are building a medical knowledge graph. You create a node for a new drug, Semaglutide.

The Passive Way: You manually search PubMed, find papers, and insert them. The Samyama Way:

1. You create the Drug node.
2. An Event Trigger fires an AgentRuntime instance.
3. The Agent uses a WebSearchTool (implementing the AgentTool trait) to find recent clinical trials.
4. The Agent interacts with the LLM via NLQClient to parse the unstructured results into structured JSON.
5. The database automatically executes CREATE commands to link the new papers to the Drug node.

Developer Tip: You can see this GAK paradigm in action by running cargo run --example agentic_enrichment_demo. This demo will automatically reach out to an LLM provider, search the web for missing node properties, and execute the Cypher queries to persist them in the local graph.

Just-In-Time (JIT) Knowledge Graphs

This enables what we call a JIT Knowledge Graph. The graph doesn’t need to be complete on day one. It grows and “heals” itself based on user interaction.

If a user asks: “How does the current Fed interest rate impact my mortgage?” and the Fed Rate node is missing, the database can fetch the live rate, create the node, and then answer the question.

Safety & Validation

Auto-generated Cypher from LLM outputs is validated before execution:

1. Schema Validation: Generated CREATE commands must target known labels and property types
2. Query Safety: The NLQPipeline::is_safe_query() method rejects destructive operations (DELETE, DROP) from agent-generated queries
3. Rate Limiting: The AgentConfig includes limits on enrichment operations per minute to prevent runaway loops
4. Audit Trail: All agent-generated mutations are logged (Enterprise) for traceability

See also: The AI & Vector Search chapter for the underlying HNSW infrastructure, and the SDKs, CLI & API chapter for how to access AgentRuntime via the SDK.

By integrating LLMs directly into the write pipeline, Samyama transforms from a simple storage engine into a dynamic, self-evolving brain.

RDF & SPARQL Support

Samyama provides native support for the Resource Description Framework (RDF) data model alongside its property graph engine. This enables interoperability with Linked Data ecosystems, ontology-based knowledge graphs, and standards-compliant data exchange.

RDF Data Model

RDF represents knowledge as a collection of triples—statements in the form of Subject-Predicate-Object:

<http://example.org/alice> <http://xmlns.com/foaf/0.1/name> "Alice" .
<http://example.org/alice> <http://xmlns.com/foaf/0.1/knows> <http://example.org/bob> .

Core Types

Samyama’s RDF implementation (built on the oxrdf crate) provides the standard RDF term types:

Triple Patterns

For querying, Samyama supports TriplePattern and QuadPattern with optional wildcards:

#![allow(unused)]
fn main() {
// Find all triples where Alice is the subject
let pattern = TriplePattern::new(
    Some(alice.clone().into()),
    None,  // any predicate
    None,  // any object
);
let results = store.query(pattern);
}

In-Memory RDF Store

The RdfStore provides an efficient in-memory triple store with three-way indexing:

graph LR
    subgraph "RdfStore Indices"
        SPO["SPO Index<br>(Subject → Predicate → Object)"]
        POS["POS Index<br>(Predicate → Object → Subject)"]
        OSP["OSP Index<br>(Object → Subject → Predicate)"]
    end

    Query["Triple Pattern"] --> SPO
    Query --> POS
    Query --> OSP

This triple-indexing strategy enables O(1) lookups for any fixed pattern component:

• SPO: Efficient for “What does Alice know?”
• POS: Efficient for “Who has the name ‘Alice’?”
• OSP: Efficient for “What relates to Alice?”

Named graphs are also supported, allowing triples to be organized into logical collections.

Serialization Formats

Samyama supports reading and writing RDF in four standard formats:

Example: Loading Turtle Data

#![allow(unused)]
fn main() {
use samyama::rdf::{RdfParser, RdfFormat, RdfStore};

let turtle_data = r#"
    @prefix foaf: <http://xmlns.com/foaf/0.1/> .
    @prefix ex: <http://example.org/> .

    ex:alice foaf:name "Alice" ;
             foaf:knows ex:bob .
    ex:bob   foaf:name "Bob" .
"#;

let triples = RdfParser::parse(turtle_data, RdfFormat::Turtle)?;
let mut store = RdfStore::new();
for triple in triples {
    store.insert(triple)?;
}
}

Example: Serializing to N-Triples

#![allow(unused)]
fn main() {
use samyama::rdf::{RdfSerializer, RdfFormat};

let output = RdfSerializer::serialize_store(&store, RdfFormat::NTriples)?;
// <http://example.org/alice> <http://xmlns.com/foaf/0.1/name> "Alice" .
// <http://example.org/alice> <http://xmlns.com/foaf/0.1/knows> <http://example.org/bob> .
// <http://example.org/bob> <http://xmlns.com/foaf/0.1/name> "Bob" .
}

Namespace Management

The NamespaceManager provides prefix resolution for compact IRIs, pre-loaded with standard ontologies:

#![allow(unused)]
fn main() {
let ns = NamespaceManager::new();
let expanded = ns.expand("foaf:name");
// → "http://xmlns.com/foaf/0.1/name"
}

SPARQL Query Engine

Status: Foundation — The SPARQL engine infrastructure is in place (parser via spargebra, executor scaffolding, result types), but query execution is not yet fully operational. The current focus is on the property graph / OpenCypher engine.

The SparqlEngine provides the framework for SPARQL 1.1 query processing:

#![allow(unused)]
fn main() {
pub struct SparqlEngine {
    store: RdfStore,
    executor: SparqlExecutor,
}

impl SparqlEngine {
    pub fn query(&self, sparql: &str) -> SparqlResult<SparqlResults>;
    pub fn update(&mut self, sparql: &str) -> SparqlResult<()>;
}
}

Planned Query Forms

Result Formats

SPARQL results support standard serialization formats:

#![allow(unused)]
fn main() {
pub enum ResultFormat {
    Json,   // SPARQL Results JSON
    Xml,    // SPARQL Results XML
    Csv,    // Tabular CSV
    Tsv,    // Tabular TSV
}
}

Property Graph ↔ RDF Mapping

Samyama includes a mapping layer for converting between its native property graph model and RDF:

Note: The bidirectional mapping infrastructure (via MappingConfig) is defined but the automatic conversion is on the roadmap. Currently, RDF data should be loaded directly via the serialization parsers.

Dependencies

The RDF/SPARQL stack uses these Rust crates:

Predictive Power (GNNs)

Status: Planned — The features described in this chapter are on the Samyama roadmap and are not yet implemented. This chapter outlines the design vision for future GNN integration.

While traditional graph algorithms like PageRank tell you about the importance of a node, Graph Neural Networks (GNNs) would allow the database to make predictions about the future.

Samyama’s philosophy on GNNs is clear: Focus on Inference, not Training.

The Problem: Data Gravity

Training a GNN model (using frameworks like PyTorch Geometric or DGL) requires massive compute power and specialized hardware. However, once a model is trained, moving the entire graph to a Python environment every time you need a prediction is slow and expensive. This is “Data Gravity.”

The Planned Solution: In-Database Inference

The planned approach is to implement an inference engine based on ONNX Runtime (ort).

How it will work:

1. Export: Train your GNN in Python (where the data science ecosystem is best) and export it to the standard ONNX format.
2. Upload: Upload the model to Samyama.
3. Execute: Run predictions directly in Cypher queries.

// Future: Predict the fraud risk for a person based on their connections
CALL algo.gnn.predict('fraud_model_v1', 'Person')
YIELD node, score
SET node.fraud_score = score

Planned: GraphSAGE Aggregators

A future addition would be native GraphSAGE-style Aggregators for “Zero-Config” intelligence.

Instead of an external model, these aggregators would leverage the existing Vector Search (HNSW) infrastructure to compute new node embeddings by aggregating the vectors of neighbors (mean, max, or LSTM pooling).

This would allow the database to act as a Dynamic Feature Store, where embeddings are updated in real-time as the graph evolves, providing a predictive layer that most graph databases offer only through external tooling.

Samyama Enterprise Edition

While the Community Edition (OSS) provides the high-performance core engine, the Samyama Enterprise Edition is designed for mission-critical production environments that require hardware acceleration, 24/7 availability, robust data protection, and deep operational visibility.

The Production Gap

Moving a database from a developer’s laptop to a production cluster involves solving three major challenges:

1. Observability: Knowing the health of the system before users complain.
2. Durability: Guaranteeing that data can be recovered even after catastrophic hardware failure.
3. Hardware Acceleration: Utilizing modern GPUs for massive graph analytical workloads.

Feature Matrix

1. Hardware Acceleration (wgpu)

Samyama Enterprise includes hardware-accelerated compute via the samyama-gpu crate. Built on wgpu, it provides cross-platform acceleration (Metal on macOS, Vulkan on Linux, DX12 on Windows).

• GPU Algorithms: PageRank, CDLP (Label Propagation), LCC (Clustering Coefficient), Triangle Counting, and PCA (Principal Component Analysis) are implemented as WGSL compute shaders.
• Vector Distance: Optimized cosine distance and inner product shaders for batch re-ranking after HNSW retrieval.
• Query Operators: Parallel reduction for SUM aggregations and bitonic sort for ORDER BY on large result sets (>10,000 rows).

Mechanical Sympathy Note: The engine uses a MIN_GPU_NODES threshold (default 1,000). For PCA specifically, the threshold is higher (MIN_GPU_PCA = 50,000 nodes and d > 32 dimensions) due to the additional overhead of covariance matrix computation. For smaller subgraphs, the CPU remains faster due to memory transfer overhead. The GPU parallelism dominates once the graph scale exceeds ~100,000 nodes.

GPU PCA Shaders

PCA on the GPU uses five specialized WGSL compute shaders:

1. pca_mean.wgsl: Parallel mean computation across feature columns.
2. pca_center.wgsl: Mean-centering the data matrix.
3. pca_covariance.wgsl: Tiled covariance matrix computation (processes 64 samples per tile for cache efficiency).
4. pca_power_iter.wgsl: Power iteration for eigenvector extraction.
5. pca_power_iter_norm.wgsl: Fused power iteration with in-GPU normalization—computes matrix-vector multiply, parallel reduction for the norm, and normalization in a single dispatch, avoiding costly CPU↔GPU synchronization per iteration.

2. Monitoring & Observability

Enterprise provides a full-stack observability suite:

• Prometheus /metrics: Over 200 real-time counters and histograms (queries/sec, P99 latency, connection counts).
• Health API: JSON-based health status (/api/health) with dedicated Kubernetes liveness/readiness probes.
• Audit Trail: Cryptographically secure logs of every administrative action and data modification for compliance (GDPR, SOC2).

3. Data Protection (Backup & Recovery)

The Enterprise persistence layer (src/persistence/backup.rs) moves beyond the WAL:

• Incremental Backups: WAL-based delta backups minimize storage costs.
• Point-in-Time Recovery (PITR): Restore the database to a specific backup ID, WAL sequence, or microsecond timestamp.
• Retention Policies: Automated cleanup based on backup age or total count.

4. Enhanced High Availability

The Enterprise edition features a production-hardened Raft implementation (+850 lines of code over OSS):

• HTTP Transport: Inter-node communication uses encrypted HTTP/2 (Axum-based) instead of simulated local pipes.
• Snapshot Recovery: Automatically synchronizes lagging nodes by streaming compressed database snapshots.
• Role Tracking: Advanced metrics for leader election, quorum health, and log replication lag.

5. Licensing & Governance

Enterprise features are gated via an Ed25519-signed JET (JSON Enablement Token).

Token Format

base64(header).base64(payload).base64(signature)

The payload contains: id, org, email, edition, features[], max_nodes, max_cluster_nodes, issued_at, expires_at, and machine fingerprint.

License Hardening

The Enterprise licensing system includes multiple layers of protection:

• Grace Period: 30-day operation after license expiry with warning logs. On day 31, enterprise features are disabled but the core engine continues operating.
• Governance: Use ADMIN.TENANTS to monitor per-tenant resource usage and enforce strict memory/storage quotas in multi-tenant environments.

Backup & Disaster Recovery

In an enterprise setting, a database is only as good as its last backup. Samyama Enterprise includes a comprehensive data protection suite that ensures zero data loss and minimal downtime.

Backup Strategies

graph TD
    Strategy["Choose Backup Strategy"] --> Full["Full Snapshot"]
    Strategy --> Incremental["Incremental (WAL Delta)"]
    Strategy --> PITR["Point-in-Time Recovery"]

    Full -- "Complete RocksDB<br>BackupEngine snapshot" --> Store["Backup Store"]
    Incremental -- "Only changed WAL<br>entries since last backup" --> Store
    PITR -- "Snapshot + WAL replay<br>to exact timestamp" --> Restore["Restored Database"]

    Store --> Restore

Samyama supports three distinct levels of backup:

1. Full Snapshots

Leveraging RocksDB’s BackupEngine, Samyama can create a consistent, point-in-time snapshot of the entire database state without blocking incoming queries. These snapshots are stored in a dedicated backup directory and can be moved to off-site storage (e.g., AWS S3).

2. Incremental Backups

To optimize for storage and speed, Samyama can perform incremental backups. It tracks the Write-Ahead Log (WAL) sequence numbers and only archives the data blocks that have changed since the last full or incremental backup.

3. Point-in-Time Recovery (PITR)

This is the most advanced feature of our recovery engine. By replaying the archived WAL entries against a snapshot, Samyama can restore the database to an exact moment in time.

• Use Case: If a developer accidentally runs a MATCH (n) DELETE n query at 10:30:05 AM, the administrator can restore the system to 10:30:04 AM, undoing the damage with microsecond precision.

The ADMIN.BACKUP Protocol

Backups are managed via the RESP protocol using standard Redis-compatible clients.

# Create a new backup
redis-cli ADMIN.BACKUP CREATE

# List existing backups
redis-cli ADMIN.BACKUP LIST

# Verify the integrity of a backup
redis-cli ADMIN.BACKUP VERIFY 5

Retention Policies

To prevent disk exhaustion, Samyama Enterprise allows administrators to define automatic retention policies:

• Max Count: Keep only the last $N$ backups.
• Max Age: Automatically delete backups older than $X$ days.

This automated maintenance ensures that the system remains operational without manual intervention, providing peace of mind for site reliability engineers.

Recovery Guarantees

Developer Tip: Schedule backups during off-peak hours for minimal performance impact. Use ADMIN.BACKUP VERIFY periodically to ensure backup integrity before you need them.

Administrative Protocol

Samyama Enterprise introduces a dedicated Administrative Protocol implemented via the ADMIN.* RESP command set. This allows database administrators to control and monitor the server using standard Redis clients without resorting to separate APIs or CLI tools.

Server Management

These commands allow operators to inspect the internal state of a Samyama node without leaving their terminal.

• ADMIN.STATUS: Returns high-level health indicators, including server uptime, total query count, active connection count, and memory usage.
• ADMIN.METRICS: Dumps the complete internal metrics registry as a JSON object. This is useful for ad-hoc debugging or custom monitoring integration.
• ADMIN.CONFIG GET/SET: Allows for dynamic reconfiguration of the server without a restart. You can adjust the slow_query_threshold, memory quotas, or log levels on the fly.

Tenant Governance

In a multi-tenant environment, the ADMIN.TENANTS command is critical. It provides a detailed breakdown of resource consumption across the cluster:

Performance Introspection

The ADMIN.SLOWLOG command tracks queries that exceed the execution time threshold. Unlike general logging, this persists in a high-performance ring buffer for quick retrieval.

# Retrieve the last 10 slow queries
redis-cli ADMIN.SLOWLOG 10

Backup & Recovery

The ADMIN.BACKUP suite provides high-level control over the BackupEngine:

• ADMIN.BACKUP CREATE: Triggers an immediate, synchronous snapshot of the database.
• ADMIN.BACKUP LIST: Lists all available backups, their IDs, and timestamps.
• ADMIN.BACKUP VERIFY [id]: Performs a checksum verification of a specific backup’s data files.
• ADMIN.BACKUP RESTORE [id]: Restores the database to a previous state (requires a restart to finalize).
• ADMIN.BACKUP DELETE [id]: Manually removes a backup file and its associated metadata.

Governance & Licensing

Every ADMIN.* call is logged to the Audit Trail. The system also uses these commands to interact with the LicenseManager:

• ADMIN.LICENSE: Returns the details of the currently active license, including the expiry date and enabled features (e.g., gpu, monitoring, backup).

By integrating these controls into the RESP protocol, Samyama allows teams to build automated operational dashboards using their existing Redis-compatible tools and libraries.

Observability & Multi-tenancy

A database in production is a living organism. To keep it healthy, we need to see inside it, and to keep it secure, we need to isolate its users.

Multi-tenancy: Namespace Isolation (Enterprise)

Multi-tenancy is an Enterprise Edition feature. The Community Edition operates with a single "default" namespace — all data lives in one graph, which is simpler and perfectly adequate for single-application deployments.

The Enterprise Edition adds full multi-tenant capabilities: a Tenant Management HTTP API (CRUD + usage tracking), resource quotas, and namespace isolation via RocksDB Column Families.

Logical Separation with RocksDB (Enterprise)

graph TD
    subgraph "Samyama Enterprise Server"
        Router["Tenant Router"]
        Router --> TenantA["Tenant A<br>Quota: 1GB RAM, 10GB Disk"]
        Router --> TenantB["Tenant B<br>Quota: 2GB RAM, 50GB Disk"]
        Router --> TenantC["Tenant C<br>Quota: 512MB RAM, 5GB Disk"]
    end

    subgraph "RocksDB"
        TenantA --> CFA["Column Family: tenant_a<br>Independent compaction"]
        TenantB --> CFB["Column Family: tenant_b<br>Independent compaction"]
        TenantC --> CFC["Column Family: tenant_c<br>Independent compaction"]
    end

Enterprise leverages RocksDB’s Column Families (CF) for isolation. Each tenant is assigned their own CF.

• Isolation: Tenant A’s keyspace is physically and logically distinct from Tenant B’s.
• Maintenance: Compaction (the background cleanup process) happens per-tenant. If Tenant A is doing heavy writes, it won’t trigger a slow compaction for Tenant B.
• Backup: We can snapshot and restore individual tenants without affecting others.
• HTTP API: GET/POST/PATCH/DELETE /api/tenants for tenant lifecycle management; GET /api/tenants/:id/usage for resource tracking.

Resource Quotas (Enterprise)

To prevent the “Noisy Neighbor” problem, the Enterprise Edition enforces strict resource quotas per tenant:

• Memory Quota: Max RAM for the in-memory graph.
• Storage Quota: Max disk space in RocksDB.
• Query Time: Max duration for a single Cypher query (to prevent “queries from hell” from locking the CPU).

Observability: The Three Pillars

We follow the industry-standard observability stack: Prometheus, OpenTelemetry (OTEL), and Structured Logging.

1. Metrics (Prometheus)

Samyama exports hundreds of metrics in the Prometheus format.

• QPS: Queries per second (Read vs. Write).
• Latency Histograms: P50, P95, and P99 response times.
• Cache Hit Rates: How often we are hitting the in-memory graph versus going to RocksDB.

2. Structured Tracing

For complex queries, metrics aren’t enough. We need to know where the time was spent. Using the tracing crate in Rust, Samyama emits structured spans and events with timing data for every stage of query execution—parsing, planning, and execution. These spans can be collected and visualized using any tracing-compatible subscriber.

Note: Currently, Samyama uses tracing + tracing-subscriber for structured logging and span instrumentation. Full OpenTelemetry export (for visualization in Jaeger or Grafana Tempo) is on the roadmap for a future release.

3. Structured Logging

Gone are the days of parsing text logs. Samyama emits JSON logs.

{
  "timestamp": "2026-02-08T10:30:45Z",
  "level": "INFO",
  "query": "MATCH (n) RETURN n",
  "duration_ms": 12,
  "tenant": "acme_corp"
}

This allows for easy ingestion into ELK (Elasticsearch, Logstash, Kibana) or Loki for powerful log aggregation and searching.

By combining strong tenant isolation (Enterprise) with deep observability, Samyama provides a production-ready experience that allows operators to run massive multi-user clusters with confidence.

SDKs, CLI & API

Samyama provides a comprehensive developer ecosystem beyond the raw RESP and HTTP protocols. This chapter covers the official SDKs (Rust, Python, TypeScript), the command-line interface, and the OpenAPI specification.

Architecture Overview

graph TD
    subgraph "Client Layer"
        CLI["CLI (Rust + clap)"]
        RustSDK["Rust SDK"]
        PySDK["Python SDK (PyO3)"]
        TsSDK["TypeScript SDK (fetch)"]
    end

    subgraph "Transport"
        HTTP["HTTP API (:8080)"]
        Embedded["Embedded (in-process)"]
    end

    subgraph "Server"
        Engine["Query Engine + GraphStore"]
    end

    CLI --> RustSDK
    PySDK --> RustSDK
    RustSDK -- "RemoteClient" --> HTTP
    RustSDK -- "EmbeddedClient" --> Embedded
    TsSDK --> HTTP
    HTTP --> Engine
    Embedded --> Engine

All SDKs connect to the same engine—either over HTTP (remote) or directly in-process (embedded). The Rust SDK serves as the foundation: the CLI wraps it with a terminal interface, and the Python SDK wraps it via PyO3 FFI.

1. Rust SDK (samyama-sdk)

The Rust SDK is a workspace crate at crates/samyama-sdk/ that provides both embedded and remote access to the graph engine.

Core Trait: SamyamaClient

#![allow(unused)]
fn main() {
#[async_trait]
pub trait SamyamaClient: Send + Sync {
    async fn query(&self, graph: &str, cypher: &str) -> SamyamaResult<QueryResult>;
    async fn query_readonly(&self, graph: &str, cypher: &str) -> SamyamaResult<QueryResult>;
    async fn delete_graph(&self, graph: &str) -> SamyamaResult<()>;
    async fn list_graphs(&self) -> SamyamaResult<Vec<String>>;
    async fn status(&self) -> SamyamaResult<ServerStatus>;
    async fn ping(&self) -> SamyamaResult<String>;
}
}

EmbeddedClient — In-Process Access

For applications that want to embed Samyama directly (no network overhead):

#![allow(unused)]
fn main() {
use samyama_sdk::{EmbeddedClient, SamyamaClient};

// Create a fresh graph store
let client = EmbeddedClient::new();

// Or wrap an existing store
let client = EmbeddedClient::with_store(store.clone());

// Execute queries
let result = client.query("default", "CREATE (n:Person {name: 'Alice'})").await?;
let result = client.query_readonly("default", "MATCH (n:Person) RETURN n.name").await?;
}

The EmbeddedClient also provides factory methods for accessing subsystems:

RemoteClient — HTTP Transport

For connecting to a running Samyama server:

#![allow(unused)]
fn main() {
use samyama_sdk::{RemoteClient, SamyamaClient};

let client = RemoteClient::new("http://localhost:8080");
let status = client.status().await?;
let result = client.query("default", "MATCH (n) RETURN count(n)").await?;
}

Extension Traits (EmbeddedClient Only)

AlgorithmClient provides direct access to graph algorithms without writing Cypher:

#![allow(unused)]
fn main() {
use samyama_sdk::AlgorithmClient;

let scores = client.page_rank(config, "Person", "KNOWS").await;
let components = client.weakly_connected_components("Person", "KNOWS").await;
let path = client.dijkstra(src, dst, "City", "ROAD", Some("distance")).await;
let pca_result = client.pca("Person", &["age", "income", "score"], config).await;
}

Available algorithm methods: page_rank, weakly_connected_components, strongly_connected_components, bfs, dijkstra, edmonds_karp, prim_mst, count_triangles, bfs_all_shortest_paths, cdlp, local_clustering_coefficient, pca.

VectorClient provides vector search operations:

#![allow(unused)]
fn main() {
use samyama_sdk::VectorClient;

client.create_vector_index("Document", "embedding", 384, "cosine").await?;
client.add_vector("Document", "embedding", node_id, vec![0.1, 0.2, ...]).await?;
let results = client.vector_search("Document", "embedding", query_vec, 10).await?;
}

SDK Data Models

#![allow(unused)]
fn main() {
pub struct QueryResult {
    pub nodes: Vec<SdkNode>,
    pub edges: Vec<SdkEdge>,
    pub columns: Vec<String>,
    pub records: Vec<Vec<Value>>,
}

pub struct ServerStatus {
    pub status: String,      // "healthy"
    pub version: String,     // "1.0.0"
    pub storage: StorageStats,
}
}

2. Command-Line Interface (CLI)

The CLI at cli/ is a Rust binary wrapping the Rust SDK with clap for argument parsing and comfy-table for formatted output.

Installation & Usage

# Build from source
cargo build --release -p samyama-cli

# Connect to a running server
samyama-cli --url http://localhost:8080 query "MATCH (n) RETURN count(n)"

# Output formats
samyama-cli --format table query "MATCH (n:Person) RETURN n.name, n.age"
samyama-cli --format json  query "MATCH (n:Person) RETURN n.name"
samyama-cli --format csv   query "MATCH (n:Person) RETURN n.name, n.age"

Subcommands

Interactive Shell

$ samyama-cli shell
samyama> MATCH (n:Person) RETURN n.name
+----------+
| n.name   |
+----------+
| Alice    |
| Bob      |
+----------+

samyama> :status
Status: healthy | Version: 1.0.0 | Nodes: 2000 | Edges: 11000

samyama> :help
samyama> :quit

Environment Variables

3. Python SDK (PyO3)

The Python SDK at sdk/python/ provides native Python bindings via PyO3, wrapping the Rust SDK as a compiled C extension (cdylib).

Usage

from samyama import SamyamaClient

# Embedded mode (in-process, no server needed)
client = SamyamaClient.embedded()

# Remote mode (connect to running server)
client = SamyamaClient.connect("http://localhost:8080")

# Execute queries
result = client.query("MATCH (n:Person) RETURN n.name")
print(result.columns)   # ['n.name']
print(result.records)    # [['Alice'], ['Bob']]
print(len(result))       # 2

# Server info
status = client.status()
print(status.version)    # '1.0.0'
print(status.nodes)      # 2000

Architecture

The Python SDK uses a shared tokio::Runtime (via OnceLock) to bridge Python’s synchronous API with the Rust SDK’s async internals. JSON serialization via serde_json handles the boundary between Rust types and Python objects.

4. TypeScript SDK

The TypeScript SDK at sdk/typescript/ is a standalone pure-TypeScript implementation using the browser/Node.js fetch API for HTTP transport. It does not wrap the Rust SDK.

Usage

import { SamyamaClient } from 'samyama-sdk';

const client = SamyamaClient.connectHttp('http://localhost:8080');

// Execute queries
const result = await client.query('MATCH (n:Person) RETURN n.name');
console.log(result.columns);  // ['n.name']
console.log(result.records);  // [['Alice'], ['Bob']]

// Server status
const status = await client.status();
console.log(status.version);  // '1.0.0'

5. OpenAPI Specification

The HTTP API is documented in api/openapi.yaml and provides two endpoints:

POST /api/query

Execute a Cypher query against the graph.

Request:

{ "query": "MATCH (n:Person) RETURN n.name, n.age LIMIT 10" }

Response:

{
  "nodes": [{ "id": "1", "labels": ["Person"], "properties": { "name": "Alice" } }],
  "edges": [],
  "columns": ["n.name", "n.age"],
  "records": [["Alice", 30], ["Bob", 25]]
}

GET /api/status

Get server health and statistics.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "storage": { "nodes": 2000, "edges": 11000 }
}

SDK Capability Matrix

Developer Tip: All 10 domain-specific examples in the examples/ directory have been migrated to use the SDK’s EmbeddedClient, demonstrating real-world usage patterns for banking, clinical trials, supply chain, and more.

Ecosystem Architecture & Dependency Graph

This chapter maps the full Samyama ecosystem: repositories, modules, features, and knowledge graph projects — with dependency graphs showing how everything connects.

1. Repository Map

graph LR
    subgraph Public ["Public (GitHub)"]
        SG["samyama-graph<br/>(OSS engine)"]
        SI["samyama-insight<br/>(React frontend +<br/>book hosting at /book)"]
        CKG["cricket-kg"]
        CTKG["clinicaltrials-kg"]
    end

    subgraph Private ["Private"]
        SGE["samyama-graph-enterprise"]
        SC["samyama-cloud<br/>(book sources, wiki, deploy)"]
        SR["samyama-research<br/>(papers, reproductions)"]
        AOKG["assetops-kg"]
    end

    SG -->|"sync via PR"| SGE
    SG -->|"Python SDK"| CKG
    SG -->|"Python SDK"| CTKG
    SG -->|"Python SDK"| AOKG
    SG -->|"TS SDK"| SI
    SGE -->|"deploy scripts"| SC
    SC -->|"mdBook build → public/book-static/"| SI
    SR -.->|"published PDFs"| SI

    style SG fill:#4a9eff,stroke:#333,color:#fff
    style SGE fill:#ff6b6b,stroke:#333,color:#fff
    style SI fill:#51cf66,stroke:#333,color:#fff
    style SC fill:#ffd43b,stroke:#333
    style SR fill:#ffd43b,stroke:#333
    style CKG fill:#b197fc,stroke:#333,color:#fff
    style CTKG fill:#b197fc,stroke:#333,color:#fff
    style AOKG fill:#b197fc,stroke:#333,color:#fff

Ecosystem in Action

Graph Simulation — Cricket KG (36K nodes, 1.4M edges) with live activity particles

Click for full demo (1:56) — Dashboard, Cypher Queries, and Graph Simulation

2. samyama-graph Module Architecture

The OSS engine is organized into 7 core modules, 3 workspace crates, and 3 SDK packages.

graph TB
    subgraph "SDK Layer"
        PYSDK["sdk/python<br/>samyama (PyO3)"]
        MCP["sdk/python<br/>samyama_mcp"]
        TSSDK["sdk/typescript<br/>samyama-sdk"]
    end

    subgraph "Crates"
        SDK["crates/samyama-sdk<br/>EmbeddedClient + RemoteClient"]
        ALGO["crates/samyama-graph-algorithms<br/>PageRank, WCC, SCC, BFS, etc."]
        OPT["crates/samyama-optimization<br/>Rao-family + classical metaheuristics"]
    end

    subgraph CLI
        CLIRS["cli/<br/>query, status, shell"]
    end

    subgraph "Core Engine (src/)"
        QUERY["query/<br/>parser (Pest) + planner + executor"]
        GRAPH["graph/<br/>store, node, edge, property, catalog"]
        PROTO["protocol/<br/>RESP server + HTTP API"]
        PERSIST["persistence/<br/>RocksDB, WAL, tenant"]
        RAFT["raft/<br/>openraft consensus"]
        NLQ["nlq/<br/>text-to-Cypher (multi-provider)"]
        AGENT["agent/<br/>GAK runtime + tools"]
        VECTOR["vector/<br/>HNSW index"]
        SHARD["sharding/<br/>tenant-level routing"]
    end

    %% SDK dependencies
    PYSDK --> SDK
    MCP --> PYSDK
    TSSDK -->|"HTTP fetch"| PROTO
    CLIRS --> SDK

    %% Crate dependencies
    SDK --> QUERY
    SDK --> GRAPH
    SDK --> PERSIST
    SDK --> ALGO
    SDK --> OPT
    SDK --> NLQ
    SDK --> AGENT
    SDK --> VECTOR

    %% Core module dependencies
    QUERY --> GRAPH
    PROTO --> QUERY
    PROTO --> GRAPH
    PERSIST --> GRAPH
    RAFT --> PERSIST
    NLQ --> QUERY
    AGENT --> NLQ
    VECTOR --> GRAPH
    SHARD --> PERSIST
    ALGO --> GRAPH

    style QUERY fill:#4a9eff,stroke:#333,color:#fff
    style GRAPH fill:#51cf66,stroke:#333,color:#fff
    style PROTO fill:#ffd43b,stroke:#333
    style SDK fill:#ff6b6b,stroke:#333,color:#fff
    style MCP fill:#b197fc,stroke:#333,color:#fff
    style PYSDK fill:#b197fc,stroke:#333,color:#fff

Module Responsibilities

3. Enterprise Feature Layering (OSS → SGE)

graph TB
    subgraph OSS ["samyama-graph (OSS — Apache 2.0)"]
        QE["Query Engine<br/>~90% OpenCypher"]
        PS["Persistence<br/>RocksDB + WAL"]
        MT["Multi-Tenancy"]
        VS["Vector Search<br/>HNSW"]
        GA["Graph Algorithms<br/>PageRank, WCC, BFS..."]
        NQ["NLQ<br/>text-to-Cypher"]
        HV["HTTP Visualizer"]
        RF["Raft Consensus<br/>(basic)"]
        MO["Metaheuristic<br/>Optimization"]
        RDF["RDF / SPARQL<br/>(infrastructure)"]
    end

    subgraph SGE ["samyama-graph-enterprise (Proprietary)"]
        MON["Prometheus /metrics"]
        HC["Health Checks"]
        BK["Backup & Restore<br/>(PITR)"]
        AU["Audit Trail"]
        SQ["Slow Query Log"]
        ADM["ADMIN.* Commands"]
        ERF["Enhanced Raft<br/>(HTTP transport)"]
        GPU["GPU Acceleration<br/>(wgpu shaders)"]
        LIC["JET Licensing<br/>(Ed25519 signed)"]
    end

    SGE -->|"inherits all of"| OSS

    GPU -->|"accelerates"| GA
    GPU -->|"accelerates"| VS
    MON -->|"observes"| QE
    BK -->|"snapshots"| PS
    AU -->|"logs"| QE
    LIC -->|"gates"| SGE

    style OSS fill:#e8f5e9,stroke:#2e7d32
    style SGE fill:#fce4ec,stroke:#c62828

For the full feature-by-feature comparison between Community and Enterprise editions, see the Enterprise Edition Overview.

4. Knowledge Graph Projects

All KG projects share the same stack: Python SDK → samyama-mcp-serve → custom config.

graph TB
    subgraph Engine ["Samyama Engine"]
        SG["samyama-graph<br/>(Rust)"]
        PYSDK["samyama<br/>(Python SDK / PyO3)"]
        MCPSERVE["samyama_mcp<br/>(MCP serve)"]
    end

    subgraph KGs ["Knowledge Graph Projects"]
        subgraph CKG ["cricket-kg"]
            CETL["etl/loader.py<br/>(Cricsheet JSON)"]
            CMCP["mcp_server/<br/>config.yaml (12 custom)"]
            CTEST["tests/<br/>25 MCP tests"]
        end

        subgraph CTKG ["clinicaltrials-kg"]
            CTETL["etl/loader.py<br/>(API or AACT flat files)"]
            CTMCP["mcp_server/<br/>16 tools (hand-written)"]
            CTAACT["etl/aact_loader.py<br/>(500K+ studies)"]
        end

        subgraph AOKG ["assetops-kg"]
            AOETL["etl/loader.py"]
            AOMCP["mcp_server/<br/>9 tools"]
        end
    end

    SG --> PYSDK
    PYSDK --> MCPSERVE
    MCPSERVE --> CMCP
    MCPSERVE -.->|"SK-14: migrate"| CTMCP
    MCPSERVE -.->|"SK-15: migrate"| AOMCP
    PYSDK --> CETL
    PYSDK --> CTETL
    PYSDK --> CTAACT
    PYSDK --> AOETL

    style SG fill:#4a9eff,stroke:#333,color:#fff
    style MCPSERVE fill:#b197fc,stroke:#333,color:#fff
    style CKG fill:#d0f0c0,stroke:#2e7d32
    style CTKG fill:#ffe0b2,stroke:#e65100
    style AOKG fill:#e1bee7,stroke:#6a1b9a

KG Schema Summary

5. Feature Dependency Graph (Backlog)

The complete feature dependency chain across all backlog items. Green = done, blue = in progress, white = planned.

graph TB
    subgraph "Query Engine (Done ✅)"
        QE01["QE-01<br/>Parameterized $param"]
        QE02["QE-02<br/>PROFILE stats"]
        QE03["QE-03<br/>shortestPath()"]
        QE07["QE-07<br/>CALL procedures"]
    end

    subgraph "Cypher Completeness (Done ✅)"
        CY01["CY-01<br/>collect(DISTINCT)"]
        CY02["CY-02<br/>datetime args"]
        CY04["CY-04<br/>Named paths"]
        CY05["CY-05<br/>Path functions"]
    end

    subgraph "Planner / Optimizer (Done ✅)"
        QP01["QP-01 Predicate pushdown"]
        QP02["QP-02 Cost-based"]
        QP05["QP-05 Plan cache"]
        QP11["QP-11 Graph-native enum"]
        QP12["QP-12 Triple stats"]
        QP13["QP-13 ExpandInto"]
        QP14["QP-14 Direction reversal"]
        QP15["QP-15 Logical plan IR"]
    end

    subgraph "Planner (Planned)"
        QP06["QP-06<br/>Histogram stats"]
        QP09["QP-09<br/>Operator fusion"]
        QP10["QP-10<br/>Adaptive exec"]
    end

    subgraph "Indexes (Done ✅)"
        IX01["IX-01..06<br/>DROP/SHOW/Composite/Unique"]
    end

    subgraph "Indexes (Planned)"
        IX07["IX-07<br/>Full-text index"]
        IX08["IX-08<br/>OR union scans"]
    end

    subgraph "Performance (Done ✅)"
        PF01["PF-01 CSR"]
        PF04["PF-04 Late materialization"]
        PF06["PF-06 AST cache"]
    end

    subgraph "Performance (Planned)"
        PF07["PF-07<br/>MVCC"]
        PF09["PF-09<br/>WCO joins"]
        PF10["PF-10<br/>Parallel exec"]
    end

    subgraph "Data Structures (Done ✅)"
        DS01["DS-01 Triple stats"]
        DS02["DS-02 Sorted adjacency"]
    end

    subgraph "Data Structures (Planned)"
        DS03["DS-03<br/>Type-partitioned adj"]
    end

    subgraph "SDK / MCP (Done ✅)"
        SK01["SK-01..06<br/>Rust/Python/TS SDK + CLI"]
        SK09["SK-09 npm publish"]
        SK10["SK-10 EXPLAIN/PROFILE"]
        SK11["SK-11 Schema/Stats"]
        SK12["SK-12<br/>samyama-mcp-serve"]
        SK13["SK-13<br/>cricket-kg MCP"]
    end

    subgraph "SDK (Planned)"
        SK14["SK-14<br/>clinicaltrials MCP"]
        SK15["SK-15<br/>assetops MCP"]
    end

    subgraph "HA (Done ✅)"
        HA01["HA-01 Raft"]
        HA02["HA-02 Sharding"]
        HA03["HA-03 Vector persist"]
    end

    subgraph "HA (Planned)"
        HA04["HA-04<br/>Temporal queries"]
        HA05["HA-05<br/>Graph sharding"]
        HA06["HA-06<br/>Distributed exec"]
    end

    subgraph "AI (Done ✅)"
        AI01["AI-01 GAK runtime"]
        AI02["AI-02 NLQ"]
        AI03["AI-03 Auto-embed"]
    end

    subgraph "AI / JIT KG (Planned)"
        AI07["AI-07<br/>Enterprise connectors"]
        AI08["AI-08<br/>Demand-driven agent"]
        AI09["AI-09<br/>Text-to-SQL bridge"]
        AI10["AI-10<br/>JIT KG demo"]
    end

    subgraph "GPU (Done ✅)"
        GP01["GP-01..10<br/>PageRank, CDLP, LCC,<br/>PCA, triangles, vectors,<br/>aggregates, sort"]
    end

    subgraph "Benchmarks (Done ✅)"
        BM01["BM-01..03<br/>Graphalytics, SNB, FinBench"]
    end

    subgraph "Benchmarks (Planned)"
        BM04["BM-04<br/>SF10 scale"]
        BM05["BM-05<br/>SNB BI tuning"]
        BM07["BM-07<br/>Comparative bench"]
    end

    subgraph "Visualizer (Done ✅)"
        VZ01["VZ-01..05<br/>Plan DAG, PROFILE,<br/>Stats, Console, Features"]
        VZ07["VZ-07..10<br/>Schema, CSV/JSON Import, E2E"]
    end

    subgraph "KG Projects"
        KG01["KG-01<br/>AACT full loader<br/>(in progress)"]
    end

    %% Dependencies
    CY01 & CY02 & QE03 & CY04 --> BM05
    CY04 --> CY05
    PF06 --> QP05
    QP01 & QP02 --> BM04
    PF07 --> HA04
    DS02 --> PF09
    HA05 --> HA06
    QE01 --> QP11
    QP12 --> QP11
    DS02 --> QP13
    QP14 --> QP11
    QP15 --> QP11
    SK09 --> VZ01
    SK10 --> VZ01
    SK11 --> VZ07
    QE07 --> VZ07
    SK12 --> SK13
    SK12 --> SK14
    SK12 --> SK15

    %% JIT KG chain
    AI01 --> AI07
    AI02 --> AI07
    SK12 --> AI07
    AI02 --> AI09
    AI07 --> AI08
    AI09 --> AI08
    AI08 --> AI10

    %% KG-01
    IX01 --> KG01

    %% Benchmark deps
    BM07 -.-> BM05

    style QE01 fill:#51cf66,stroke:#333,color:#fff
    style QE02 fill:#51cf66,stroke:#333,color:#fff
    style QE03 fill:#51cf66,stroke:#333,color:#fff
    style QE07 fill:#51cf66,stroke:#333,color:#fff
    style CY01 fill:#51cf66,stroke:#333,color:#fff
    style CY02 fill:#51cf66,stroke:#333,color:#fff
    style CY04 fill:#51cf66,stroke:#333,color:#fff
    style CY05 fill:#51cf66,stroke:#333,color:#fff
    style QP01 fill:#51cf66,stroke:#333,color:#fff
    style QP02 fill:#51cf66,stroke:#333,color:#fff
    style QP05 fill:#51cf66,stroke:#333,color:#fff
    style QP11 fill:#51cf66,stroke:#333,color:#fff
    style QP12 fill:#51cf66,stroke:#333,color:#fff
    style QP13 fill:#51cf66,stroke:#333,color:#fff
    style QP14 fill:#51cf66,stroke:#333,color:#fff
    style QP15 fill:#51cf66,stroke:#333,color:#fff
    style IX01 fill:#51cf66,stroke:#333,color:#fff
    style PF01 fill:#51cf66,stroke:#333,color:#fff
    style PF04 fill:#51cf66,stroke:#333,color:#fff
    style PF06 fill:#51cf66,stroke:#333,color:#fff
    style DS01 fill:#51cf66,stroke:#333,color:#fff
    style DS02 fill:#51cf66,stroke:#333,color:#fff
    style SK01 fill:#51cf66,stroke:#333,color:#fff
    style SK09 fill:#51cf66,stroke:#333,color:#fff
    style SK10 fill:#51cf66,stroke:#333,color:#fff
    style SK11 fill:#51cf66,stroke:#333,color:#fff
    style SK12 fill:#51cf66,stroke:#333,color:#fff
    style SK13 fill:#51cf66,stroke:#333,color:#fff
    style HA01 fill:#51cf66,stroke:#333,color:#fff
    style HA02 fill:#51cf66,stroke:#333,color:#fff
    style HA03 fill:#51cf66,stroke:#333,color:#fff
    style AI01 fill:#51cf66,stroke:#333,color:#fff
    style AI02 fill:#51cf66,stroke:#333,color:#fff
    style AI03 fill:#51cf66,stroke:#333,color:#fff
    style GP01 fill:#51cf66,stroke:#333,color:#fff
    style BM01 fill:#51cf66,stroke:#333,color:#fff
    style VZ01 fill:#51cf66,stroke:#333,color:#fff
    style VZ07 fill:#51cf66,stroke:#333,color:#fff
    style KG01 fill:#4a9eff,stroke:#333,color:#fff
    style AI07 fill:#fff,stroke:#333
    style AI08 fill:#fff,stroke:#333
    style AI09 fill:#fff,stroke:#333
    style AI10 fill:#fff,stroke:#333

6. Data Flow: Query → Enrichment → Response

This diagram shows the runtime data flow for a JIT KG query, incorporating the planned AI-07..AI-10 features.

sequenceDiagram
    participant U as User / Agent
    participant MCP as MCP Server
    participant NLQ as NLQ Pipeline
    participant QE as Query Engine
    participant GS as GraphStore
    participant AG as GAK Agent
    participant SRC as Enterprise Source<br/>(OneDrive / OLTP)

    U->>MCP: Natural language question
    MCP->>NLQ: text_to_cypher(question, schema)
    NLQ->>QE: MATCH (n:Person)-[:AUTHORED]->(d:Document)...
    QE->>GS: Execute query
    GS-->>QE: 0 results (gap detected)
    QE-->>MCP: Empty result set

    Note over MCP,AG: AI-08: Demand-driven enrichment triggers

    MCP->>AG: process_trigger(gap_context)
    AG->>SRC: AI-07: Pull from OneDrive (documents)
    SRC-->>AG: Document metadata + content
    AG->>NLQ: Extract entities (LLM)
    NLQ-->>AG: Cypher: CREATE (p:Person)..., CREATE (d:Document)...
    AG->>QE: Execute enrichment Cypher
    QE->>GS: MERGE nodes + edges

    AG->>SRC: AI-09: text-to-SQL (OLTP database)
    SRC-->>AG: Relational rows
    AG->>NLQ: Transform to graph entities (LLM)
    NLQ-->>AG: Cypher: CREATE (proj:Project)...
    AG->>QE: Execute enrichment Cypher
    QE->>GS: MERGE nodes + edges

    Note over MCP,GS: Graph enriched — re-execute original query

    MCP->>QE: Re-execute original Cypher
    QE->>GS: Execute query
    GS-->>QE: Results (populated)
    QE-->>MCP: Result set
    MCP-->>U: Answer with graph context

7. Deployment Architecture

graph TB
    subgraph "Samyama Server"
        SGE_BIN["samyama-graph<br/>(release binary)"]
        ROCKS["RocksDB<br/>(persistent storage)"]
        SI_DIST["samyama-insight<br/>(static dist/)"]
    end

    subgraph "Developer Workflow"
        SG_DEV["samyama-graph<br/>(cargo build)"]
        PY_DEV["Python SDK<br/>(maturin develop)"]
        KG_DEV["KG projects<br/>(python -m etl.loader)"]
    end

    subgraph "External Services"
        LLM["LLM Provider<br/>(OpenAI / Claude / Ollama)"]
    end

    SGE_BIN -->|":6379 RESP"| ROCKS
    SGE_BIN -->|":8080 HTTP"| SI_DIST
    SG_DEV -->|"sync via PR"| SGE_BIN
    SG_DEV --> PY_DEV --> KG_DEV
    SGE_BIN -->|"NLQ / GAK"| LLM

    style SGE_BIN fill:#ff6b6b,stroke:#333,color:#fff
    style SG_DEV fill:#4a9eff,stroke:#333,color:#fff

8. Version Sync Points

All packages must stay version-aligned. These are the 13 files that must be updated together on a version bump (Step 0.5 in the workflow):

graph LR
    V["Version<br/>v1.0.0"]

    V --> CT["Cargo.toml<br/>(root)"]
    V --> CLI["cli/Cargo.toml"]
    V --> SDKRS["crates/samyama-sdk/<br/>Cargo.toml"]
    V --> OPTC["crates/samyama-optimization/<br/>Cargo.toml"]
    V --> ALGOC["crates/samyama-graph-algorithms/<br/>Cargo.toml"]
    V --> PYC["sdk/python/Cargo.toml"]
    V --> PYP["sdk/python/pyproject.toml"]
    V --> TSP["sdk/typescript/package.json"]
    V --> TSL["sdk/typescript/package-lock.json"]
    V --> API["api/openapi.yaml"]
    V --> LIB["src/lib.rs<br/>(test_version)"]
    V --> CMD["CLAUDE.md"]

    style V fill:#ffd43b,stroke:#333

9. Technology Stack

The Future of Graph DBs

The rest of this book describes what Samyama is today: a single-server graph database with MVCC isolation, OpenCypher and SPARQL frontends, GPU-accelerated analytics, vector search, and a 500/500-pass mega-benchmark across 11 federated knowledge graphs. This chapter is about where it goes next — frontier directions that build on that foundation.

1. Time-Travel Queries (Temporal Graphs)

Data is not static; it flows. Current graph databases only show the current state.

We plan to expose our internal MVCC versions to the user. Goal: Allow queries like:

MATCH (p:Person)-[:KNOWS]->(f:Person)
WHERE p.name = 'Alice'
AT TIME '2023-01-01' -- Query the graph as it looked last year
RETURN f.name

This is invaluable for auditing, debugging, and historical analysis.

2. Graph-Level Sharding

Currently, we shard by Tenant. This is perfect for SaaS but limits the size of a single graph to one machine’s capacity (vertical scaling).

The Challenge: Partitioning a single graph across multiple machines is the “Holy Grail” of graph databases. It introduces the “Min-Cut” problem (minimizing edges that cross machines) to reduce network latency.

The Plan: We are investigating METIS and streaming partitioning algorithms to intelligently distribute nodes based on community structure, ensuring that “friends stay together” on the same physical server.

3. Distributed Query Execution (Scatter-Gather)

To complement Graph-Level Sharding, the query engine must evolve from a single-node vectorized iterator to a distributed execution framework.

• Query Coordinator: Will partition the physical plan into sub-plans.
• Workers: Execute local traversals.
• Shuffle/Exchange Operators: Pass intermediate RecordBatch streams across the network using Arrow Flight RPC.

4. PROFILE (Runtime Statistics)

While EXPLAIN shows the plan, PROFILE will show the reality—executing the query and collecting actual row counts and operator-level timing. This will complement cost-based optimization with empirical feedback.

5. Native Graph Neural Networks (GNNs)

While we currently support powerful vector search (HNSW) and metaheuristic optimization, the next step in “predictive power” is natively training and serving Graph Neural Networks directly within the database.

• Goal: Run CALL algo.gnn.predict_link('Person', 'KNOWS') without exporting data to Python and PyTorch Geometric.

Full Backlog

The items above are highlights. The complete prioritized backlog with ~100 items across 13 categories is maintained in samyama-cloud/docs/BACKLOG.md. Key backlog IDs referenced in this chapter:

Conclusion

Samyama started as a question: “Can we do better?” The answer, we believe, is “Yes.”

By fusing the transactional integrity of RocksDB, the safety of Rust, the massive parallelism of GPU compute shaders, and the semantic power of AI, we are building a database engine for the next decade of intelligent applications.

Thank you for exploring the architecture of Samyama with us.

Frequently Asked Questions

This FAQ covers common questions about Samyama’s architecture, usage, and capabilities. Use your browser’s search (Ctrl+F / Cmd+F) or the mdBook search bar to quickly find answers.

Getting Started

How do I install and run Samyama?

# Clone and build
git clone https://github.com/samyama-ai/samyama-graph.git
cd samyama-graph
cargo build --release

# Start the server (RESP on :6379, HTTP on :8080)
cargo run --release

# Run a demo
cargo run --example banking_demo

What protocols does Samyama support? Is it Postgres wire protocol?

No, Samyama does not use the Postgres wire protocol. It exposes two protocols:

• RESP (Redis Protocol) on port 6379 — use any Redis client (redis-cli, Jedis, ioredis, etc.)
• HTTP API on port 8080 — RESTful endpoints for queries and status

We chose RESP over Postgres wire protocol because: (1) RESP is simpler and faster (binary protocol, minimal framing overhead), (2) it enables drop-in compatibility with the RedisGraph ecosystem (which was sunset by Redis Ltd), and (3) graph queries are fundamentally different from SQL — we didn’t want to shoehorn Cypher into a SQL-shaped protocol.

Example using redis-cli:

redis-cli GRAPH.QUERY default "CREATE (n:Person {name: 'Alice', age: 30})"
redis-cli GRAPH.QUERY default "MATCH (n:Person) RETURN n.name, n.age"

Example using HTTP:

curl -s -X POST http://localhost:8080/api/query \
  -d '{"query": "MATCH (n) RETURN count(n)", "graph": "default"}'

curl -s http://localhost:8080/api/status | python3 -m json.tool

See the SDKs, CLI & API chapter.

What query language does Samyama use?

Samyama supports OpenCypher with ~90% coverage. Supported clauses: MATCH, OPTIONAL MATCH, CREATE, DELETE, SET, REMOVE, MERGE, WITH, UNWIND, UNION, RETURN DISTINCT, ORDER BY, SKIP, LIMIT, EXPLAIN, EXISTS subqueries.

Example — create a small social graph and query it:

CREATE (a:Person {name: 'Alice', age: 30})-[:KNOWS]->(b:Person {name: 'Bob', age: 25})
CREATE (b)-[:KNOWS]->(c:Person {name: 'Charlie', age: 35})

MATCH (p:Person)-[:KNOWS]->(friend)
WHERE p.age > 28
RETURN p.name, friend.name

See the Query Engine chapter.

What are the minimum system requirements?

Samyama runs on any system with a Rust 1.83+ toolchain:

• CPU: Any x86_64 or ARM64 (M-series Macs fully supported)
• RAM: 512MB minimum; 4GB+ recommended for production
• Disk: Depends on data size; RocksDB with LZ4 compression is space-efficient
• GPU (Enterprise only): Any Metal, Vulkan, or DX12-compatible GPU

What is the difference between Community and Enterprise?

See the Enterprise Edition chapter for full details.

Query Engine

What Cypher features are NOT yet supported?

Remaining gaps: list slicing ([1..3]) and pattern comprehensions. The Future Roadmap tracks planned additions.

Added in v0.6.0: Named paths (p = (a)-[]->(b)), CASE expressions, collect(DISTINCT x), datetime({year: 2026, month: 3}) constructor, parameterized queries ($param), and PROFILE.

-- Named paths (v0.6.0):
MATCH p = (a:Person)-[:KNOWS]->(b:Person) RETURN p, length(p)

-- CASE expressions (v0.6.0):
MATCH (n:Person) RETURN n.name, CASE WHEN n.age > 30 THEN 'senior' ELSE 'junior' END AS category

-- collect(DISTINCT x) (v0.6.0):
MATCH (n:Person)-[:LIVES_IN]->(c:City) RETURN collect(DISTINCT c.name) AS cities

-- Parameterized queries (v0.6.0):
MATCH (n:Person {age: $age}) RETURN n

How do I check if my query is using an index?

Use EXPLAIN before your query:

EXPLAIN MATCH (n:Person {name: 'Alice'}) RETURN n

If you see IndexScanOperator in the output, the index is being used. If you see NodeScanOperator, the query is doing a full label scan — consider creating an index:

-- Before: full scan (slow on large graphs)
EXPLAIN MATCH (n:Person) WHERE n.name = 'Alice' RETURN n
-- Output: NodeScanOperator(Person) → FilterOperator(n.name = 'Alice')

-- Create the index:
CREATE INDEX ON :Person(name)

-- After: index scan (fast O(log n))
EXPLAIN MATCH (n:Person) WHERE n.name = 'Alice' RETURN n
-- Output: IndexScanOperator(Person.name = 'Alice')

See the Query Optimization chapter.

Can I use EXPLAIN to see estimated costs?

Yes. EXPLAIN returns the operator tree with estimated row counts and graph statistics (label counts, edge type counts, property selectivity):

EXPLAIN MATCH (a:Person)-[:KNOWS]->(b:Person)
WHERE a.age > 25
RETURN a.name, b.name

Output includes:

ProjectOperator [a.name, b.name]
  └── FilterOperator [a.age > 25]
        └── ExpandOperator [KNOWS]
              └── NodeScanOperator [Person]
--- Statistics ---
  Person: 10,000 nodes
  KNOWS: 45,000 edges
  avg_out_degree: 4.5

PROFILE (with actual execution timing and row counts per operator) is supported since v0.6.0:

PROFILE MATCH (a:Person)-[:KNOWS]->(b:Person)
WHERE a.age > 25
RETURN a.name, b.name

How many physical operators does the engine have?

33 operators covering scan, traversal, filter, join, aggregation, sort, write, index, constraint, and specialized operations. See the operator table.

Does Samyama support transactions?

Samyama provides per-query atomicity via RocksDB WriteBatch + WAL. Each write query (CREATE, DELETE, SET, MERGE) executes as an atomic unit — either all changes commit or none do.

-- This entire query is atomic — both nodes and the edge are created together:
CREATE (a:Account {id: 'A1', balance: 1000})-[:TRANSFER {amount: 500}]->(b:Account {id: 'A2', balance: 2000})

Interactive BEGIN...COMMIT transactions (spanning multiple queries) are on the roadmap. See the ACID Guarantees section.

Indexes & Data Access

What types of indexes does Samyama support?

Samyama provides four index types: