GraphQL Guide

TerminusDB auto-generates a GraphQL endpoint from your database's document schema. The terminusdb_ex client provides a thin HTTP wrapper for sending GraphQL queries and mutations.

Connecting

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

Queries

{:ok, result} = TerminusDB.GraphQL.query(config, "{ Person { name age } }")
# => {:ok, %{data: %{"Person" => [%{"name" => "Alice", "age" => 30}]}, errors: nil}}

Filtering

{:ok, result} = TerminusDB.GraphQL.query(config, """
  {
    Person(filter: {name: {eq: "Alice"}}) {
      name
      age
    }
  }
""")

Pagination

{:ok, result} = TerminusDB.GraphQL.query(config, """
  {
    Person(limit: 10, offset: 20) { name }
  }
""")

Ordering

{:ok, result} = TerminusDB.GraphQL.query(config, """
  {
    Person(orderBy: {name: ASC}) { name }
  }
""")

Path queries

{:ok, result} = TerminusDB.GraphQL.query(config, """
  {
    Person {
      name
      _path(friend+: { name: "Bob" }) { name }
    }
  }
""")

Backlinks

{:ok, result} = TerminusDB.GraphQL.query(config, """
  {
    Person {
      name
      _backlink(friend: {}) { name }
    }
  }
""")

Count

{:ok, result} = TerminusDB.GraphQL.query(config, """
  {
    Person { _count }
  }
""")

Mutations

Insert documents

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

Replace documents

{:ok, result} = TerminusDB.GraphQL.mutate(config, """
  mutation {
    _replaceDocuments(json: "{\\"@id\\":\\"Person/Alice\\",\\"name\\":\\"Alicia\\"}", create: true)
  }
""")

Delete documents

{:ok, result} = TerminusDB.GraphQL.mutate(config, """
  mutation {
    _deleteDocuments(ids: ["Person/Alice"])
  }
""")

With commit info

{:ok, result} = TerminusDB.GraphQL.mutate(config, """
  mutation {
    _insertDocuments(json: "{\\"@type\\":\\"Person\\",\\"name\\":\\"Bob\\"}") {
      _commitInfo { author message }
    }
  }
""")

Introspection

{:ok, schema} = TerminusDB.GraphQL.introspect(config)
# => {:ok, %{"__schema" => %{"types" => [...]}}}

Variables

{:ok, result} = TerminusDB.GraphQL.query(config, """
  query($name: String) {
    Person(filter: {name: {eq: $name}}) { name }
  }
""", %{"name" => "Alice"})

Error handling

case TerminusDB.GraphQL.query(config, "{ Person { name } }") do
  {:ok, %{data: data, errors: nil}} ->
    # Success
    IO.inspect(data)

  {:ok, %{data: nil, errors: errors}} ->
    # GraphQL errors
    IO.inspect(errors)

  {:error, error} ->
    # HTTP/transport error
    IO.inspect(error)
end