JetGraph Documentation

⚡ Quick Start in 5 Minutes

Get JetGraph running locally and execute your first graph query — no build step, no configuration.

1. 1

   Start JetGraph with Docker Compose

   Save the following as docker-compose.yml and run docker compose up -d.

2. 2

   Verify the engine is ready

   Wait about 5 seconds for the container to start, then check the health endpoint.

3. 3

   Load sample data with one click (optional)

   Open the Admin UI at http://localhost, click Schema in the left nav, then click ⚡ Apply Schema & Load Sample Data in the Quick Start — Credit Card Fraud Space card. This provisions the Credit Card Fraud schema and seeds a representative dataset so every query in Analytics returns results. When the green All done banner appears, explore the data in Graph Explorer, Cypher Editor, or the Analytics pages. Prefer to bring your own schema? Skip this step and register it manually in Step 4 below.

4. 4

   Or — register a schema and write your first node

   Skip this step if you loaded the sample dataset in Step 3. Otherwise, schema must be declared once before any data can be written. Run these three calls in order.

Introduction

What is JetGraph?

JetGraph is a purpose-built, in-memory graph engine designed for applications that need real-time graph queries and decisions at high throughput. It stores your graph entirely in memory for sub-millisecond access, supports the Cypher query language, speaks the Bolt wire protocol (compatible with all official Neo4j drivers), and exposes a simple HTTP/Cypher API for any language.

JetGraph is not a general-purpose persistent database — it is purpose-built for high-velocity workloads where you need graph signals in real time: fraud detection, recommendation engines, anomaly detection, network security, and more.

Key Features

When to Use a Graph Database

Graph databases shine when the relationships between entities are as important as the entities themselves. Use JetGraph when you need to:

• Detect patterns across connected entities (e.g., shared devices, IPs, or accounts)
• Compute real-time velocity and novelty signals (e.g., "how many times did this card transact in the last hour?")
• Traverse multi-hop paths (e.g., "find all merchants connected to a flagged card via two hops")
• Build recommendation systems based on shared relationships
• Propagate risk or scores across a network automatically

Running JetGraph

Prerequisites

• Docker 24+ and Docker Compose v2 — required for the demo image
• curl — for testing API calls from the terminal
• Any Neo4j-compatible Bolt driver (optional, for Bolt connections)
• Rust toolchain (optional, only for the jetgraph-client crate)

Exposed Ports

Health Check

Connection — REST / Cypher API

The simplest way to interact with JetGraph from any language. Send a JSON body with a query (Cypher string) and optional parameters to POST /cypher.

Base URL

Request Format

Response Format

Successful responses return a JSON object with columns and rows:

Example Requests

Additional Endpoints

Error Responses

On error, JetGraph returns a non-2xx HTTP status with a JSON error body:

Connection — Bolt Protocol

JetGraph speaks the Bolt binary protocol on port 7687, the same protocol used by Neo4j. This means any official or community Neo4j driver works out-of-the-box — no code changes, no new SDK to learn.

What is Bolt?

Bolt is a binary, connection-oriented protocol optimized for graph databases. It supports efficient serialisation of Cypher queries and results, pipelining, and authentication. Because JetGraph is Bolt-compatible, you can use drivers for Python, JavaScript, Java, Go, .NET, and more without modification.

Connection Details

Python Example

JavaScript (Node.js) Example

Connection — Rust Client

The jetgraph-client crate provides a typed, ergonomic API over gRPC. It is the recommended client for Rust applications that need the highest throughput and the lowest latency.

Installation

Add the crate to your Cargo.toml:

Minimal Working Example

Recommended Usage Pattern

For scoring workloads, follow the Query → Score → Insert three-phase pattern on every event:

• Query: collect all graph signals (velocity, novelty, risk context) before scoring
• Score: apply your business logic using the signals
• Insert: always record the event edge, regardless of the decision

Data Modeling in JetGraph

Core Concepts

JetGraph organizes data into two primitives:

• Nodes — entities in your domain (e.g., a user, a card, a merchant, a device)
• Relationships (edges) — directed connections between two nodes (e.g., CARD -[:TRANSACTS_AT]-> MERCHANT)

Each node and edge has a type (also called a label) and an optional set of properties (key-value pairs).

Graph Diagram — Fraud Detection Domain

Schema Registration

Before any data can be written, you must declare your node types and edge types. This is done once at startup via the CALL db.* system procedures, then finalized with db.finalizeSchema().

