Rust API

The relate crate is the engine as a Rust library: a Database opens a storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary, a Connection runs statements on it, and each statement returns a QueryResult of Value rows or a relate::Error. This page lists what the crate exports at its root (every name is relate::<name>), as of relate 0.1.2. The C application binary interface (ABI) and the Python client are built on the same Database. The guide Use the Rust crate covers the same API with runnable programs.

Synopsis

use relate::{Database, OpenOptions, Value};

Database::open(uri) -> Result<Database>
Database::open_with(uri, OpenOptions) -> Result<Database>
Database::clone(source, dest, CloneOptions) -> Result<()>
db.connect() -> Result<Connection>
conn.query(cypher) -> Result<QueryResult>
conn.query_with_params(cypher, BTreeMap<String, Value>) -> Result<QueryResult>
conn.begin() -> Result<()>
conn.commit() -> Result<Option<String>>
conn.rollback() -> Result<()>
relate::error_info(&Error) -> ErrorInfo

relate::Result<T> is std::result::Result<T, relate::Error>. A uri is ":memory:", a filesystem path or a file:// URI: a path ending in .rl (or the legacy .cl) is a single-file storesingle-file store A store kept in one .rl file that holds the snapshot and the WAL together; the layout for a --database path ending in .rl. Read more in the glossary, any other path a directory store. An s3:// URI is refused at open.

Cargo features

The crate is relate, in the workspace at version 0.1.2, with rust-version 1.88 and edition 2021. Before crates.io publication it is a Git dependency, cargo add --git https://github.com/relatedb/relate relate.

Database

An open store. Database is Send and Sync; dropping it stops the background checkpoint and durability threads, and a Connection still alive keeps the store open.

OpenOptions

The settings of Database::open_with, a struct with public fields and Default. OpenOptions::with_mode(mode) is the default with mode set. An Option field left None reads the environment variable its Default cell names, then takes the default; wal_dir and load_csv_max_bytes read none. A set variable that does not parse fails the open.

CloneOptions holds wal_dir (a directory source's WAL; refused for a .rl source), to_snapshot_format (transcode the copy to another codec; default keeps the source's) and markdown_body_properties.

Connection

One session on a Database. Connection is Send but not Sync; every method that runs a statement takes &mut self.

QueryResult

QueryResult.header is a ResultHeader, the metadata every statement announces; a staged run's ExecutionFailure carries the same struct. Its public fields are columns, column_types, query_type, namespace and elapsed; its phase timings and plan-cache outcome are read through the QueryResult methods.

Value

A parameter or a result cell. Value is Send, Sync and Clone; strings, lists, maps, vectors and byte arrays share their payload behind an Arc, so a clone never copies it.

Temporal::CivilDate and Temporal::CivilDateTime hold dates outside the range of the standard date types. node_element_id, rel_element_id, parse_node_element_id and parse_rel_element_id convert between numeric ids and element idselement id The string elementId() returns for a node or relationship, such as 4:relate-neo4j:n0; it stays the same when the store is closed and opened again. Read more in the glossary, the strings elementId() returns.

Errors

relate::Error is an enum; its Display is the message every surface prints. error_info(&e) returns ErrorInfo { neo4j_code, gql_status, stage, retryable }, the one classification that the CLI, Python, the C ABI, Bolt, and HTTP all derive from. stage is an ErrorStage: Compile (rejected before any work), Runtime (found while producing rows) or Internal (not the statement's fault).

The gql_status shown for Syntax, Semantic and Execution is the default: a payload naming a more specific class carries that class's code, such as 42N18 for semantic error: WriteOnReadOnlyAccessDatabase: …. Error::WAL_PAYLOAD_CAP_BYTES is 64 MiB, the largest single commit record. ResourceLimit names are the constants Error::CONCURRENT_LOGICAL_WORKSPACE_LIMIT, Error::WRITER_DRAINING and Error::FOLLOW_GAP. A write-write conflict is never retried by the engine. The errors reference lists the messages with their causes and remedies.

Plans and notifications

notification_to_wire_json, notifications_to_wire_json and notification_to_neo4j_json serialize notifications as the other surfaces send them. The notifications reference lists the codes.

Staged runs

Upstream documents these entry points for network transports, which report planning failures and execution failures at different points; relate's Bolt server is their in-tree user.

Other root exports

Limits

The limits come from the engine and are the same on every surface: a statement's text is at most 4194304 bytes (syntax error: query text of <n> bytes exceeds the maximum query size of 4194304 bytes), one value a statement builds is bounded by the expression memory cap, and a file-backed store has one writing open across every process. Limits and sizing lists each limit with its default and the setting that changes it.

Capabilities

Example

This program writes the team graph to an in-memory store, reads it back with a parameter, and classifies an error:

use std::collections::BTreeMap;

use relate::{error_info, Database, Error, Value};

const TEAM: &str = "
CREATE (ada:Person {name: 'Ada', role: 'engineer'}),
       (grace:Person {name: 'Grace', role: 'engineer'}),
       (noor:Person {name: 'Noor', role: 'maintainer'}),
       (relate:Project {name: 'relate', language: 'Rust'}),
       (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}),
       (ada)-[:WORKS_ON {since: 2024}]->(relate),
       (grace)-[:WORKS_ON {since: 2023}]->(relate),
       (grace)-[:WORKS_ON {since: 2022}]->(tck),
       (noor)-[:MAINTAINS]->(relate),
       (ada)-[:KNOWS]->(grace)";

fn main() -> relate::Result<()> {
    let db = Database::open(":memory:")?;
    let mut conn = db.connect()?;
    conn.query(TEAM)?;

    let params = BTreeMap::from([("name".to_string(), Value::String("Grace".into()))]);
    let result = conn.query_with_params(
        "MATCH (p:Person {name: $name})-[w:WORKS_ON]->(proj:Project) \
         RETURN proj.name AS project, w.since AS since ORDER BY since",
        params,
    )?;
    println!("{:?} {:?} {}", result.header.columns, result.header.column_types,
        result.header.query_type.as_str());
    for row in &result.rows {
        println!("{row:?}");
    }

    let err = conn.query("RETURN 1 / 0 AS x").unwrap_err();
    let info = error_info(&err);
    println!("{err:?}: {err}");
    println!("{} {} {:?} {}", info.neo4j_code, info.gql_status, info.stage, info.retryable);
    println!("conflict retryable: {}", error_info(&Error::Conflict).retryable);
    Ok(())
}

["project", "since"] ["STRING", "INTEGER"] r
[String("opencypher-tck"), Int(2022)]
[String("relate"), Int(2023)]
Arithmetic(DivisionByZero): type error: / by zero
Neo.ClientError.Statement.ArithmeticError 22G03 Runtime false
conflict retryable: true

See also

• Use the Rust crate: the same API, task by task, with runnable programs.
• C ABI: the library the Node.js, Java, Go and Swift clients wrap, over this crate.
• Errors: every message with its cause and remedy.
• Storage formats: what each store layout and codec writes to disk.
• Choose a durability mode: the loss window of each DurabilityMode.
• Embedded graph in an app: the problem the crate solves.