# `NebulaGraphEx.Options`
[🔗](https://github.com/VChain/nebula_graph_ex/blob/v0.1.8/lib/nebula_graph_ex/options.ex#L1)

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`.

# `resolve_password`

```elixir
@spec resolve_password(String.t() | (-&gt; String.t())) :: String.t()
```

Resolves the password value — calls the function if given one, otherwise
returns the binary as-is.

# `validate_pool`

```elixir
@spec validate_pool(keyword()) :: {:ok, keyword()} | {:error, String.t()}
```

Validates pool-level options. Returns `{:ok, opts}` or `{:error, reason}`.

# `validate_pool!`

```elixir
@spec validate_pool!(keyword()) :: keyword()
```

Validates pool-level options, raising `ArgumentError` on failure.

# `validate_query`

```elixir
@spec validate_query(keyword()) :: {:ok, keyword()} | {:error, String.t()}
```

Validates per-query option overrides.

---

*Consult [api-reference.md](api-reference.md) for complete listing*