Option schema and validation for NebulaGraphEx.Graph.

All options listed here may be passed to NebulaGraphEx.Graph.start_link/1. Per-query options (:timeout, :space, :decode_mapper, :log, :telemetry_prefix) may also be passed as the final argument to NebulaGraphEx.Graph.query/4 and NebulaGraphEx.Graph.query!/4 to override the pool-level defaults for a single call.

Option reference

Identity

• :name — registered name for the pool process, e.g. MyApp.Graph. Required when starting multiple pools in one application.

Connectivity

• :hostname — NebulaGraph graphd host. Default: "localhost".
• :port — NebulaGraph graphd port. Default: 9669.
• :hosts — list of {host, port} tuples for multi-host mode (round-robin). When set, :hostname and :port are ignored.
• :load_balancing — :round_robin or :random. Default: :round_robin.

Authentication

• :username — authentication username. Default: "root".
• :password — authentication password. Default: "nebula". May be a zero-arity function: fn -> System.fetch_env!("NEBULA_PASS") end.

Default space

• :space — graph space to USE immediately after authentication. When nil the caller must issue USE <space> manually. Default: nil.

Timeouts

• :connect_timeout — TCP connect timeout in milliseconds. Default: 5_000.
• :recv_timeout — Socket read timeout per frame in milliseconds. Default: 15_000.
• :send_timeout — Socket write timeout in milliseconds. Default: 15_000.

TLS / SSL

• :ssl — enable TLS. Default: false.
• :ssl_opts — keyword list passed directly to :ssl.connect/3. Default: []. Common keys: :verify, :cacertfile, :certfile, :keyfile, :server_name_indication.

Connection pool (DBConnection)

• :pool_size — number of connections to maintain. Default: 10.
• :max_overflow — extra connections allowed under burst load. Default: 0.
• :idle_interval — how often to ping idle connections, in ms. Default: 1_000.
• :queue_target — connection queue latency target in ms. Default: 50.
• :queue_interval — queue sampling interval in ms. Default: 1_000.
• :pool — DBConnection pool module. Default: DBConnection.ConnectionPool.

Reconnection / back-off

• :backoff_type — :stop | :exp | :rand | :rand_exp. Default: :rand_exp.

• :backoff_min — minimum back-off in ms. Default: 1_000.
• :backoff_max — maximum back-off in ms. Default: 30_000.

Query defaults

• :timeout — per-query execution timeout in ms. Default: 15_000.
• :decode_mapper — fn(%NebulaGraphEx.Record{}) :: term() applied to every row. Default: nil (rows returned as %NebulaGraphEx.Record{}).

JSON execution

• :prefer_json — use executeJson instead of execute. The server returns a JSON binary rather than a Thrift-encoded DataSet; slower to decode but useful for debugging. Default: false.

Observability

• :telemetry_prefix — prefix list for :telemetry events. Default: [:nebula_graph_ex, :query].
• :log — emit a structured Logger message for each query. The message includes the caller location (in muted gray), a [NGE] prefixed status line with row count and timing, the nGQL statement, and any parameters. Default: false.
• :log_level — overrides the automatically inferred log level. When not set, the level is derived from the nGQL verb: reads → :debug, writes and updates → :info, deletes and DDL → :warning. Accepts :debug, :info, :notice, :warning, :error. Default: inferred.
• :slow_query_threshold — log queries whose total time (queue + db) exceeds this value in milliseconds, regardless of :log. Useful for surfacing slow queries in production without enabling full query logging. Default: nil (disabled).

Example log output:

↳ MyApp.IntelModule.recent_snapshots/1, at: lib/my_app/intel_module.ex:42
[NGE] QUERY OK 3 rows db=0.6ms queue=0.1ms
MATCH (v:Player) RETURN v.name LIMIT 3 []

Security

• :show_sensitive_data_on_connection_error — include password in connection error messages. Default: false.