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 Logger messages for each query. Default: false.
• :log_level — Logger level when :log is true. Default: :debug.
• :slow_query_threshold — log queries exceeding this duration (ms) regardless of :log. Default: nil (disabled).

Security

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