C ABI

The C application binary interface (ABI) is the header relate.h and the library librelate_ffi: opaque handles for a database, a connection, a result, a value and a parameter builder, and 81 functions over them. The ABI version is 2, and relate_abi_version() returns it. The Node.js, Java, Go and Swift clientsclient A language package that runs the relate engine inside a program's process: the Python, Node.js, Rust, Java, Go and Swift clients. Read more in the glossary wrap this library, and the library wraps the Rust crate's Database. The header is the contract; this page groups its declarations as of relate 0.1.2. The guide Use the C ABI covers the same calls with runnable programs.

Synopsis

#include "relate.h"

relate_database_open(uri, &db, &err)              -> relate_status
relate_connect_namespace(db, NULL, &conn, &err)   -> relate_status
relate_query_params(conn, cypher, params, &r, &err) -> relate_status
  relate_result_is_error(r) ? relate_result_error_json(r)
                            : relate_value_at(r, row, col) -> relate_value
relate_destroy_result(r)
relate_disconnect(conn)
relate_database_close(db)

Each release attaches a relate-ffi-<target>.tar.gz archive per platform (aarch64-apple-darwin, x86_64-apple-darwin, aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu, x86_64-pc-windows-msvc) holding include/relate.h and the static and shared libraries. A program links with -lrelate_ffi. After the first public release the ABI changes only by addition; a version bump means symbols were removed or signatures changed.

Types

Error shape

Every failure carries one JSON object, delivered with the call that failed. There is no thread-local error slot, so a call on a worker thread reports its own error.

{"code":"Neo.ClientError.Statement.ArithmeticError","gql_status":"22G03","stage":"runtime","retryable":false,"message":"type error: / by zero"}

An error_json out-param is written only on failure; NULL in its place drops the detail, and the status alone reports the failure. The classification comes from the engine's one table, the same one the CLI, the clients, Bolt, and HTTP use. With RELATE_FFI_LOG=1 set in the environment (read once per process), the original message of an internal failure goes to the host's stderr, prefixed ffi internal error: .

Lifecycle

Statements and transactions

A bookmarkbookmark The marker a commit returns, relate:<n>, naming its place in the store's commit sequence; returned by the clients and over Bolt. Read more in the glossary is relate:<n>, n being the store's commit sequence across every connection and surface. Bookmarks order by the parsed n, not as strings: as strings, relate:10 sorts before relate:9.

Results

Every string a result or value accessor returns belongs to the result and lives until relate_destroy_result. A NULL result gives 0, 0.0 or NULL; an error result gives NULL from the string accessors, 0.0 from the timings and 0 rows.

The plan document is {schema, profiled, statement, root}. Each node holds operator, details, identifiers, estimated_rows (or null), actual (null under EXPLAIN; rows, time, database hits and memory under PROFILE), children and warnings (the remedy-bearing notifications raised for that operator). Keys are snake_case, and a breaking change bumps the schema version.

Value kinds

A kind that a later, additive ABI introduces is a number a program does not know; the header asks clients to treat it as a reportable case.

Value accessors

An accessor called on another kind, on a NULL handle, or with a NULL out-param refuses without side effects: a pointer return gives NULL, a count return gives -1, and a status return gives RELATE_ERROR with the out-params untouched. A refusal never poisons anything. Every handle and string belongs to the result.

Params builder

relate_params_new() returns a root: the statement's map of named parameters. _put_list and _put_map insert a nested container and write its child builder, which takes the same putters. A map takes a unique, non-NULL UTF-8 name; a list takes a NULL name and appends. Every putter copies its input and returns a status; a refusal returns RELATE_ERROR with an internal-stage shape and leaves the builder unchanged and usable.

Each limit refuses one past its value. A len or dim argument is trusted: a buffer shorter than it is undefined behavior. A statement that references a parameter the builder does not hold fails as an error result with semantic error: ParameterMissing: Expected parameter(s): <names>.

Ownership