Edge Types, Histograms & Activity Windows

Edge types define both the graph relationship (CARD → MERCHANT) and the feature storage kept for every edge pair. The storage layout is chosen once, when the edge type is registered. For ML/GNN use cases, the two most important read paths are: graph.histogram for node-level bucketed counts and graph.edgeState for edge-pair state.

Registering a transaction edge with full numeric features

To get the full compact payload (numeric bins + approximate sum), register the edge type with bin_boundaries. The seven boundaries define eight buckets. tracked_property names the numeric value from ingest that is binned and summed, usually "amount" for payments.

Reading node histograms

graph.histogram returns aggregated bucket counts for one node and one edge type. It is node-level: for CARD → PAYMENT, it counts all PAYMENT edges from that card, not a single merchant edge.

Example output counts = [0, 2, 12, 2, 0, 0, 0, 0] means: 0 events below 5, 2 events in 5–25, 12 events in 25–50, 2 events in 50–100, and none in the higher buckets.

Reading edge state

graph.edgeState reads one edge pair. It is the edge-level complement to graph.histogram. Use it for per-edge features such as tx_count, approx_sum, last_seen, boolean flags, and activity windows.

If PAYMENT.activity_bitmap.tick_size_secs = 300, then [1, 2, 12] asks for counts over the last 5 minutes, 10 minutes, and 1 hour. The bitmap holds at most 21 ticks, so a 5-minute tick gives about 105 minutes of edge-level activity history. Longer windows should come from node histograms.

Data Modeling Best Practices

• Use meaningful, domain-specific labels — CARD, MERCHANT, DEVICE instead of generic names
• Keep relationship types verb-like and directional — TRANSACTS_AT, USES_DEVICE, OWNED_BY
• Identify entities by a stable external ID (e.g., card PAN hash, merchant ID) not internal surrogate keys
• Model shared attributes as nodes, not properties — a shared device should be a DEVICE node that multiple cards point to, not a string property on each card
• Avoid deeply nesting all data in properties — if you query by it, it should be a node or relationship

Querying the Graph — Cypher

JetGraph uses Cypher, the standard graph query language originally developed for Neo4j and now governed by the openCypher specification. If you know SQL, Cypher will feel natural — it uses a similar declarative style but describes patterns in the graph rather than joins between tables.

Basic Patterns

Cypher uses ASCII-art notation to express graph patterns:

• (n:LABEL) — a node with a label
• -[:EDGE_TYPE]-> — a directed relationship
• (a)-[:EDGE]->(b) — node a connected to node b

CREATE — Insert a Node

MATCH — Query Nodes

CREATE — Insert a Relationship

Traversal — Multi-hop Queries

Filtering with WHERE

Parameterized Queries

Always use parameters (prefixed with $) instead of string interpolation to avoid injection and improve query plan reuse:

Aggregations

MERGE — Upsert Nodes and Relationships

MERGE matches an existing pattern or creates it if it does not exist. Use ON CREATE SET and ON MATCH SET to set properties conditionally:

OPTIONAL MATCH

OPTIONAL MATCH works like a left outer join — if the pattern does not exist, the variables are bound to null rather than excluding the row:

WITH — Pipeline and Filter Mid-Query

WITH passes results from one query stage to the next, allowing intermediate filtering, aggregation, and variable re-binding:

UNWIND — Expand a List

UNWIND turns a list into individual rows, which is useful for batch operations driven by a parameter array:

Data Manipulation

Insert Data

Use CREATE to insert new nodes and relationships. Both the source and destination nodes must already exist before creating a relationship.

Update Node Properties

Use SET to update or add properties on an existing node:

Delete a Node

A node must have no relationships before it can be deleted. Use DETACH DELETE to remove both the node and all its relationships in one step:

Delete a Relationship

Bulk Inserts

For bulk data loading, fire multiple POST /cypher requests in parallel. Each request is independent and thread-safe. For maximum throughput from Rust, use the jetgraph-client crate which batches requests over a persistent gRPC connection.

Graph Analysis & Use Cases

Velocity Counting (O(1))

JetGraph pre-computes velocity counts using ring buffers, making time-window queries instant. Query them via the Rust client or via Cypher system procedures:

Fraud Detection Pattern

Graph databases are uniquely effective for fraud detection because fraud rings are defined by connections. A card that shares a device with a flagged card is suspicious — even if the card itself has no prior fraud history.

