# `NebulaGraphEx.Thrift.GraphService`
[🔗](https://github.com/VChain/nebula_graph_ex/blob/v0.1.10/lib/nebula_graph_ex/thrift/graph_service.ex#L1)

Typed Thrift calls for the NebulaGraph `GraphService`.

This module wraps `NebulaGraphEx.Thrift.Client` with the exact method
signatures defined in `priv/thrift/graph.thrift`. All encoding and
decoding is done manually against the Thrift binary protocol so that the
raw socket stays under `DBConnection`'s control.

## Methods

* `authenticate/3` — open a session with username + password
* `execute/4` — run a nGQL statement (binary DataSet response)
* `execute_with_parameter/5` — parameterised nGQL
* `execute_json/4` — run a nGQL statement (JSON response)
* `signout/2` — close a session (one-way, no reply)
* `verify_client_version/2` — version handshake

# `authenticate`

```elixir
@spec authenticate(NebulaGraphEx.Transport.socket(), binary(), binary(), keyword()) ::
  {:ok, map()} | {:error, term()}
```

Authenticates against the NebulaGraph server.

Returns `{:ok, auth_response}` on success, where `auth_response` is a map:

* `:error_code` — raw integer error code (0 = success)
* `:session_id` — integer session ID to use in subsequent calls
* `:time_zone_offset_seconds` — server timezone offset or `nil`
* `:time_zone_name` — server timezone binary or `nil`
* `:error_msg` — error message binary or `nil`

# `execute`

```elixir
@spec execute(NebulaGraphEx.Transport.socket(), integer(), binary(), keyword()) ::
  {:ok, map()} | {:error, term()}
```

Executes a nGQL statement and returns an `ExecutionResponse` map with keys:

* `:error_code` — integer
* `:latency_in_us` — server-side latency in microseconds
* `:data` — `nil` or a map with `:column_names` and `:rows`
* `:space_name` — binary or `nil`
* `:error_msg` — binary or `nil`
* `:comment` — binary or `nil`

# `execute_json`

```elixir
@spec execute_json(NebulaGraphEx.Transport.socket(), integer(), binary(), keyword()) ::
  {:ok, binary()} | {:error, term()}
```

Executes a nGQL statement and returns a raw JSON binary.

Useful for debugging. The caller is responsible for JSON decoding.

# `execute_with_parameter`

```elixir
@spec execute_with_parameter(
  NebulaGraphEx.Transport.socket(),
  integer(),
  binary(),
  map(),
  keyword()
) :: {:ok, map()} | {:error, term()}
```

Executes a parameterised nGQL statement.

`params` is a map with binary keys and Elixir values that are encodable
by `NebulaGraphEx.Thrift.Types.encode_value/1`.

## Example

    GraphService.execute_with_parameter(
      socket,
      session_id,
      "MATCH (v:Player{name: $name}) RETURN v",
      %{"name" => "Tim Duncan"}
    )

# `signout`

```elixir
@spec signout(NebulaGraphEx.Transport.socket(), integer()) :: :ok | {:error, term()}
```

Signs out and closes the session. One-way — the server sends no reply.

# `verify_client_version`

```elixir
@spec verify_client_version(
  NebulaGraphEx.Transport.socket(),
  keyword()
) :: {:ok, :ok} | {:error, term()}
```

Performs the client version handshake. Call immediately after opening
the socket, before `authenticate/3`.

Returns `{:ok, :ok}` on success or `{:error, message}`.

---

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