BoltexNif (boltex_nif v0.1.1)

View Source

Elixir NIF bindings for the neo4rs Rust driver for Neo4j.

All public functions are synchronous at the Elixir layer. Internally the Rust side spawns work on a global Tokio runtime and signals completion by sending {ref, result} back to the calling process. The Elixir wrapper blocks on a receive until the response arrives or :timeout elapses.

High-level API

Summary

Connection

connect(opts)

Connect to a Neo4j database.

Auto-commit queries

execute(graph, cypher, params \\ nil, opts \\ [])

Run a query in auto-commit mode, collecting all rows into a list of maps.

run(graph, cypher, params \\ nil, opts \\ [])

Run a query in auto-commit mode, discarding any rows.

run_with_summary(graph, cypher, params \\ nil, opts \\ [])

Run a query in auto-commit mode and return a BoltexNif.Summary struct with counters (nodes/relationships created, properties set, …), notifications and the query bookmark (Bolt v5).

Transactions

begin_transaction(graph, opts \\ [])

Start an explicit transaction.

commit(txn, opts \\ [])

Commit a transaction. Returns {:ok, bookmark} on Bolt v5 (the bookmark may be nil) or plain :ok otherwise.

rollback(txn, opts \\ [])

Roll back a transaction.

transaction(graph, fun, opts \\ [])

Convenience wrapper: begin_transaction → run fun, commit on success, rollback on {:error, _} or raise.

txn_execute(txn, cypher, params \\ nil, opts \\ [])

Run a query inside a transaction and collect all rows.

txn_run(txn, cypher, params \\ nil, opts \\ [])

Run a query inside a transaction, returning its BoltexNif.Summary struct.

Streaming

stream_close(stream, opts \\ [])

Drop a stream eagerly (without consuming remaining rows).

stream_next(stream, opts \\ [])

Fetch the next row. Returns {:ok, row}, :done, or {:error, reason}.

stream_start(graph, cypher, params \\ nil, opts \\ [])

Start a lazy row stream for cypher. Consume with stream_next/2.

Types

config()
graph()
params()
row()
stream()
txn()

Connection

connect(opts)

@spec connect(config()) :: {:ok, graph()} | {:error, term()}

Connect to a Neo4j database.

Accepted options:

  • :uri (required) — e.g. "bolt://localhost:7687" or "neo4j://..."
  • :user / :password
  • :db — database name (optional)
  • :fetch_size — rows per fetch window (0 keeps driver default)
  • :max_connections — pool size (0 keeps driver default)
  • :impersonate_user — user to impersonate for queries (Bolt v5)
  • :tls — one of:
    • nil (default) — use scheme-driven TLS (neo4j+s://, bolt+ssc://, …)
    • {:ca, "path/to/ca.pem"} — validate the server against this CA

    • {:mutual, ca: path | nil, cert: path, key: path} — mutual TLS

    • :skip_validation — bypass verification (NOT for production)
  • :timeout — milliseconds to wait for the handshake (default 15 000)

Auto-commit queries

execute(graph, cypher, params \\ nil, opts \\ [])

@spec execute(graph(), String.t(), params(), keyword()) ::
  {:ok, [row()]} | {:error, term()}

Run a query in auto-commit mode, collecting all rows into a list of maps.

Keys in each row are the AS aliases from the Cypher RETURN clause. For large result sets, prefer stream_start/4 to avoid buffering everything in memory.

run(graph, cypher, params \\ nil, opts \\ [])

@spec run(graph(), String.t(), params(), keyword()) :: :ok | {:error, term()}

Run a query in auto-commit mode, discarding any rows.

params is a map of string (or atom) keys to Elixir terms that are marshalled to Bolt values — see the type table in the Overview.

run_with_summary(graph, cypher, params \\ nil, opts \\ [])

@spec run_with_summary(graph(), String.t(), params(), keyword()) ::
  {:ok, BoltexNif.Summary.t()} | {:error, term()}

Run a query in auto-commit mode and return a BoltexNif.Summary struct with counters (nodes/relationships created, properties set, …), notifications and the query bookmark (Bolt v5).

Transactions

begin_transaction(graph, opts \\ [])

@spec begin_transaction(
  graph(),
  keyword()
) :: {:ok, txn()} | {:error, term()}

Start an explicit transaction.

The returned handle must be finished with commit/2 or rollback/2; use transaction/3 for the recommended scope-and-commit pattern.

commit(txn, opts \\ [])

@spec commit(
  txn(),
  keyword()
) :: :ok | {:ok, String.t() | nil} | {:error, term()}

Commit a transaction. Returns {:ok, bookmark} on Bolt v5 (the bookmark may be nil) or plain :ok otherwise.

rollback(txn, opts \\ [])

@spec rollback(
  txn(),
  keyword()
) :: :ok | {:error, term()}

Roll back a transaction.

transaction(graph, fun, opts \\ [])

@spec transaction(
  graph(),
  (txn() -> {:ok, any()} | {:error, any()} | any()),
  keyword()
) ::
  {:ok, any()} | {:error, term()}

Convenience wrapper: begin_transaction → run fun, commit on success, rollback on {:error, _} or raise.

The function value you return from fun drives the transaction:

  • {:ok, value} — commit, result is {:ok, value}.
  • {:error, reason} — rollback, result is {:error, reason}.
  • any other term — commit, result is {:ok, term}.
  • a raised exception — rollback, then re-raise.

txn_execute(txn, cypher, params \\ nil, opts \\ [])

@spec txn_execute(txn(), String.t(), params(), keyword()) ::
  {:ok, [row()]} | {:error, term()}

Run a query inside a transaction and collect all rows.

txn_run(txn, cypher, params \\ nil, opts \\ [])

@spec txn_run(txn(), String.t(), params(), keyword()) ::
  {:ok, BoltexNif.Summary.t()} | {:error, term()}

Run a query inside a transaction, returning its BoltexNif.Summary struct.

Streaming

stream_close(stream, opts \\ [])

@spec stream_close(
  stream(),
  keyword()
) :: :ok

Drop a stream eagerly (without consuming remaining rows).

stream_next(stream, opts \\ [])

@spec stream_next(
  stream(),
  keyword()
) :: {:ok, row()} | :done | {:error, term()}

Fetch the next row. Returns {:ok, row}, :done, or {:error, reason}.

stream_start(graph, cypher, params \\ nil, opts \\ [])

@spec stream_start(graph(), String.t(), params(), keyword()) ::
  {:ok, stream()} | {:error, term()}

Start a lazy row stream for cypher. Consume with stream_next/2.

Types

config()

@type config() :: keyword() | map()

graph()

@type graph() :: reference()

params()

@type params() :: map() | nil

row()

@type row() :: %{optional(String.t()) => term()}

stream()

@type stream() :: reference()

txn()

@type txn() :: reference()