---
title: API reference
description: "relate, the embedded Cypher graph database (relatedb.ai): Every relate surface, from the CLI and the language clients to the served protocols, with the capability matrix and each surface's reference page."
type: reference
surfaces:
  - cli
  - rust
  - c
  - python
  - node
  - browser
  - java
  - go
  - swift
  - bolt
  - http
  - mcp
status: stable
verified: 0.1.2
canonical_url: https://relatedb.ai/docs/reference/api/
prerequisites: []
related:
  - get-started/install
  - reference/project
  - reference/cli
  - reference/errors
  - concepts/architecture
  - concepts/problems-relate-solves#embedded-graph-in-an-app
last_updated: 2026-11-08
---

# API reference

Every relate surface, from the CLI and the language clients to the served protocols, with the capability matrix and each surface's reference page.

> Verified against relate 0.1.2. If your `relate --version` is newer, read https://relatedb.ai/docs/reference/changelog/#since-0.1.2

relate is one engine with several front doors, and each front door is a [surface](https://relatedb.ai/docs/reference/glossary/#surface). The Rust crate is the engine. The C library, `librelate_ffi`, exposes it through a C application binary interface (C ABI), which the Node.js, Java, Go and Swift [clients](https://relatedb.ai/docs/reference/glossary/#client) call; the Python client and the WebAssembly (WASM) browser build carry the engine themselves. The `relate` CLI links the engine too, and `relate serve` hosts [Bolt](https://relatedb.ai/docs/reference/glossary/#bolt), the HTTP Query API and [MCP](https://relatedb.ai/docs/reference/glossary/#mcp) over one [store](https://relatedb.ai/docs/reference/glossary/#store). Every surface runs the same engine, so a statement means the same thing on each; the surfaces differ in what they expose around it, which the matrix on this page records.

## Synopsis

| Surface         | Package or command                      | An in-memory store                                                                                          |
| --------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| CLI             | `relate`                                | `--database :memory:`, the default                                                                          |
| Python          | `relate-db`                             | `relate.connect(":memory:")`                                                                                |
| Node.js         | `@relate/relate`                        | `Database.open(":memory:")`                                                                                 |
| Browser         | `@relate/relate-wasm`                   | `new RelateDb()`                                                                                            |
| Rust            | the `relate` crate                      | `Database::open(":memory:")`                                                                                |
| C               | `librelate_ffi`, `relate.h`             | `relate_database_open(":memory:", …)`                                                                       |
| Java            | `com.relate:relate`                     | `Database.open(":memory:")`                                                                                 |
| Go              | `github.com/relatedb/relate/clients/go` | `relate.Open(":memory:")`                                                                                   |
| Swift           | `Relate`                                | `Database.inMemory()`                                                                                       |
| Bolt, HTTP, MCP | `relate serve`                          | `relate serve --database :memory: --http <port>`; at least one of `--http`, `--bolt` or `--mcp` is required |

Package names are launch-day targets; [Project](https://relatedb.ai/docs/reference/project/#platforms) lists the platforms each one ships for.

## Capability matrix

| Feature | CLI | Python | Node.js | Browser (WASM) | Rust | C | Java | Go | Swift | Bolt | HTTP | MCP |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| In-memory store. A store that lives only in the process. | yes: `--database :memory:`, the default | yes: `relate.connect(":memory:")` | yes: `Database.open(":memory:")` | yes: `new RelateDb()` | yes: `Database::open(":memory:")` | yes: `relate_database_open(":memory:", …)` | yes: `Database.open(":memory:")` | yes: `relate.Open(":memory:")` | yes: `Database.inMemory()` | yes: `relate serve --database :memory: --bolt <port>` | yes: `relate serve --database :memory: --http <port>` | yes: `relate serve --database :memory: --mcp stdio` |
| Directory store. A store in a directory on disk. | yes: `--database ./dir` | yes: `relate.connect(path)` | yes: `Database.open(path)` | no: no filesystem paths; `RelateDb.open("opfs://<name>")` is the durable browser store, in a dedicated worker | yes: `Database::open(path)` | yes: `relate_database_open(path, …)` | yes: `Database.open(path)` | yes: `relate.Open(path)` | yes: `Database(path:)` | yes: `relate serve` on a directory store | yes: `relate serve` on a directory store | yes: `relate serve` on a directory store |
| Single-file .rl store. A store in one `.rl` file. | yes: `--database ./graph.rl` | yes: `relate.connect("graph.rl")` | yes: `Database.open("graph.rl")` | no: opens `:memory:` and `opfs://` only | yes: `Database::open("graph.rl")` | yes: a `*.rl` URI | yes: `Database.open("graph.rl")` | yes: `relate.Open("graph.rl")` | yes: `Database(path: "graph.rl")` | yes: `relate serve` on a `.rl` store | yes: `relate serve` on a `.rl` store | yes: `relate serve` on a `.rl` store |
| Read-only open. An open that loads the store once and refuses every write. | yes: `--read-only`; a write exits 6 | yes: `read_only=True` | yes: `Database.open(uri, { readOnly: true })` | yes: `new RelateDb(true)` | yes: `OpenMode::ReadOnly` | yes: `relate_database_open_read_only` | yes: `Database.openReadOnly(uri)` | yes: `relate.OpenReadOnly(uri)` | yes: `Database(readOnlyPath:)` | yes: `relate serve --read-only` | yes: `relate serve --read-only` | yes: `relate serve --mcp stdio --read-only`; only `read_cypher` and `get_schema` are listed |
| Explicit transactions. Several statements committed or rolled back together. | yes: `.begin`, `.commit`, `.rollback` in a script on stdin or the shell | yes: `autocommit = False`, then `commit()` or `rollback()` | yes: `begin()`, `commit()`, `rollback()` | no: each statement commits on its own; `BEGIN` is a syntax error | yes: `begin()`, `commit()`, `rollback()` | yes: `relate_conn_begin`, `relate_conn_commit`, `relate_conn_rollback` | yes: `begin()`, `commit()`, `rollback()` | yes: `Begin()`, `Commit()`, `Rollback()` | yes: `begin()`, `commit()`, `rollback()`, `transaction { }` | yes: `BEGIN`, `COMMIT`, `ROLLBACK` | yes: `POST /db/<name>/query/v2/tx`, then `…/tx/<id>/commit` | no: each `tools/call` runs one statement |
| Parameters. `$name` values passed beside the statement. | yes: `--param name=value` | yes: `execute(statement, {"x": 3})` | yes: `query(statement, { x: 3 })` | yes: `execute(statement, paramsJson)` | yes: `query_with_params` | yes: the params builder | yes: `query(statement, Map)` | yes: `QueryParams(statement, map)` | yes: `query(statement, [String: CypherValue])` | yes: the `RUN` message's parameter map | yes: `"parameters"` in the request body | yes: the tools' `parameters` argument |
| Column types, counters and timings. Metadata returned with each result. | partial: the envelope has `columnTypes`, `timings` (elapsed and its phase split) and `planCache`, and the plan on `EXPLAIN`; no counters | yes: `QueryResult` (`column_types`, `stats`, `query_type`, `elapsed_ms` and its phase split) and the result summary | partial: counters, query type, elapsed and its phase split; no per-column type list (each value carries its type) | yes: `columnTypes`, `stats`, `elapsed_ms` and its phase split, `plan_cache` in the envelope | yes: `QueryResult`: `header.column_types`, `header.query_type`, `stats`, `elapsed_ms()` and its phase split, `plan_cache()` | partial: counters, timings and column names; no column-type call (read each value's kind with `relate_value_kind`) | partial: query type (a typed `QueryType`), namespace, bookmark, notifications and plan; no column types, counters or timings | partial: `Stats`, `QueryType`, `Plan`; no column types or timings | partial: `stats`, `elapsedMs` and its phase split, `queryType`; no column types | yes: the `SUCCESS` summaries: `columnTypes`, `t_first`, `t_last`, the phase times, `plan_cache`, `type`, `stats` | partial: `counters` on a write, `queryPlan`, `timings` (elapsed and its phase split) and `planCache`; no column types in the JSON response | yes: `columnTypes`, `stats`, `elapsed_ms` and its phase split, `plan_cache` in the tool result |
| Notifications. The engine's query notifications (for example a Cartesian product), each with a remedy. | yes: `notifications` in the envelope; filled on `EXPLAIN` and `PROFILE` | yes: `QueryResult.notifications` | yes: `result.notifications` | yes: `notifications` in the envelope; filled on `EXPLAIN` and `PROFILE` | yes: with the plan, on `EXPLAIN` and `PROFILE` | yes: `relate_result_notifications` | yes: `getNotifications()` | yes: `Notifications` | yes: `notifications` | yes: in the ending `SUCCESS` summary on `EXPLAIN` and `PROFILE`; a plain run carries none | yes: `notifications` in the response on `EXPLAIN` and `PROFILE` only; the remedy is appended to `description` | yes: on every call, from the `EXPLAIN` that classifies the statement |
| Arrow output. Results as Apache Arrow. | no: no Arrow output mode | yes: `cursor.to_arrow()` (the `relate-db[arrow]` extra), `Database.execute_arrow()` | no: no Arrow call in the client | no: no Arrow call in the package | yes: the `relate-arrow` crate | no: no Arrow call in the client | no: no Arrow call in the client | no: no Arrow call in the client | no: no Arrow call in the client | no: no Arrow output on this surface | no: no Arrow output on this surface | no: no Arrow output on this surface |
| Change data capture. Reading committed changes from a slot. | no: no CDC command; `CALL db.cdc.current()` is `ProcedureNotFound` | no: no change-data-capture call in the client | no: no change-data-capture call in the client | no: `CALL db.cdc.current()` is `ProcedureNotFound` | yes: `register_cdc_slot`, `cdc_records_after`, `ack_cdc_slot` | no: no change-data-capture call in the client | no: no change-data-capture call in the client | no: no change-data-capture call in the client | no: no change-data-capture call in the client | no: no change-data-capture feed on this surface; `CALL db.cdc.current()` is `ProcedureNotFound` | no: no change-data-capture feed on this surface; `CALL db.cdc.current()` is `ProcedureNotFound` | no: no change-data-capture feed on this surface; `CALL db.cdc.current()` is `ProcedureNotFound` |
| Vector search. Vector indexes and `SEARCH`. | yes: `CREATE VECTOR INDEX` and `SEARCH` | yes: `CREATE VECTOR INDEX` and `SEARCH` | yes: `CREATE VECTOR INDEX` and `SEARCH` | yes: `CREATE VECTOR INDEX` and `SEARCH` | yes: `CREATE VECTOR INDEX` and `SEARCH`; the engine crate the other surfaces build on | yes: `CREATE VECTOR INDEX` and `SEARCH` through the C ABI | yes: `CREATE VECTOR INDEX` and `SEARCH` through the C ABI | yes: `CREATE VECTOR INDEX` and `SEARCH` through the C ABI | yes: `CREATE VECTOR INDEX` and `SEARCH` through the C ABI | yes: `CREATE VECTOR INDEX` and `SEARCH` as statements | yes: `CREATE VECTOR INDEX` and `SEARCH` | yes: `CREATE VECTOR INDEX` and `SEARCH` as statements |
| Full-text search. Full-text indexes and their queries. | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH`, with the index's query syntax (`AND`, `NOT`) | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH` | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH` | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH` | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH`; the engine crate the other surfaces build on | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH` through the C ABI | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH` through the C ABI | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH` through the C ABI | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH` through the C ABI | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH` as statements | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH` | yes: `CREATE FULLTEXT INDEX` and full-text `SEARCH` as statements |
| LOAD CSV from local files. Local `LOAD CSV` under a configured directory (denied unless one is set). | yes: `--load-csv-dir PATH` or `RELATE_LOAD_CSV_DIR` | yes: `RELATE_LOAD_CSV_DIR`; `connect` takes no CSV option | yes: `RELATE_LOAD_CSV_DIR` | no: no CSV directory can be set; a local file is `LOAD CSV file unavailable` | yes: `OpenOptions.load_csv_dir` | yes: `RELATE_LOAD_CSV_DIR`, read by the C ABI's open | yes: `RELATE_LOAD_CSV_DIR`, read by the C ABI's open | yes: `RELATE_LOAD_CSV_DIR`, read by the C ABI's open | yes: `RELATE_LOAD_CSV_DIR`, read by the C ABI's open | yes: `RELATE_LOAD_CSV_DIR` for `relate serve`, one store for every served surface | yes: `RELATE_LOAD_CSV_DIR` for `relate serve`, which has no flag for it | yes: `RELATE_LOAD_CSV_DIR` for `relate serve`; only through `write_cypher`, which returns no rows (`read_cypher` refuses `LOAD CSV`) |
| Load a store from a URL. Opening a `.rl` store fetched over https. | yes: `--load` with an https URL to a `.rl` file | no: no open from a URL in the client | no: no open from a URL in the client | no: opens `:memory:` and `opfs://` only | no: `Database::open` takes `:memory:`, a path or `file://` | no: no open from a URL in the client | no: no open from a URL in the client | no: no open from a URL in the client | no: no open from a URL in the client | yes: `relate serve --database :memory: --load` with an https URL; the loaded store is read-only | yes: `relate serve --database :memory: --load` with an https URL; the loaded store is read-only | yes: `relate serve --database :memory: --load` with an https URL; the loaded store is read-only |
| Agent mode. The CLI's agent defaults: the 100-row cap and the piped `toon` output. | yes: `--agent-mode`, `RELATE_AGENT_MODE`, or a detected agent harness | no: A CLI setting | no: A CLI setting | no: A CLI setting | no: A CLI setting | no: A CLI setting | no: A CLI setting | no: A CLI setting | no: A CLI setting | no: A CLI setting | no: A CLI setting | no: A CLI setting |

Each cell is yes, no, partial or unknown, with the call, flag or reason. Checked on 2026-11-09 against relate 0.1.2: runs of the CLI binary and `relate serve` (Bolt, HTTP and MCP), the WebAssembly build this site ships, and the Python, Node.js, C, Java, Go, Swift and Rust clients, and each surface's upstream reference. The C, Java, Go and Swift clients load the same C ABI library as the Node.js client.

Each row is a feature and each column a surface; every row has a stable anchor, `#matrix-<feature>`, such as `#matrix-read-only`. A cell holds one of four values, then a note:

| Value     | Meaning                                                              |
| --------- | -------------------------------------------------------------------- |
| `yes`     | The surface has the feature; the note names the call, flag, or field |
| `no`      | The surface lacks it; the note says why, or what it offers instead   |
| `partial` | The surface has part of it; the note names the part                  |
| `unknown` | Nobody has checked the cell; the matrix never guesses                |

A cell is checked against a run of the surface or its upstream reference, and the note says what the surface does, not how the cell was checked. The C, Java, Go and Swift clients load the same C library as the Node.js client, so a statement-level cell such as vector search is checked once through that library; the Bolt and MCP cells of statement-level features are checked on the store all three served surfaces share. The reference page of each language client shows its own column alone.

## Surfaces

- CLI: [relate CLI](https://relatedb.ai/docs/reference/cli/) for every command and flag; [Script the CLI](https://relatedb.ai/docs/guides/cli/scripting/) for using it from shell scripts.
- Python: [Python API](https://relatedb.ai/docs/reference/api/python/); [Use the Python client](https://relatedb.ai/docs/guides/embed/python/).
- Node.js: [Node.js API](https://relatedb.ai/docs/reference/api/javascript/); [Use the Node.js client](https://relatedb.ai/docs/guides/embed/node/).
- Browser: [WebAssembly API](https://relatedb.ai/docs/reference/api/wasm/); [Use relate from a web page](https://relatedb.ai/docs/guides/embed/browser/).
- Rust: [Rust API](https://relatedb.ai/docs/reference/api/rust/); [Use the Rust crate](https://relatedb.ai/docs/guides/embed/rust/).
- C: [C ABI](https://relatedb.ai/docs/reference/api/c/); [Use the C ABI](https://relatedb.ai/docs/guides/embed/c/).
- Java: [Java API](https://relatedb.ai/docs/reference/api/java/); [Use the Java client](https://relatedb.ai/docs/guides/embed/java/).
- Go: [Go API](https://relatedb.ai/docs/reference/api/go/); [Use the Go client](https://relatedb.ai/docs/guides/embed/go/).
- Swift: [Swift API](https://relatedb.ai/docs/reference/api/swift/); [Use the Swift package](https://relatedb.ai/docs/guides/embed/swift/).
- Bolt: [Bolt server](https://relatedb.ai/docs/reference/server/bolt/); [Serve a store over Bolt](https://relatedb.ai/docs/guides/serve/bolt/).
- HTTP: [HTTP Query API](https://relatedb.ai/docs/reference/server/http/); [Serve the HTTP Query API](https://relatedb.ai/docs/guides/serve/http-query-api/).
- MCP: [MCP server](https://relatedb.ai/docs/reference/server/mcp/); [Serve a store over MCP](https://relatedb.ai/docs/guides/serve/mcp/).

## See also

- [Install relate](https://relatedb.ai/docs/get-started/install/): the CLI and a package for each language.
- [Project](https://relatedb.ai/docs/reference/project/): releases, platforms and where each package is published.
- [Errors](https://relatedb.ai/docs/reference/errors/): the error codes every surface shares.
- [Architecture](https://relatedb.ai/docs/concepts/architecture/): how the engine and its surfaces fit together.
- [Embedded graph in an app](https://relatedb.ai/docs/concepts/problems-relate-solves/#embedded-graph-in-an-app): the problem the language clients solve.

## Terms used on this page

- **surface**: Any front door to the relate engine: the CLI, a language client, the C ABI, the WebAssembly build, or a server that `relate serve` hosts.
- **client**: A language package that runs the relate engine inside a program's process: the Python, Node.js, Rust, Java, Go and Swift clients.
- **Bolt**: Neo4j's binary client protocol; `relate serve --bolt <port>` speaks it, so Neo4j's drivers and Neo4j Browser can run statements against a relate store.
- **MCP**: The Model Context Protocol, which agent hosts use to call tools; `relate serve --mcp` exposes a store as `read_cypher`, `get_schema` and `write_cypher`.
- **store**: A relate database: a directory, a single `.rl` file, or `:memory:`, opened with `--database`.