xrayGraphDB Documentation

# Pull and run xrayGraphDB
docker run -d \
  --name xraygraphdb \
  -p 7687:7687 \
  -p 7689:7689 \
  -v xraydata:/data \
  xraygraphdb:4.0.2

version: "3.8"
services:
  xraygraphdb:
    image: xraygraphdb:4.0.2
    ports:
      - "7687:7687"   # Bolt
      - "7689:7689"   # xrayProtocol
    volumes:
      - xraydata:/data
    environment:
      - XRAY_DATA_DIRECTORY=/data
      - XRAY_LOG_LEVEL=INFO
      - XRAY_SNAPSHOT_ON_EXIT=true
    restart: unless-stopped

volumes:
  xraydata:

docker compose up -d
docker compose logs -f xraygraphdb

# Check container status
docker ps --filter name=xraygraphdb

# Check logs for startup confirmation
docker logs xraygraphdb | grep "listening"
# Expected: "Bolt server listening on 0.0.0.0:7687"
#           "xrayProtocol server listening on 0.0.0.0:7689"

# Download
wget https://releases.emtailabs.com/xraygraphdb/xraygraphdb-4.0.2-linux-amd64.tar.gz

# Extract
tar xzf xraygraphdb-4.0.2-linux-amd64.tar.gz
cd xraygraphdb-4.0.2

# Start the server
./bin/xraygraphdb-wrapper

# Server listens on:
#   Bolt      -> :7687
#   xrayProto -> :7689

# /etc/systemd/system/xraygraphdb.service
[Unit]
Description=xrayGraphDB Graph Database
After=network.target

[Service]
Type=simple
User=xraygraph
ExecStart=/opt/xraygraphdb/bin/xraygraphdb-wrapper \
  --data-directory=/var/lib/xraygraphdb \
  --log-level=INFO
ExecStop=/bin/kill -SIGTERM $MAINPID
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable xraygraphdb
sudo systemctl start xraygraphdb
sudo systemctl status xraygraphdb

# Download macOS binary (Apple Silicon or Intel)
curl -LO https://releases.emtailabs.com/xraygraphdb/xraygraphdb-4.0.2-macos-arm64.tar.gz

# Extract and run
tar xzf xraygraphdb-4.0.2-macos-arm64.tar.gz
cd xraygraphdb-4.0.2
./bin/xraygraphdb-wrapper

pip install neo4j

from neo4j import GraphDatabase

driver = GraphDatabase.driver(
    "bolt://localhost:7687",
    auth=("admin", "<your-password>")
)

with driver.session() as session:
    # Create a node
    session.run(
        "CREATE (n:Person {name: $name, age: $age})",
        name="Alice", age=30
    )

    # Read it back
    result = session.run(
        "MATCH (n:Person {name: $name}) RETURN n.name, n.age",
        name="Alice"
    )
    record = result.single()
    print(record["n.name"], record["n.age"])
    # Output: Alice 30

driver.close()

npm install neo4j-driver

const neo4j = require('neo4j-driver');

const driver = neo4j.driver(
  'bolt://localhost:7687',
  neo4j.auth.basic('admin', '<your-password>')
);

const session = driver.session();

try {
  // Create a node
  await session.run(
    'CREATE (n:Person {name: $name, age: $age})',
    { name: 'Bob', age: 25 }
  );

  // Read it back
  const result = await session.run(
    'MATCH (n:Person {name: $name}) RETURN n',
    { name: 'Bob' }
  );

  console.log(result.records[0].get('n').properties);
} finally {
  await session.close();
  await driver.close();
}

<!-- Maven dependency -->
<dependency>
  <groupId>org.neo4j.driver</groupId>
  <artifactId>neo4j-java-driver</artifactId>
  <version>5.x</version>
</dependency>

import org.neo4j.driver.*;

