DrinkMeAlice.Graph (drink_me_alice v0.1.0)

Copy Markdown

Graph edges between records — SurrealDB's RELATE — with the same honest write outcomes as DrinkMeAlice.Tx.

Edge tables are TYPE RELATION tables (DDL via DrinkMeAlice.Ash.Schema.edge_statements/4, or by hand). A node is {table, key} where key is a string or integer record key.

{:committed, _} = Graph.relate(conn, "blocks", {"task", "a"}, {"task", "b"}, %{"why" => "needs api"})
{:ok, ["b"]}    = Graph.outgoing(conn, {"task", "a"}, "blocks", "task")

Table and edge names must be identifiers (DrinkMeAlice.identifier?/1); keys and field values travel as bound params. String keys and top-level string field values travel exact (DrinkMeAlice.exact_string/1 — 3.0.5 coerces date-, UUID- and record-shaped strings); nested field values are canonical terms and are NOT protected from that coercion. Field names must be identifiers.

Summary

Functions

Keys of the from_table records with an edge INTO to (one incoming hop), bounded likewise.

Keys of the to_table records reachable by one outgoing edge hop, bounded at 1000 (more is {:error, {:bounded_limit_exceeded, :neighbors}}).

Create one edge from -[edge]-> to. Returns a Tx.run/4 outcome; {:committed, %{"edge" => edge_row}} on success.

Delete every from -[edge]-> to edge. A Tx.run/4 outcome.

Types

node_ref()

@type node_ref() :: {binary(), binary() | integer()}

Functions

incoming(conn, to, edge, from_table, opts \\ [])

@spec incoming(GenServer.server(), node_ref(), binary(), binary(), keyword()) ::
  {:ok, list()} | {:error, term()}

Keys of the from_table records with an edge INTO to (one incoming hop), bounded likewise.

outgoing(conn, from, edge, to_table, opts \\ [])

@spec outgoing(GenServer.server(), node_ref(), binary(), binary(), keyword()) ::
  {:ok, list()} | {:error, term()}

Keys of the to_table records reachable by one outgoing edge hop, bounded at 1000 (more is {:error, {:bounded_limit_exceeded, :neighbors}}).

relate(conn, edge, from, to, fields \\ %{}, opts \\ [])

@spec relate(GenServer.server(), binary(), node_ref(), node_ref(), map(), keyword()) ::
  DrinkMeAlice.Tx.outcome() | {:error, term()}

Create one edge from -[edge]-> to. Returns a Tx.run/4 outcome; {:committed, %{"edge" => edge_row}} on success.

unrelate(conn, edge, from, to, opts \\ [])

@spec unrelate(GenServer.server(), binary(), node_ref(), node_ref(), keyword()) ::
  DrinkMeAlice.Tx.outcome() | {:error, term()}

Delete every from -[edge]-> to edge. A Tx.run/4 outcome.