Injects a graph module into the calling module.

Options

• :otp_app — required. The OTP application atom used to look up config via Application.get_env(otp_app, __MODULE__, []).

Generated API

When you use NebulaGraphEx.Graph, otp_app: :my_app, the following functions are injected into your module, all scoped to the pool that the module itself manages:

• start_link/1 — starts the pool (used by your supervision tree).
• child_spec/1 — makes the module a valid child spec entry.
• query/1,2,3 — query(statement, params \\ %{}, opts \\ []).
• query!/1,2,3 — raises on failure.
• map/2,3,4 — map(statement, params \\ %{}, opts \\ [], fun).
• status/0,1 — checks whether the pool is alive and can run a simple query.
• use_space/1,2 — use_space(space, opts \\ []).

All functions are overridable so you can add instrumentation or defaults.

@spec map(
  DBConnection.conn(),
  String.t(),
  map(),
  keyword(),
  (NebulaGraphEx.ResultSet.t() -> term())
) ::
  {:ok, [term()]} | {:error, NebulaGraphEx.Error.t()}

Executes a nGQL statement and applies fun to every %Record{} row, returning a list of results.

Equivalent to:

{:ok, rs} = query(conn, stmt, params, opts)
Enum.map(ResultSet.rows(rs), fun)

Example

NebulaGraphEx.Graph.map(MyApp.Graph, "MATCH (v:Player) RETURN v.name", fn record ->
  record |> NebulaGraphEx.Record.get!("v.name")
end)
#=> ["Tim Duncan", "LeBron James", ...]

@spec query(DBConnection.conn(), String.t(), map(), keyword()) ::
  {:ok, NebulaGraphEx.ResultSet.t()} | {:error, NebulaGraphEx.Error.t()}

Executes a nGQL statement and returns {:ok, %ResultSet{}} or {:error, %NebulaGraphEx.Error{}}.

Arguments

• conn — pool name or PID from start_link/1. When using the use macro, this is the module itself and is passed automatically.
• statement — nGQL string.
• params — map of parameter bindings. Default: %{}.
• opts — per-query option overrides (see NebulaGraphEx.Options). Default: [].

Examples

{:ok, rs} = NebulaGraphEx.Graph.query(MyApp.Graph, "RETURN 1+1 AS sum")
rs |> NebulaGraphEx.ResultSet.first!() |> NebulaGraphEx.Record.get!("sum")
#=> 2

{:error, %NebulaGraphEx.Error{code: :e_syntax_error}} =
  NebulaGraphEx.Graph.query(MyApp.Graph, "THIS IS NOT VALID nGQL")

@spec query!(DBConnection.conn(), String.t(), map(), keyword()) ::
  NebulaGraphEx.ResultSet.t()

Like query/4 but raises NebulaGraphEx.Error on failure.

Example

NebulaGraphEx.Graph.query!(MyApp.Graph, "MATCH (v:Player) RETURN count(v) AS n")
|> NebulaGraphEx.ResultSet.first!()
|> NebulaGraphEx.Record.get!("n")
#=> 51

@spec start_link(keyword()) :: {:ok, pid()} | {:error, term()}

Starts a supervised connection pool and links it to the calling process.

Typically called via a module that uses NebulaGraphEx.Graph. When using the pool directly, pass a :name so callers can reference it by atom:

children = [
  {NebulaGraphEx.Graph,
   name: MyApp.Graph,
   hostname: System.fetch_env!("NEBULA_HOST"),
   password: fn -> System.fetch_env!("NEBULA_PASS") end,
   space: "my_graph",
   pool_size: 20}
]

See NebulaGraphEx.Options for the full option reference.

@spec status(
  DBConnection.conn(),
  keyword()
) ::
  {:ok,
   %{
     pid: pid(),
     connected?: true,
     queryable?: boolean(),
     probe_statement: String.t() | nil
   }}
  | {:error,
     %{
       pid: pid() | nil,
       connected?: boolean(),
       queryable?: false,
       probe_statement: String.t() | nil,
       error: term(),
       error_details: map()
     }}

Checks whether a pool is alive and able to execute a simple query.

This is an active health check. It first resolves the pool process and then, unless disabled, executes RETURN 1 AS status to verify the checked-out connection can talk to NebulaGraph successfully.

Options

• :probe_statement — query used for the health check. Default: "RETURN 1 AS status".
• :probe_query — whether to run the health-check query. Default: true.
• :query_opts — options passed to the probe query. Default: [].

Return value

On success:

{:ok,
 %{
   pid: #PID<0.123.0>,
   connected?: true,
   queryable?: true,
   probe_statement: "RETURN 1 AS status"
 }}

If the pool process is missing:

{:error,
 %{
   pid: nil,
   connected?: false,
   queryable?: false,
   error: :not_running,
   error_details: %{reason: :not_running, message: "pool process is not running"}
 }}

If the pool exists but the probe query fails:

{:error,
 %{
   pid: #PID<0.123.0>,
   connected?: true,
   queryable?: false,
   probe_statement: "RETURN 1 AS status",
   error: %NebulaGraphEx.Error{},
   error_details: %{code: :e_syntax_error, message: "...", category: :query}
 }}

@spec use_space(DBConnection.conn(), String.t(), keyword()) ::
  {:ok, NebulaGraphEx.ResultSet.t()} | {:error, NebulaGraphEx.Error.t()}

Issues USE <space> on the given connection, switching the active graph space for that connection's current session.

This is only useful when you hold a checked-out connection directly. With the pool, prefer passing the :space option to query/4 instead.