public class XRayExample {
    public static void main(String[] args) {
        var driver = GraphDatabase.driver(
            "bolt://localhost:7687",
            AuthTokens.basic("admin", "<your-password>")
        );

        try (var session = driver.session()) {
            session.run(
                "CREATE (n:Person {name: $name})",
                Values.parameters("name", "Carol")
            );

            var result = session.run(
                "MATCH (n:Person) RETURN n.name"
            );

            while (result.hasNext()) {
                System.out.println(result.next().get("n.name").asString());
            }
        }
        driver.close();
    }
}

go get github.com/neo4j/neo4j-go-driver/v5

package main

import (
    "context"
    "fmt"
    "github.com/neo4j/neo4j-go-driver/v5/neo4j"
)

func main() {
    ctx := context.Background()

    driver, err := neo4j.NewDriverWithContext(
        "bolt://localhost:7687",
        neo4j.BasicAuth("admin", "<your-password>", ""),
    )
    if err != nil { panic(err) }
    defer driver.Close(ctx)

    session := driver.NewSession(ctx, neo4j.SessionConfig{})
    defer session.Close(ctx)

    _, err = session.Run(ctx,
        "CREATE (n:Person {name: $name})",
        map[string]any{"name": "Dave"},
    )
    if err != nil { panic(err) }

    result, err := session.Run(ctx,
        "MATCH (n:Person) RETURN n.name", nil,
    )
    if err != nil { panic(err) }

    for result.Next(ctx) {
        fmt.Println(result.Record().Values[0])
    }
}

dotnet add package Neo4j.Driver

using Neo4j.Driver;

var driver = GraphDatabase.Driver(
    "bolt://localhost:7687",
    AuthTokens.Basic("admin", "<your-password>")
);

await using var session = driver.AsyncSession();

await session.RunAsync(
    "CREATE (n:Person {name: $name})",
    new { name = "Eve" }
);

var result = await session.RunAsync(
    "MATCH (n:Person) RETURN n.name"
);

var records = await result.ToListAsync();
foreach (var record in records)
{
    Console.WriteLine(record["n.name"].As<string>());
}

await driver.DisposeAsync();

// Step 1: Create some nodes
CREATE (alice:Person {name: "Alice", age: 30})
CREATE (bob:Person {name: "Bob", age: 25})
CREATE (carol:Person {name: "Carol", age: 35})
CREATE (proj:Project {name: "xrayGraphDB"})
RETURN alice, bob, carol, proj;

// Step 2: Create relationships
MATCH (a:Person {name: "Alice"}), (b:Person {name: "Bob"})
CREATE (a)-[:KNOWS]->(b)
RETURN a, b;

MATCH (a:Person {name: "Alice"}), (p:Project {name: "xrayGraphDB"})
CREATE (a)-[:WORKS_ON {role: "lead"}]->(p)
RETURN a, p;

MATCH (b:Person {name: "Bob"}), (p:Project {name: "xrayGraphDB"})
CREATE (b)-[:WORKS_ON {role: "contributor"}]->(p)
RETURN b, p;

// Step 3: Query the graph
MATCH (p:Person)-[:WORKS_ON]->(proj:Project)
RETURN p.name, proj.name;

// Step 4: Update properties
MATCH (a:Person {name: "Alice"})
SET a.email = "alice@example.com"
RETURN a;

// Step 5: Clean up
MATCH (n) DETACH DELETE n;

// Match all nodes with a specific label
MATCH (n:Person)
RETURN n;

// Match a relationship pattern
MATCH (a:Person)-[:KNOWS]->(b:Person)
RETURN a.name, b.name;

// Match with relationship variable
MATCH (a:Person)-[r:WORKS_ON]->(p:Project)
RETURN a.name, r.role, p.name;

// Match any direction
MATCH (a:Person)-[:KNOWS]-(b:Person)
RETURN a.name, b.name;

// Match with multiple labels
MATCH (n:Person:Employee)
RETURN n;

// Comparison operators
MATCH (n:Person)
WHERE n.age > 25 AND n.age <= 40
RETURN n.name, n.age;

