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

Triples (turtle) API for TerminusDB.

Wraps the `/api/triples/{path}/{graph_type}` endpoints for reading and
writing graph contents as turtle-encoded triples.

All functions require a `TerminusDB.Config` scoped to a database.

## Quick start

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

    {:ok, turtle} = TerminusDB.Triples.get(config)
    {:ok, _} = TerminusDB.Triples.update(config, turtle, author: "admin", message: "replace")
    {:ok, _} = TerminusDB.Triples.insert(config, more_turtle, author: "admin", message: "add")

# `triples_opt`

```elixir
@type triples_opt() ::
  {:graph_type, :instance | :schema}
  | {:organization, String.t()}
  | {:repo, String.t()}
  | {:author, String.t()}
  | {:message, String.t()}
```

# `get`

```elixir
@spec get(TerminusDB.Config.t(), [triples_opt()]) ::
  {:ok, String.t()} | {:error, TerminusDB.Error.t()}
```

Retrieves the contents of the specified graph as turtle-encoded triples.

## Options

- `:graph_type` — `:instance` (default) or `:schema`.
- `:organization` — overrides `config.organization`.
- `:repo` — overrides `config.repo`.

## Examples

    iex> config = TerminusDB.Config.new(
    ...>   endpoint: "http://localhost:6363",
    ...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: "@prefix : <http://example.org/> .")} end
    ...> ) |> TerminusDB.Config.with_database("mydb")
    iex> {:ok, turtle} = TerminusDB.Triples.get(config)
    iex> turtle
    "@prefix : <http://example.org/> ."

# `get!`

```elixir
@spec get!(TerminusDB.Config.t(), [triples_opt()]) :: String.t()
```

Retrieves triples, or raises.

## Examples

    iex> config = TerminusDB.Config.new(
    ...>   endpoint: "http://localhost:6363",
    ...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: "<http://example.org/foo> <http://example.org/bar> <http://example.org/baz> .")} end
    ...> ) |> TerminusDB.Config.with_database("mydb")
    iex> TerminusDB.Triples.get!(config)
    "<http://example.org/foo> <http://example.org/bar> <http://example.org/baz> ."

# `insert`

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

Inserts turtle triples into the graph (additive).

## Options

Same as `update/3`.

## Examples

    iex> config = TerminusDB.Config.new(
    ...>   endpoint: "http://localhost:6363",
    ...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
    ...> ) |> TerminusDB.Config.with_database("mydb")
    iex> {:ok, resp} = TerminusDB.Triples.insert(config, ":foo :bar :baz .", author: "admin", message: "add")
    iex> resp["api:status"]
    "api:success"

# `insert!`

```elixir
@spec insert!(TerminusDB.Config.t(), String.t(), [triples_opt()]) :: map()
```

Inserts turtle triples, or raises.

## Examples

    iex> config = TerminusDB.Config.new(
    ...>   endpoint: "http://localhost:6363",
    ...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
    ...> ) |> TerminusDB.Config.with_database("mydb")
    iex> TerminusDB.Triples.insert!(config, ":foo :bar :baz .")
    %{"api:status" => "api:success"}

# `update`

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

Replaces the entire graph with the given turtle triples.

## Options

- `:author` — commit author.
- `:message` — commit message.
- `:graph_type` — `:instance` (default) or `:schema`.
- `:organization` — overrides `config.organization`.
- `:repo` — overrides `config.repo`.

## Examples

    iex> config = TerminusDB.Config.new(
    ...>   endpoint: "http://localhost:6363",
    ...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
    ...> ) |> TerminusDB.Config.with_database("mydb")
    iex> {:ok, resp} = TerminusDB.Triples.update(config, "@prefix : <http://example.org/> .", author: "admin", message: "replace")
    iex> resp["api:status"]
    "api:success"

# `update!`

```elixir
@spec update!(TerminusDB.Config.t(), String.t(), [triples_opt()]) :: map()
```

Replaces graph with turtle triples, or raises.

## Examples

    iex> config = TerminusDB.Config.new(
    ...>   endpoint: "http://localhost:6363",
    ...>   adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
    ...> ) |> TerminusDB.Config.with_database("mydb")
    iex> TerminusDB.Triples.update!(config, "@prefix : <http://example.org/> .")
    %{"api:status" => "api:success"}

---

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