Grafeo Documentation

Grafeo is a high-performance, embeddable graph database written in Rust. It is designed for speed and low memory consumption, supporting both Labeled Property Graph (LPG) and Resource Description Framework (RDF) data models.

It can be used as an embedded library with zero external dependencies (no JVM, Docker, or external processes required) or as a standalone server. It provides full ACID transactions via MVCC with snapshot isolation.

Grafeo provides several ways to extend its core functionality depending on your requirements. You can customize the database behavior through the following mechanisms:

• Plugins: Used to add custom functions, algorithms, and third-party integrations.
• Storage Backends: Used to implement custom storage engines for managing data persistence.
• Custom Functions: Used to add user-defined functions (UDFs) directly to the Graph Query Language (GQL).
• Rust Extensions: Used to extend the database engine using native Rust code for high-performance requirements.

Grafeo's functionality is distributed across several crates. The primary entry points for users are grafeo and grafeo-engine.

• grafeo: The main crate for interacting with the database.
• grafeo-engine: The database facade and engine logic.

Other specialized crates include:

• grafeo-common: Foundation types.
• grafeo-core: Core data structures.
• grafeo-adapters: Parsers and storage adapters.

The grafeo-server is a standalone HTTP server and web UI that wraps the Grafeo engine in a REST API, GQL Wire Protocol (gRPC), and Bolt v5.x wire protocol. It transforms the embeddable Grafeo library into a full database server.

Key capabilities include:

• Multi-language support: GQL, Cypher, GraphQL, Gremlin, SPARQL, and SQL/PGQ.
• Search API: Vector (KNN/HNSW), text (BM25), and hybrid search.
• Admin API: Database stats, WAL management, integrity validation, and index management.
• ACID transactions: Session-based lifecycle with auto-commit or explicit modes.
• Web UI (Studio): For interactive query exploration.
• Protocols: REST (HTTP), GQL Wire Protocol (gRPC on port 7688), and Bolt v5.x (port 7687) for Neo4j driver compatibility.

Grafeo provides three distinct storage modes depending on your requirements for durability and performance:

• In-Memory Mode: Offers the fastest performance but provides no durability. Ideal for unit testing, temporary data, or caching.
• Persistent Storage: Provides full durability with Write-Ahead Logging (WAL) and checkpointing. This is the recommended mode for production workloads.
• Compact Mode: An in-memory mode optimized for the fastest possible reads. It is suitable for read-only analytics or WASM-based environments where data does not need to be persisted.

The Python examples demonstrate several key Grafeo features:

• Graph Visualization (graph_visualization.py): Uses anywidget-graph for interactive visualization. Covers node/edge creation, pattern matching, PageRank, Louvain community detection, and shortest path analysis.
• Vector Search (vector_search.py): Demonstrates vector similarity search (cosine similarity), hybrid search (vectors + filters), and PCA projection for 3D visualization using anywidget-vector.
• Fraud Detection (fraud_detection.py): Shows how to build transaction graphs, detect suspicious patterns, run ring detection algorithms, and apply risk scoring via PageRank.
• NetworkX Integration (networkx_integration.py): Demonstrates bidirectional data flow between Grafeo and NetworkX, including converting Grafeo graphs to NetworkX for use with NetworkX algorithms and matplotlib visualization.

The Python API for Grafeo is organized into several functional areas:

• Database Operations: Creating and configuring database instances.
• Working with Nodes: CRUD operations (Create, Read, Update, Delete) for nodes.
• Working with Edges: Managing relationships between nodes.
• Transactions: Managing transaction lifecycles and isolation levels.
• Query Results: Handling and iterating over data returned from queries.

The Grafeo Go bindings provide access to the following capabilities:

• Query Languages: Support for GQL, Cypher, SPARQL, Gremlin, and GraphQL.
• CRUD Operations: Full node and edge management including properties.
• Transactions: ACID transactions with configurable isolation levels.
• Vector Search: HNSW vector similarity search.
• Indexing: Property indexes for high-performance lookups.
• Concurrency: Thread-safe operations for concurrent use.

Grafeo implements the GQL (Graph Query Language) standard, targeting minimum conformance (ISO/IEC 39075:2024) while providing a broad set of optional features.

For tool integration (e.g., using GraphGlot), a machine-readable compliance matrix is available as gql-dialect.json. You can regenerate this file using the following command:

python scripts/gql-conformance.py dialect