// String matching
MATCH (n:Person)
WHERE n.name STARTS WITH "A"
RETURN n;

// Regular expression
MATCH (n:Person)
WHERE n.email =~ ".*@example\\.com"
RETURN n;

// Null checks
MATCH (n:Person)
WHERE n.email IS NOT NULL
RETURN n;

// IN list
MATCH (n:Person)
WHERE n.name IN ["Alice", "Bob", "Carol"]
RETURN n;

// Pattern predicates (exists)
MATCH (n:Person)
WHERE (n)-[:WORKS_ON]->()
RETURN n.name;

// Return specific properties
MATCH (n:Person)
RETURN n.name, n.age;

// Alias with AS
MATCH (n:Person)
RETURN n.name AS person_name, n.age AS years;

// Return all properties as a map
MATCH (n:Person)
RETURN properties(n);

// Return distinct values
MATCH (n:Person)-[:WORKS_ON]->(p:Project)
RETURN DISTINCT p.name;

// Expressions in RETURN
MATCH (n:Person)
RETURN n.name, n.age * 12 AS age_in_months;

// Order by a property
MATCH (n:Person)
RETURN n.name, n.age
ORDER BY n.age DESC;

// Limit results
MATCH (n:Person)
RETURN n.name
ORDER BY n.name
LIMIT 10;

// Pagination with SKIP and LIMIT
MATCH (n:Person)
RETURN n.name
ORDER BY n.name
SKIP 20
LIMIT 10;

// Multiple sort keys
MATCH (n:Person)
RETURN n.name, n.age
ORDER BY n.age DESC, n.name ASC;

// Filter intermediate results
MATCH (p:Person)-[:WORKS_ON]->(proj:Project)
WITH proj, count(p) AS team_size
WHERE team_size > 3
RETURN proj.name, team_size
ORDER BY team_size DESC;

// Chain queries
MATCH (n:Person)
WITH n
ORDER BY n.age DESC
LIMIT 5
MATCH (n)-[:KNOWS]->(friend)
RETURN n.name, collect(friend.name) AS friends;

// Expand a list
UNWIND [1, 2, 3] AS x
RETURN x;

// Bulk create from parameters
UNWIND $people AS person
CREATE (n:Person {name: person.name, age: person.age});

// Combine with MATCH
UNWIND ["Alice", "Bob"] AS name
MATCH (n:Person {name: name})
RETURN n;

// Return all people, even those without projects
MATCH (p:Person)
OPTIONAL MATCH (p)-[:WORKS_ON]->(proj:Project)
RETURN p.name, proj.name;

// Create a single node
CREATE (n:Person {name: "Frank", age: 28})
RETURN n;

// Create multiple nodes
CREATE (a:Person {name: "Grace"}),
       (b:Person {name: "Hank"});

// Create a node with multiple labels
CREATE (n:Person:Developer {name: "Ivy"});

// Create a relationship between existing nodes
MATCH (a:Person {name: "Grace"}), (b:Person {name: "Hank"})
CREATE (a)-[:KNOWS {since: 2024}]->(b)
RETURN a, b;

// Create a full path in one statement
CREATE (a:Module {name: "auth"})-[:IMPORTS]->(b:Module {name: "crypto"})
RETURN a, b;

// Merge a node (create if not exists)
MERGE (n:Person {name: "Alice"})
ON CREATE SET n.created = timestamp()
ON MATCH SET n.lastSeen = timestamp()
RETURN n;

// Merge a relationship
MATCH (a:Person {name: "Alice"}), (b:Person {name: "Bob"})
MERGE (a)-[r:KNOWS]->(b)
ON CREATE SET r.since = 2024
RETURN r;

// Set a property
MATCH (n:Person {name: "Alice"})
SET n.age = 31
RETURN n;

// Set multiple properties
MATCH (n:Person {name: "Alice"})
SET n.age = 31, n.email = "alice@example.com"
RETURN n;