The return type is the rule: a char * belongs to the caller, a const char * to relate.

Threading and panic safety

Environment

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 binds a zoned datetime, a point and a vector, then reads each back by its components:

#include <stdio.h>
#include "relate.h"

/* Bind a zoned datetime, a WGS-84 point and a FLOAT32 vector, then read them back. */
int main(void) {
    relate_database db = NULL;
    relate_connection conn = NULL;
    relate_query_result r = NULL;
    char *err = NULL;
    if (relate_database_open(":memory:", &db, &err) != RELATE_OK) return 1;
    if (relate_connect_namespace(db, NULL, &conn, &err) != RELATE_OK) return 1;

    double embedding[3] = {0.25, -1.0, 0.5};
    relate_params p = relate_params_new();
    if (relate_params_put_datetime(p, "at", 2026, 11, 4, 9, 30, 0, 0, 0, "Europe/Berlin", &err) != RELATE_OK ||
        relate_params_put_point(p, "loc", 4326, 12.5, 55.6, NULL, &err) != RELATE_OK ||
        relate_params_put_vector_float(p, "emb", "FLOAT32", embedding, 3, &err) != RELATE_OK) {
        fprintf(stderr, "put refused: %s\n", err);
        relate_free_string(err);
        return 1;
    }
    if (relate_query_params(conn, "RETURN $at AS at, $loc AS loc, $emb AS emb", p, &r, &err) != RELATE_OK) return 1;
    if (relate_result_is_error(r)) return 1;

    relate_value at = relate_value_at(r, 0, 0);
    int64_t y = 0, mo = 0, d = 0, h = 0, mi = 0, off = 0;
    relate_value_year(at, &y); relate_value_month(at, &mo); relate_value_day(at, &d);
    relate_value_hour(at, &h); relate_value_minute(at, &mi); relate_value_offset_seconds(at, &off);
    printf("at: kind=%d %04lld-%02lld-%02lld %02lld:%02lld offset=%lld zone=%s\n",
           relate_value_kind(at), (long long)y, (long long)mo, (long long)d,
           (long long)h, (long long)mi, (long long)off, relate_value_zone(at));

    int32_t srid = 0, dim = 0;
    double x = 0, yy = 0, z = 0;
    relate_value_point(relate_value_at(r, 0, 1), &srid, &dim, &x, &yy, &z);
    printf("loc: kind=%d srid=%d dim=%d x=%g y=%g\n", relate_value_kind(relate_value_at(r, 0, 1)), srid, dim, x, yy);

    relate_value emb = relate_value_at(r, 0, 2);
    printf("emb: kind=%d dtype=%s dim=%lld [", relate_value_kind(emb), relate_value_vector_dtype(emb),
           relate_value_vector_dim(emb));
    for (long long i = 0; i < relate_value_vector_dim(emb); i++) {
        double c = 0;
        relate_value_vector_float(emb, i, &c);
        printf("%s%g", i ? ", " : "", c);
    }
    int64_t wrong = 0;
    printf("]\nint accessor on a FLOAT32 vector: %s\n",
           relate_value_vector_int(emb, 0, &wrong) == RELATE_ERROR ? "RELATE_ERROR" : "RELATE_OK");

    relate_destroy_result(r);
    relate_params_free(p);
    relate_disconnect(conn);
    relate_database_close(db);
    return 0;
}

at: kind=14 2026-11-04 09:30 offset=3600 zone=Europe/Berlin
loc: kind=10 srid=4326 dim=2 x=12.5 y=55.6
emb: kind=17 dtype=FLOAT32 dim=3 [0.25, -1, 0.5]
int accessor on a FLOAT32 vector: RELATE_ERROR

See also

• Use the C ABI: linking, the error channel and the ownership rules, task by task.
• Rust API: the crate this library wraps.
• Errors: every message with its cause and remedy.
• Storage formats: what each store layout writes to disk.
• Embedded graph in an app: the problem the C ABI solves.