# `TerminusDB.GraphQL`
[🔗](https://github.com/thanos/terminusdb-client-elixir/blob/v0.3.3/lib/terminus_db/graphql.ex#L1)

GraphQL API for TerminusDB.

Wraps the `/api/graphql/{org}/{db}` endpoint. TerminusDB auto-generates a
GraphQL schema from the database's document schema, supporting queries
(filter, limit, offset, orderBy, backlinks, path queries, count) and
mutations (insert/replace/delete documents).

This is a **thin HTTP wrapper** — users write raw GraphQL query strings.
A programmatic query builder DSL is planned for a future release.

## Quick start

    config =
      TerminusDB.Config.new(endpoint: "http://localhost:6363")
      |> TerminusDB.Config.with_database("mydb")

    # Query
    {:ok, result} = TerminusDB.GraphQL.query(config, "{ Person { name age } }")

    # Mutation
    {:ok, result} = TerminusDB.GraphQL.mutate(config, ~s'''
      mutation {
        _insertDocuments(json: "{\"@type\":\"Person\",\"name\":\"Alice\"}")
      }
    ''')

    # Introspect schema
    {:ok, schema} = TerminusDB.GraphQL.introspect(config)

## Response format

- `{:ok, %{data: data, errors: nil}}` — successful query with no errors.
- `{:ok, %{data: data, errors: errors}}` — partial success with errors.
- `{:ok, %{data: nil, errors: errors}}` — query failed.
- `{:error, %Error{}}` — HTTP/transport error.

# `graphql_opt`

```elixir
@type graphql_opt() :: {:organization, String.t()}
```

# `result`

```elixir
@type result() ::
  {:ok, %{data: term(), errors: [map()] | nil}} | {:error, TerminusDB.Error.t()}
```

# `introspect`

```elixir
@spec introspect(TerminusDB.Config.t(), [graphql_opt()]) ::
  {:ok, map()} | {:error, TerminusDB.Error.t()}
```

Introspects the GraphQL schema of the database.

Sends a `__schema` introspection query and returns the raw schema map.

## Options

- `:organization` — overrides `config.organization`.

## Examples

    iex> config = TerminusDB.Config.new(
    ...>   endpoint: "http://localhost:6363",
    ...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"data" => %{"__schema" => %{"types" => [%{"name" => "Person"}]})})} end
    ...> ) |> TerminusDB.Config.with_database("mydb")
    iex> {:ok, schema} = TerminusDB.GraphQL.introspect(config)
    iex> schema["__schema"]["types"]
    [%{"name" => "Person"}]

# `mutate`

```elixir
@spec mutate(TerminusDB.Config.t(), String.t(), [graphql_opt()] | map()) :: result()
```

Executes a GraphQL mutation against the database.

Same as `query/3` but conventionally used for mutations.

## Examples

    iex> config = TerminusDB.Config.new(
    ...>   endpoint: "http://localhost:6363",
    ...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"data" => %{"_insertDocuments" => ["Person/Alice"]})})} end
    ...> ) |> TerminusDB.Config.with_database("mydb")
    iex> {:ok, result} = TerminusDB.GraphQL.mutate(config, ~s(mutation { _insertDocuments(json: "{\"@type\":\"Person\",\"name\":\"Alice\"}") }))
    iex> result.data["_insertDocuments"]
    ["Person/Alice"]

# `query`

```elixir
@spec query(TerminusDB.Config.t(), String.t(), [graphql_opt()] | map()) :: result()
```

Executes a GraphQL query against the database.

`query_string` is a raw GraphQL query string. `variables` is an optional
map of variable values for parameterized queries.

## Options

- `:organization` — overrides `config.organization`.

## Examples

    iex> config = TerminusDB.Config.new(
    ...>   endpoint: "http://localhost:6363",
    ...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"data" => %{"Person" => [%{"name" => "Alice"}]})})} end
    ...> ) |> TerminusDB.Config.with_database("mydb")
    iex> {:ok, result} = TerminusDB.GraphQL.query(config, "{ Person { name } }")
    iex> result.data["Person"]
    [%{"name" => "Alice"}]

---

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