// Replace all properties with a map
MATCH (n:Person {name: "Alice"})
SET n = {name: "Alice", age: 31, active: true}
RETURN n;

// Merge properties (add without removing existing)
MATCH (n:Person {name: "Alice"})
SET n += {department: "engineering"}
RETURN n;

// Add a label
MATCH (n:Person {name: "Alice"})
SET n:Employee
RETURN n;

// Remove a property
MATCH (n:Person {name: "Alice"})
REMOVE n.email
RETURN n;

// Remove a label
MATCH (n:Person:Employee {name: "Alice"})
REMOVE n:Employee
RETURN labels(n);

// Delete a relationship
MATCH (a:Person)-[r:KNOWS]->(b:Person)
WHERE a.name = "Alice" AND b.name = "Bob"
DELETE r;

// Delete a node (must have no relationships)
MATCH (n:Person {name: "Frank"})
DELETE n;

// Detach delete (node + all relationships)
MATCH (n:Person {name: "Alice"})
DETACH DELETE n;

// Delete all nodes and relationships in the database
MATCH (n) DETACH DELETE n;

// Paths of exactly 2 hops
MATCH (a:Person)-[:KNOWS*2]->(c:Person)
RETURN a.name, c.name;

// Paths of 1 to 5 hops
MATCH (a:Person)-[:KNOWS*1..5]->(c:Person)
RETURN a.name, c.name;

// Paths of any length (use with caution)
MATCH (a:Person {name: "Alice"})-[:KNOWS*]->(c:Person)
RETURN DISTINCT c.name;

// Capture the path
MATCH path = (a:Person {name: "Alice"})-[:KNOWS*1..3]->(c:Person)
RETURN path, length(path) AS hops;

// Find one shortest path
MATCH (a:Person {name: "Alice"}),
      (b:Person {name: "Eve"})
MATCH p = shortestPath((a)-[*..10]-(b))
RETURN p, length(p) AS hops;

// Find all shortest paths (same length)
MATCH (a:Person {name: "Alice"}),
      (b:Person {name: "Eve"})
MATCH p = allShortestPaths((a)-[*..10]-(b))
RETURN p;

// With relationship type filter
MATCH (a:Person {name: "Alice"}),
      (b:Person {name: "Eve"})
MATCH p = shortestPath((a)-[:KNOWS|WORKS_WITH*..10]-(b))
RETURN p;

// BFS with upper bound
MATCH (start:Person {name: "Alice"})
MATCH path = (start)-[:KNOWS BFS]->(target)
RETURN target.name, length(path) AS distance
ORDER BY distance;

// Count
MATCH (n:Person)
RETURN count(n) AS total_people;

// Group and count
MATCH (p:Person)-[:WORKS_ON]->(proj:Project)
RETURN proj.name, count(p) AS team_size
ORDER BY team_size DESC;

// Sum, average, min, max
MATCH (n:Person)
RETURN
  sum(n.age) AS total_age,
  avg(n.age) AS avg_age,
  min(n.age) AS youngest,
  max(n.age) AS oldest;

// Collect into a list
MATCH (p:Person)-[:WORKS_ON]->(proj:Project)
RETURN proj.name, collect(p.name) AS members;

// Standard deviation and percentile
MATCH (n:Person)
RETURN
  stDev(n.age) AS std_dev,
  percentileCont(n.age, 0.5) AS median;

// Create a label-property index
CREATE INDEX ON :Person(name);

// Neo4j-compatible named index syntax
CREATE INDEX person_name_idx
FOR (n:Person)
ON (n.name);

// Composite index
CREATE INDEX ON :Person(name, age);

// Drop an index
DROP INDEX ON :Person(name);

// Unique constraint
CREATE CONSTRAINT ON (n:Person) ASSERT n.email IS UNIQUE;

// Existence constraint
CREATE CONSTRAINT ON (n:Person) ASSERT EXISTS (n.name);

// Show index info
SHOW INDEX INFO;

// List all constraints
SHOW CONSTRAINT INFO;