Ring Fraud Detection (Cypher)

Find cards that share a device with a known-fraudulent card — the classic "fraud ring" pattern:

Recommendation System Pattern

Find merchants popular with other cards that share the same device as the current card — a graph-based collaborative filter:

Performance & Best Practices

Query Optimization Tips

• Always anchor on a specific node first. Start your MATCH with a node that has a known external_id rather than scanning all nodes of a type.
• Use velocity APIs for time-window counts. Do not use COUNT over traversals for time-windowed counts — the pre-computed O(1) velocity API is orders of magnitude faster.
• Prefer shorter paths. Traversals up to 2–3 hops are fast. Deeper unbounded traversals should have a LIMIT to avoid full graph scans.
• Use parameterized queries. This enables query plan reuse across calls with different values.
• Limit result sets. Always add LIMIT to exploratory queries — especially in production where the graph may be large.

Efficient Traversal Patterns

Common Mistakes to Avoid

• Writing data before calling db.finalizeSchema() — all writes will fail
• Forgetting to call CREATE for destination nodes before creating a relationship
• Using string interpolation to build Cypher queries — always use parameters
• Querying without LIMIT on large result sets in production
• Skipping the edge insert when a transaction is declined — this breaks future velocity counts
• Modeling shared attributes (devices, IPs) as string properties instead of nodes — you lose the ability to traverse them

Cypher Best Practices

These rules are derived from direct analysis of the JetGraph query planner logs. Each one maps to a specific engine optimisation — or the absence of one — that has measurable impact at scale. Follow them to keep every query O(1) or close to it.

1. Always label every node in MATCH

The pushdown optimizer converts a WHERE node.external_id = $value filter into an O(1) IndexLookup only when it knows the node type. Without a label the engine produces NodeScan { node_type: None } — a full scan across every node in the graph, repeated once per edge type registered in the schema.

2. Always use parameters — never embed literal values

Literal values baked into the query string each create a unique plan cache key. Every new literal triggers a full parse + plan cycle regardless of how many times a similar query has been run before. Parameters collapse every variation of a query into a single cached plan that is reused for every card ID, merchant ID, device fingerprint, or IP address.

3. Filter on external_id equality on the source node

The pushdown optimizer walks the plan tree and converts Filter(src.external_id = value) → NodeScan into an IndexLookup. This rewrite only fires when the filter is an equality on external_id and applies to the source variable of the expand. Filters on destination properties or on any other property remain as post-expansion filters (slower).

4. Always type every relationship

An untyped relationship -[r]-> causes the engine to fan out the expand across every edge type registered in the schema — one full expand per type. With six edge types registered, a single untyped MATCH compiles into six separate query plans. Always name the relationship type explicitly.

5. Canonical fraud context — the recommended multi-hop template

This is the recommended pattern for pulling the full risk context of a card in a single round-trip: typed nodes, typed relationships, parameterized, one plan cached for every card. Each UNION ALL branch is compiled and optimized independently.

6. Anchor ring / co-occurrence queries on the known node

Shared-entity ring queries (cards sharing a device or IP) must start from a known, typed anchor. An unanchored ring causes a full scan of all devices before expanding to cards. Start from the entity you know.

7. Always add LIMIT to traversals and scans

The engine propagates LIMIT hints down into NodeScan and VariableExpand nodes so BFS stops as soon as enough rows are found. Without a limit, traversals materialise the full result set before returning anything. This is especially important for variable-length paths.

8. Use db.nodeStats() for counts, not MATCH (n:TYPE)

A bare MATCH (n:CARD) RETURN count(n) materialises every node in that type before counting. db.nodeStats() reads a pre-maintained O(1) counter with no scan.

9. Batch writes with graph.ingest()

Individual CREATE statements are planned and executed one at a time. For loading multiple nodes and edges in a single operation, use graph.ingest() — one round-trip, one plan, one atomic batch write regardless of how many entities are included.

10. Record transaction events with graph.upsertEdge()

For high-throughput edge upserts — recording payment events — use graph.upsertEdge() rather than MERGE-based patterns. It is a single O(1) procedure call that increments counters and updates the activity bitmap atomically, with no planner involved.

Quick Reference

Error Handling & Debugging

Common Errors

Debugging with Logs

Testing Connectivity

Persistence & Durability

JetGraph is an in-memory engine — all data lives in RAM for sub-millisecond access. Durability is provided by a layered persistence model that writes to disk asynchronously without pausing query processing.

