TerminusDB.GraphQL (terminusdb_ex v0.3.3)

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.

Summary

Types

graphql_opt()

result()

Functions

introspect(config, opts \\ [])

Introspects the GraphQL schema of the database.

mutate(config, query_string, opts \\ [])

Executes a GraphQL mutation against the database.

query(config, query_string, opts \\ [])

Executes a GraphQL query against the database.

Types

graphql_opt()

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

result()

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

Functions

introspect(config, opts \\ [])

@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(config, query_string, opts \\ [])

@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(config, query_string, opts \\ [])

@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"}]