with driver.session() as session:
    tx = session.begin_transaction()
    try:
        tx.run("CREATE (a:Account {id: $id, balance: $bal})",
               id="A001", bal=1000)
        tx.run("CREATE (a:Account {id: $id, balance: $bal})",
               id="A002", bal=500)
        tx.commit()
    except Exception:
        tx.rollback()
        raise

// Explicit transaction commands (Bolt protocol)
BEGIN;
CREATE (n:Temp {data: "test"});
COMMIT;

// Or rollback
BEGIN;
CREATE (n:Temp {data: "test"});
ROLLBACK;

// String function examples
RETURN
  toLower("Hello World") AS lower,
  split("one:two:three", ":") AS parts,
  replace("foo-bar-baz", "-", "_") AS replaced,
  substring("xrayGraphDB", 4) AS suffix;

// List comprehension
WITH [1, 2, 3, 4, 5] AS nums
RETURN [x IN nums WHERE x > 2 | x * 10] AS result;
// result: [30, 40, 50]

// Reduce
RETURN reduce(total = 0, x IN [1, 2, 3, 4] | total + x) AS sum;
// sum: 10

// Extract nodes from a path
MATCH p = (a:Person)-[:KNOWS*1..3]->(b:Person)
RETURN [n IN nodes(p) | n.name] AS names;

// Store a timestamp
CREATE (e:Event {name: "deploy", ts: timestamp()});

// Query by time range
MATCH (e:Event)
WHERE e.ts > timestamp() - 86400000
RETURN e.name, e.ts
ORDER BY e.ts DESC;

// Duration arithmetic
RETURN datetime() + duration({hours: 3}) AS three_hours_later;

// Generate and store an embedding
MATCH (n:Document {title: "README"})
SET n.vec = EMBED("Getting started guide for xrayGraphDB")
RETURN n;

// Cosine similarity search
MATCH (n:Document)
WHERE cosine_similarity(n.vec, EMBED("installation guide")) > 0.75
RETURN n.title,
       cosine_similarity(n.vec, EMBED("installation guide")) AS score
ORDER BY score DESC
LIMIT 10;

// Set context to all Function nodes
SET GFQL_CONTEXT label='Function';

// Set context with edge filter
SET GFQL_CONTEXT label='Module', edge_type='IMPORTS';

// Set context with property filter
SET GFQL_CONTEXT label='Person', WHERE age > 25;

// Find high-complexity functions and their callees
chain()
  .n(label='Function')
  .filter(complexity > 10)
  .e_forward(type='CALLS')
  .select('source.name', 'target.name');

// Multi-hop traversal
chain()
  .n(label='Module', name='auth')
  .hop(edge_type='IMPORTS', depth=3)
  .select('name', '_hop_depth');

// Aggregate by module
chain()
  .n(label='Function')
  .aggregate(by='module', count='name', avg_complexity='complexity');

# Unencrypted
bolt://localhost:7687

# With TLS (if server has cert configured)
bolt+s://xraygraphdb.example.com:7687

# Neo4j scheme (resolves to bolt://)
neo4j://localhost:7687

# xrayProtocol URI
xray://localhost:7689

Client                           Server
  |                                  |
  |------ HELLO (auth) ------------>|
  |<----- WELCOME (version) --------|
  |                                  |
  |------ RUN (query, params) ----->|
  |<----- COLUMNS (metadata) -------|
  |<----- CHUNK (data batch 1) -----|
  |<----- CHUNK (data batch 2) -----|
  |<----- ...                       |
  |<----- DONE (summary) -----------|
  |                                  |
  |------ RUN (next query) -------->|
  |<----- ...                       |
  |                                  |
  |------ GOODBYE ----------------->|
  |<----- GOODBYE ------------------|
  |                                  |

# Command-line
./bin/xraygraphdb-wrapper --bolt-port=7687 --data-directory=/data

# Environment variable equivalent
export XRAY_BOLT_PORT=7687
export XRAY_DATA_DIRECTORY=/data
./bin/xraygraphdb-wrapper