How Data Survives Restarts

Recovery Sequence at Startup

1. 1

   Load latest full snapshot

   The most recent snapshot-*.bin file is deserialized into memory. The engine is marked ready immediately so queries can start while the Cuckoo filter rebuilds in the background.

2. 2

   Apply checkpoint (if any)

   If a checkpoint file exists for this snapshot base, it is applied first to skip replaying the earliest deltas.

3. 3

   Replay remaining delta files

   Any delta files newer than the checkpoint are applied in order, bringing the graph fully up to date.

Emergency Snapshot (Memory Pressure)

When RSS memory exceeds memory_limit_bytes in config.toml, the engine automatically writes an emergency full snapshot, blocks new ingest, and logs an error. This protects data before the container OOM-killer fires. Ingest resumes once memory drops back below the limit.

Manual Snapshot

Trigger a snapshot on demand via Cypher without restarting:

Graceful Shutdown

Send SIGTERM (what docker compose stop / docker compose down sends) and the engine will write a final delta then a full snapshot before exiting. The stop_grace_period: 300s in the compose file gives it up to 5 minutes for very large graphs. Never use SIGKILL directly — it bypasses the shutdown snapshot.

Clustering & High Availability

JetGraph supports primary–standby clustering for high availability and read scale-out. The primary serves reads and writes; one or more standbys keep a live in-memory replica of the graph and serve reads only. Replication is delta-based and lag is typically under 35 seconds under normal ingest.

Architecture

A cluster is built from three small components running alongside each graphengine process:

What Gets Replicated

• Schema — snapshots include the finalized schema; the standby reloads automatically when a new snapshot arrives.
• Nodes and edges — every CREATE, MERGE, SET, DELETE, and graph.upsertEdge write produces dirty pairs that flow in the next delta file.
• Edge state — velocity counters, activity bitmaps, and histograms are snapshot-bound and travel with the data.
• Fraud flags — graph.flagNode / graph.unflagNode propagate through the normal delta channel.

Segment Evaluator and Pattern Miner sidecars maintain their own config stores; they should run on both hosts but do not participate in graph replication.

Replication Lag

Lag = delta_interval_secs (30 s default) + POLL_INTERVAL_SECS (5 s default) = ~35 seconds upper bound under normal load. For tighter RPO, lower both intervals at the cost of more but smaller delta files. Data loss on an unplanned primary failure is bounded by this window.

Minimum Compose Setup

Clusters use two Compose files. The primary runs the engine plus the replicator sidecar; the standby runs the engine with STANDBY_MODE enabled.

Failover

1. 1

   Drain and stop the primary

   Stop new writes at the load-balancer level, then docker compose stop graphengine. On SIGTERM the engine writes a final delta and full snapshot — up to stop_grace_period (default 300 s).

2. 2

   Wait for the standby to drain the delta queue

   Tail the standby logs until no more applying delta lines appear. At that point the two engines are byte-for-byte equivalent.

3. 3

   Promote the standby

   Restart the engine with STANDBY_MODE removed (or swap in the primary compose file on that host). The data directory is already a full mirror — no migration step.

4. 4

   Cut clients over

   Update DNS or load-balancer config. Optionally reconfigure the old primary as the new standby — point its STANDBY_HOST at the new primary and install the new replication key.

For an unplanned failover (primary host lost), promote the standby immediately. Data loss is bounded by the last delta the standby applied — at most ≈ 35 seconds.

Verifying Replication

Operational Limits

• Standbys are read-only. All writes must go to the primary; any write attempted on a standby returns an error.
• Standbys must not evict independently. Set pressure_eviction_batch_size = 0 on standbys so the replica only deletes edges that arrive in the primary's delta stream.
• Size the standby like the primary. It holds the same in-memory graph — size mem_limit identically and use the same (or slightly lower) memory_limit_bytes.
• No cascading replication. Topology is primary-to-standby. Chained standbys are not supported.

Memory & Compression

JetGraph keeps the entire graph in RAM to guarantee sub-millisecond reads, so every byte is engineered. The engine uses several compression and compaction techniques — trading a few cycles for a much smaller footprint — so a single 96 GiB host can hold hundreds of millions of nodes and billions of edges.

Where Memory Goes

Use db.memoryUsage() for a live, fully-accounted breakdown, or GET /admin/memory for the same payload in JSON:

Per-Pair Edge Compression

Each edge type stores adjacency with a payload variant chosen at registration. Pick the smallest variant that still answers your queries:

At 1 B edges, choosing Static over Full for a structural edge type saves ≈ 36 GiB of RSS — and avoids maintaining an inverse index that is never queried.

Other In-Memory Compression

On-Disk Compression

All snapshots, deltas, and checkpoints are written through zstd. Hot-path writers use level 1 for low CPU overhead; the offline compactor uses the ultra-fast -1 level.

Disk throughput is rarely the bottleneck — delta throughput is CPU-bound on the zstd encoder, not on disk I/O. On NVMe you can ingest 30 MB deltas every 30 seconds with RSS growth matching payload growth within a few percent.

Memory-Pressure Protection

JetGraph never exceeds its configured memory budget silently. memory_limit_bytes in config.toml is the engine's RSS soft limit (set it below the container's mem_limit). When RSS crosses the limit the engine takes one of two actions based on pressure_eviction_batch_size:

Sizing Memory

Size memory_limit_bytes from Docker mem_limit, not from memswap_limit. Swap is an emergency cushion — paging graph pages catastrophically regresses query latency. Start at 70–75 % of mem_limit and only raise after seeing stable headroom in docker stats and db.memoryUsage.

jemalloc Tuning

JetGraph ships with jemalloc as the system allocator because glibc's default fragments badly under high-churn graph writes. Recommended MALLOC_CONF in the container environment:

Watching Memory Metrics

Scrape GET /metrics with any Prometheus-compatible collector:

• jetgraph_memory_pressure — 1 when RSS ≥ memory_limit_bytes, 0 otherwise. Alert on sustained 1.
• jetgraph_rcu_retries_total — RCU retries on the compact neighbor store. A steady climb indicates hot-row write contention — consider sharding by a higher-cardinality source or moving the edge type to is_static.
• jetgraph_inverse_lock_contentions_total — lock contention on the inverse index. Climbs when a destination node crosses 10 K in-neighbours and the adaptive index promotes to a BTreeSet.

Procedures Reference

All procedures are invoked via CALL procedure.name(args) YIELD col1, col2 RETURN ... over any connection (REST, Bolt, or gRPC).

Schema Procedures (db.*)

Graph Procedures (graph.*)

Edge Type Variants

When registering edge types, the storage variant is determined by registration fields. Choose the smallest payload that still answers your feature queries:

Metrics

JetGraph exposes a Prometheus-compatible metrics endpoint at GET /metrics on port 8080. Scrape it with any Prometheus-compatible collector or read it directly:

Segment Evaluator

The Segment Evaluator is a sidecar service that sits in front of the graph engine's ingest path. It evaluates configurable segment rules in real time on every transaction — automatically assigning entities to segments like "High Velocity", "New Merchant Risk", or "Fraud Ring Adjacent" based on graph signals.

How It Works

• You define signals (individual graph metrics — velocity, novelty, fraud proximity) and segments (named groups with threshold rules over signals)
• On every POST /ingest/evaluate call, the evaluator ingests the transaction into the graph engine and re-evaluates which segments the entity belongs to
• Segment membership is stored as MEMBER_OF static edges to a Segment node — queryable via standard Cypher
• Segments persist in a sled key-value store at /data/seg-config and survive restarts
• Configuration can be managed via the API or by editing TOML files (seeded on first boot)

Key API Endpoints (port 8081)

Querying Segments via Cypher

Once segments are assigned, you can query them like any other graph relationship:

Pattern Miner

The Pattern Miner is a sidecar service that watches the graph engine's edge stream in real time and builds behavioral transition patterns — sequences of entities a node visited over time. These patterns power next-location prediction, impossible-travel detection, and anomaly scoring.

How It Works

• You define rules that watch a specific edge type (e.g., USES_IP)
• For each new edge event, the miner calls graph.lastNeighbor to find the previous entity of that type, then writes a transition edge (e.g., NEXT_IP) capturing the sequence
• Transition contexts accumulate in an in-memory PatternStore and are persisted in a sled store at /data/pm-config
• The /patterns/predict/:node_id endpoint returns the most probable next entity based on historical transitions

Key API Endpoints (port 8082)

Impossible-Travel Detection Example

Code Examples Reference

Copy-paste-ready snippets for common operations.

REST API — Full Workflow

Bolt — Python

Rust Client — Complete Scoring Loop