/var/lib/xraygraphdb/
  snapshots/
    snapshot-20260401T120000.bin
    snapshot-20260401T115500.bin
    snapshot-20260401T115000.bin
  wal/
    wal-000001.bin
    wal-000002.bin

# Limit container to 16 GB
docker run -d \
  --name xraygraphdb \
  --memory=16g \
  -p 7687:7687 \
  xraygraphdb:4.0.2

// Create a new user
CREATE USER analyst IDENTIFIED BY "<strong-password>";

// Change a user's password
ALTER USER analyst SET PASSWORD "<new-password>";

// Drop a user
DROP USER analyst;

// List all users
SHOW USERS;

// Create a role
CREATE ROLE analyst;

// Grant read access on all labels
GRANT READ ON LABELS * TO analyst;

// Grant read access on specific label
GRANT READ ON LABELS :Person TO analyst;

// Deny write access
DENY WRITE ON LABELS * TO analyst;

// Assign a role to a user
SET ROLE FOR analyst_user TO analyst;

// Revoke a permission
REVOKE READ ON LABELS :Secret FROM analyst;

// Show all roles and their privileges
SHOW PRIVILEGES;

// Drop a role
DROP ROLE analyst;

# Validate a license key file
xraygraph-admin --validate-license /path/to/license.json

# Reset admin password (requires auth token from first-start log)
xraygraph-admin \
  --admin-reset \
  --auth-token=1711929600 \
  --data-directory=/var/lib/xraygraphdb

# Verify data integrity
xraygraph-admin \
  --verify-integrity \
  --auth-token=1711929600 \
  --data-directory=/var/lib/xraygraphdb

# Attempt repair of corrupted data
xraygraph-admin \
  --repair \
  --auth-token=1711929600 \
  --data-directory=/var/lib/xraygraphdb

# Trigger a snapshot first
# (connect via driver and run)
# FREE MEMORY;  -- triggers GC + snapshot

# Then copy the latest snapshot
cp /var/lib/xraygraphdb/snapshots/snapshot-latest.bin \
   /backup/xraygraphdb-$(date +%Y%m%d).bin

# Stop the server (creates exit snapshot)
sudo systemctl stop xraygraphdb

# Copy the entire data directory
cp -r /var/lib/xraygraphdb /backup/xraygraphdb-$(date +%Y%m%d)

# Restart
sudo systemctl start xraygraphdb

# Stop the server
sudo systemctl stop xraygraphdb

# Replace data directory with backup
rm -rf /var/lib/xraygraphdb
cp -r /backup/xraygraphdb-20260401 /var/lib/xraygraphdb

# Restart (will load the restored snapshot)
sudo systemctl start xraygraphdb

./bin/xraygraphdb-wrapper \
  --license-key=/path/to/license.json \
  --organization-name="Your Company"

xraygraph-admin --validate-license /path/to/license.json
# Output:
#   Organization: Your Company
#   Expires:      2027-04-01
#   Features:     ha, encryption, rbac
#   Signature:    VALID

{
  "organization": "Your Company",
  "issued": "2026-04-01T00:00:00Z",
  "expires": "2027-04-01T00:00:00Z",
  "features": ["ha", "encryption", "rbac"],
  "signature": "<ed25519-signature>"
}

# Using APOC in Neo4j to export Cypher statements
# Run inside Neo4j Browser:
# CALL apoc.export.cypher.all("/export/data.cypher", {})

# Or use neo4j-admin
neo4j-admin database dump neo4j --to-path=/export/

from neo4j import GraphDatabase

driver = GraphDatabase.driver(
    "bolt://localhost:7687",
    auth=("admin", "<your-password>")
)

with open("data.cypher") as f:
    statements = f.read().split(";")

with driver.session() as session:
    for stmt in statements:
        stmt = stmt.strip()
        if stmt:
            session.run(stmt)

driver.close()
print("Import complete")