# `SPARQL.Client`
[🔗](https://github.com/rdf-elixir/sparql_client/blob/v0.5.1/lib/sparql_client.ex#L1)

A SPARQL protocol client.

The [SPARQL Protocol](https://www.w3.org/TR/sparql11-protocol/) defines how the operations
specified in the SPARQL query and update specs can be requested by a client from a
SPARQL service via HTTP.

This module provides dedicated functions for the various forms of SPARQL query and update
operations and generic `query/3` and `update/3` for the query and update operations.

For a general introduction you may refer to the guides on the [homepage](https://rdf-elixir.dev).

## Raw-mode

The query functions can be called with a `SPARQL.Query` struct or a SPARQL query as a raw string.
By default, a SPARQL query string will be parsed into a `SPARQL.Query` struct for validation
purposes before the string is sent via an HTTP request to the SPARQL protocol service endpoint.
This parsing step can be omitted by setting `:raw_mode` option to `true` on the dedicated
functions for the various SPARQL operation forms.

    "SELECT * { ?s ?p ?o .}"
    |> SPARQL.Client.select("http://example.com/sparql", raw_mode: true)

On the generic `SPARQL.Client.query/3` this raw-mode is not supported, since the parsing is
needed there to determine the query form which determines which result to expect.

For SPARQL update operations the picture is a little different. The SPARQL.ex package doesn't
provide parsing of SPARQL updates (yet), but except for `INSERT` and `DELETE` updates this isn't
actually needed, since all elements of the updates can be provided directly to the respective
functions for the update forms, which will generate valid SPARQL updates.

    RDF.Graph.new({EX.S, EX.p, EX.O})
    |> SPARQL.Client.insert_data("http://example.com/sparql")

You can still provide handwritten update strings to these functions, but due to the lack of
SPARQL update parsing the raw-mode is mandatory then. For the `INSERT` and `DELETE` update
forms this the only way to request them for now.

    """
    PREFIX dc:  <http://purl.org/dc/elements/1.1/>
    PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

    INSERT
    { GRAPH <http://example/bookStore2> { ?book ?p ?v } }
    WHERE
    { GRAPH  <http://example/bookStore>
         { ?book dc:date ?date .
           FILTER ( ?date > "1970-01-01T00:00:00-02:00"^^xsd:dateTime )
           ?book ?p ?v
    } }
    """
    |> SPARQL.Client.insert("http://example.com/sparql", raw_mode: true)

## Specifying custom headers

Custom headers for the HTTP request to the SPARQL service can be specified with the `headers`
option and a map.

    SPARQL.Client.query(query, "http://some.company.org/private/sparql",
      headers: %{"Authorization" => "Basic XXX=="})

## Specifying Tesla adapter specific options

The keyword list provided under the  `request_opts` options, will be passed as the `opts` option
value to the `Tesla.request/2` function.
This allows for example to set the timeout value for the Hackney adapter like this:

```elixir
SPARQL.Client.query(query, "http://example.com/sparql",
  request_opts: [adapter: [recv_timeout: 30_000]])
```

## Other options

- `max_redirects`: the number of redirects to follow before the operation fails (default: `5`)
- `logger`: allows to enable and configure the `Tesla.Middleware.Logger` by
  either setting it `true` or providing the `Tesla.Middleware.Logger` options
  (default: `false`)

## Application configuration of default values

Several default values for the options of the operations can be configured via the
Mix application environment.
Here's an example configuration showing all available configuration options:

    config :sparql_client,
      protocol_version: "1.1",
      query_request_method: :get,
      update_request_method: :direct,
      query_result_format: %{
        select: :json,
        ask: :json,
        construct: :turtle,
        describe: :turtle
      },
      http_headers: %{"Authorization" => "Basic YWxhZGRpbjpvcGVuc2VzYW1l"},
      tesla_request_opts: [adapter: [recv_timeout: 30_000]],
      max_redirects: 3,
      raw_mode: true

The `http_headers` can also be set to a function receiving the `SPARQL.Client.Request`
struct and the computed default headers:

    defmodule SomeModule do
      def http_header_config(request, _headers) do
        if request.sparql_operation_type == SPARQL.Client.Update do
          %{"Authorization" => "Basic YWxhZGRpbjpvcGVuc2VzYW1l"}
        else
          %{}
        end
    end

    config :sparql_client,
      http_headers: &SomeModule.http_header_config/2,

# `add`

Executes a SPARQL `ADD` update operation against a service endpoint.

The source graph must be specified with the `:from` option and the destination graph with the
`:to` option either as a string, `RDF.IRI`, vocabulary namespace term for the graph name or
`:default` for the default graph. The source graph can also be a list of graphs with any of the above as elements.

    SPARQL.Client.add("http://example.com/sparql",
      from: "http://example.com/Graph1", to: "http://example.com/Graph2")

    SPARQL.Client.add("http://example.com/sparql",
      from: :default, to: EX.Graph)

The update operation can be run in `SILENT` mode by setting the `:silent` option to `true`.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `add`

Executes a SPARQL `ADD` update operation against a service endpoint.

This version only allows execution of `ADD` updates given as string in raw-mode (see the
[module documentation](`SPARQL.Client`) for more information on the raw-mode).

    "ADD GRAPH <http://example.com/Graph1> TO GRAPH <http://example.com/Graph2>"
    |> SPARQL.Client.add("http://example.com/sparql", raw_mode: true)

See `add/2` for how to execute a `ADD` update with an automatically built update string.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `ask`

Executes a SPARQL `ASK` query operation against a service endpoint.

See documentation of the generic `query/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `clear`

Executes a SPARQL `CLEAR` update operation against a service endpoint.

The graph name must be specified with the `:graph` option either as a string, `RDF.IRI`,
vocabulary namespace term, one of the special values `:default`, `:named`, `:all`, or a list of
any of the above.

    SPARQL.Client.clear("http://example.com/sparql", graph: "http://example.com/Graph")

    SPARQL.Client.clear("http://example.com/sparql", graph: EX.Graph)

The update operation can be run in `SILENT` mode by setting the `:silent` option to `true`.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `clear`

Executes a SPARQL `CLEAR` update operation against a service endpoint.

This version only allows execution of `CLEAR` updates given as string in raw-mode (see the
[module documentation](`SPARQL.Client`) for more information on the raw-mode).

    "CLEAR <http://example.com/Graph>"
    |> SPARQL.Client.clear("http://example.com/sparql", raw_mode: true)

See `clear/2` for how to execute a `CLEAR` update with an automatically built update string.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `construct`

Executes a SPARQL `CONSTRUCT` query operation against a service endpoint.

See documentation of the generic `query/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `copy`

Executes a SPARQL `COPY` update operation against a service endpoint.

The source graph must be specified with the `:from` option and the destination graph with the
`:to` option either as a string, `RDF.IRI`, vocabulary namespace term for the graph name or
`:default` for the default graph. 

    SPARQL.Client.copy("http://example.com/sparql",
      from: "http://example.com/Graph1", to: "http://example.com/Graph2")

    SPARQL.Client.copy("http://example.com/sparql",
      from: :default, to: EX.Graph)

The update operation can be run in `SILENT` mode by setting the `:silent` option to `true`.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `copy`

Executes a SPARQL `COPY` update operation against a service endpoint.

This version only allows execution of `COPY` updates given as string in raw-mode (see the
[module documentation](`SPARQL.Client`) for more information on the raw-mode).

    "COPY GRAPH <http://example.com/Graph1> TO GRAPH <http://example.com/Graph2>"
    |> SPARQL.Client.copy("http://example.com/sparql", raw_mode: true)

See `copy/2` for how to execute a `COPY` update with an automatically built update string.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `create`

Executes a SPARQL `CREATE` update operation against a service endpoint.

The graph name must be specified with the `:graph` option either as a string, `RDF.IRI`,
vocabulary namespace term, one of the special values `:default`, `:named`, `:all`, or a list of
any of the above.

    SPARQL.Client.create("http://example.com/sparql", graph: "http://example.com/Graph")

    SPARQL.Client.create("http://example.com/sparql", graph: EX.Graph)

The update operation can be run in `SILENT` mode by setting the `:silent` option to `true`.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `create`

Executes a SPARQL `CREATE` update operation against a service endpoint.

This version only allows execution of `CREATE` updates given as string in raw-mode (see the
[module documentation](`SPARQL.Client`) for more information on the raw-mode).

    "CREATE <http://example.com/Graph>"
    |> SPARQL.Client.create("http://example.com/sparql", raw_mode: true)

See `create/2` for how to execute a `CREATE` update with an automatically built update string.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `delete`

Executes a SPARQL `DELETE` update operation against a service endpoint.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `delete_data`

Executes a SPARQL `DELETE DATA` update operation against a service endpoint.

The `DELETE DATA` update can either be given as string (only in raw-mode; see the
[module documentation](`SPARQL.Client`) for more information on the raw-mode) or
by providing the data to be deleted directly via an RDF.ex data structure
(`RDF.Graph`, `RDF.Description` or `RDF.Dataset`).

    RDF.Graph.new({EX.S, EX.p, EX.O})
    |> SPARQL.Client.delete_data("http://example.com/sparql")

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `describe`

Executes a SPARQL `DESCRIBE` query operation against a service endpoint.

See documentation of the generic `query/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `drop`

Executes a SPARQL `DROP` update operation against a service endpoint.

The graph name must be specified with the `:graph` option either as a string, `RDF.IRI`,
vocabulary namespace term, one of the special values `:default`, `:named`, `:all`, or a list of
any of the above.

    SPARQL.Client.drop("http://example.com/sparql", graph: "http://example.com/Graph")

    SPARQL.Client.drop("http://example.com/sparql", graph: EX.Graph)

The update operation can be run in `SILENT` mode by setting the `:silent` option to `true`.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `drop`

Executes a SPARQL `DROP` update operation against a service endpoint.

This version only allows execution of `DROP` updates given as string in raw-mode (see the
[module documentation](`SPARQL.Client`) for more information on the raw-mode).

    "DROP <http://example.com/Graph>"
    |> SPARQL.Client.drop("http://example.com/sparql", raw_mode: true)

See `drop/2` for how to execute a `DROP` update with an automatically built update string.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `insert`

Executes a SPARQL `INSERT` update operation against a service endpoint.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `insert_data`

Executes a SPARQL `INSERT DATA` update operation against a service endpoint.

The `INSERT DATA` update can either be given as string (only in raw-mode; see the
[module documentation](`SPARQL.Client`) for more information on the raw-mode) or
by providing the data to be inserted directly via an RDF.ex data structure
(`RDF.Graph`, `RDF.Description` or `RDF.Dataset`).

    RDF.Graph.new({EX.S, EX.p, EX.O})
    |> SPARQL.Client.insert_data("http://example.com/sparql")

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `load`

Executes a SPARQL `LOAD` update operation against a service endpoint.

The URL from to be loaded must be specified with the `:from` option. The graph name
to which the data should be loaded can be given with the `:to` option. Both options
expect a URI as a value which can be given as a string, `RDF.IRI` or vocabulary namespace term.
The `:to` option can also be `:default` to explicitly load into the default graph.

    SPARQL.Client.load("http://example.com/sparql", from: "http://example.com/Resource")

    SPARQL.Client.load("http://example.com/sparql", from: EX.Resource, to: EX.Graph)

    SPARQL.Client.load("http://example.com/sparql", from: EX.Resource, to: :default)

The update operation can be run in `SILENT` mode by setting the `:silent` option to `true`.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `load`

Executes a SPARQL `LOAD` update operation against a service endpoint.

This version only allows execution of `LOAD` update given as string in raw-mode (see the
[module documentation](`SPARQL.Client`) for more information on the raw-mode).

    "LOAD <http://example.com/Resource>"
    |> SPARQL.Client.load("http://example.com/sparql", raw_mode: true)

See `load/2` for how to execute a `LOAD` update with an automatically built update string.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `move`

Executes a SPARQL `MOVE` update operation against a service endpoint.

The source graph must be specified with the `:from` option and the destination graph with the
`:to` option either as a string, `RDF.IRI`, vocabulary namespace term for the graph name or
`:default` for the default graph. 

    SPARQL.Client.move("http://example.com/sparql",
      from: "http://example.com/Graph1", to: "http://example.com/Graph2")

    SPARQL.Client.move("http://example.com/sparql",
      from: :default, to: EX.Graph)

The update operation can be run in `SILENT` mode by setting the `:silent` option to `true`.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `move`

Executes a SPARQL `MOVE` update operation against a service endpoint.

This version only allows execution of `MOVE` updates given as string in raw-mode (see the
[module documentation](`SPARQL.Client`) for more information on the raw-mode).

    "MOVE GRAPH <http://example.com/Graph1> TO GRAPH <http://example.com/Graph2>"
    |> SPARQL.Client.move("http://example.com/sparql", raw_mode: true)

See `move/2` for how to execute a `MOVE` update with an automatically built update string.

See documentation of the generic `update/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `query`

Executes any form of a SPARQL query operation against a service endpoint.

The query can either be given as string or as an already parsed `SPARQL.Query`.

    "SELECT * WHERE { ?s ?p ?o }"
    |> SPARQL.Client.query(query, "http://dbpedia.org/sparql")

    with %SPARQL.Query{} = query <- SPARQL.Query.new("SELECT * WHERE { ?s ?p ?o }") do
      SPARQL.Client.query(query, "http://dbpedia.org/sparql")
    end

For the execution of queries in raw-mode see the [module documentation](`SPARQL.Client`)

The result is in the success case returned in a `:ok` tuple or in error cases in an `:error`
tuple with an error message or in case of a non-200 response by the SPARQL service with a
`SPARQL.Client.HTTPError`.

The type of the result returned depends on the query form:

- `SELECT` queries will return a `SPARQL.Query.Result` struct
- `ASK` queries will return a `SPARQL.Query.Result` struct with the boolean
  result in the `results` field
- `CONSTRUCT` and `DESCRIBE` queries will return an RDF data structure

## Specifying the request method

The SPARQL 1.1 protocol spec defines [three methods](https://www.w3.org/TR/sparql11-protocol/#query-operation)
to perform a SPARQL query operation via HTTP, which can be specified via the
`:request_method` and `:protocol_version` options:

1. query via GET: by setting the options as `request_method: :get` and `protocol_version: "1.1"`
2. query via URL-encoded POST: by setting the options as `request_method: :post` and `protocol_version: "1.0"`
3. query via POST directly: by setting the options as `request_method: :post` and `protocol_version: "1.1"`

In order to work with SPARQL 1.0 services out-of-the-box the second method,
query via URL-encoded POST, is the default.

To perform previous query via GET, you would have to call it like this:

    SPARQL.Client.query(query, "http://dbpedia.org/sparql",
      request_method: :get, protocol_version: "1.1")

## Specifying the response format

The `SPARQL.Client` can handle all the specified result formats for SPARQL
tuple results (JSON, XML, CSV and TSV) and for `CONSTRUCT` and `DESCRIBE` queries
all RDF serialization formats supported by [RDF.ex](https://github.com/rdf-elixir/rdf-ex)
can be handled.

If no custom `Accept` header is specified, all accepted formats for the resp.
query form will be set automatically, with

- JSON being the preferred format for `SELECT` and `ASK` queries
- Turtle being the preferred format for `CONSTRUCT` and `DESCRIBE` queries

Although the returned result is mostly independent of the actually returned
response format from the service, you might want to set it manually with the
`:result_format` and the name of the format

    SPARQL.Client.query(query, "http://some.company.org/private/sparql",
      result_format: :xml)

These are the names of the supported formats:

- tuple result formats: `:json, :xml, :csv, :tsv`
- RDF result formats: `:turtle, :ntriples, :nquads, :jsonld`

When a `:result_format` is specified the `Accept` header is set to the corresponding
media type. You might however still want to overwrite the `Accept` header, for
example when a SPARQL service uses a non-standard media type for a format.
Note that, when providing a custom non-standard `Accept` header the `result_format`
option is mandatory.

## Specifying an RDF Dataset

The RDF dataset to be queried can be specified [as described in the spec](https://www.w3.org/TR/sparql11-protocol/#dataset)
via the `:default_graph` and `:named_graph` options and either a single graph
name or lists of graphs.

    SPARQL.Client.query(query, "http://some.company.org/private/sparql",
      default_graph: "http://www.example/sparql/",
      named_graph: [
        "http://www.other.example/sparql/",
        "http://www.another.example/sparql/"
      ])

Similarly, the `:using_graph` and `:using_named_graph` can be used to
specify the dataset on update operation [as described in the spec](https://www.w3.org/TR/sparql11-protocol/#update-dataset).

    SPARQL.Client.update(update, "http://some.company.org/private/sparql",
      using_graph: "http://www.example/sparql/",
      using_named_graph: [
        "http://www.other.example/sparql/",
        "http://www.another.example/sparql/"
      ])

# `select`

Executes a SPARQL `SELECT` query operation against a service endpoint.

See documentation of the generic `query/3` function and the [module documentation](`SPARQL.Client`) for the available options.

# `update`

Executes any form of a SPARQL update operation against a service endpoint.

In case of this generic function, updates can be given only as string and executed in raw-mode
(see the [module documentation](`SPARQL.Client`) for a description of the raw-mode)

    """
    PREFIX dc:  <http://purl.org/dc/elements/1.1/>
    PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

    INSERT
    { GRAPH <http://example/bookStore2> { ?book ?p ?v } }
    WHERE
    { GRAPH  <http://example/bookStore>
         { ?book dc:date ?date .
           FILTER ( ?date > "1970-01-01T00:00:00-02:00"^^xsd:dateTime )
           ?book ?p ?v
    } }
    """
    |> SPARQL.Client.update("http://example.com/sparql", raw_mode: true)

The result for all updates is either `:ok` or an `:error` tuple in error cases with an error
message or in case of a non-2XX response by the SPARQL service with a `SPARQL.Client.HTTPError`.

## Specifying the request method

The SPARQL 1.1 protocol spec defines [two methods](https://www.w3.org/TR/sparql11-protocol/#update-operation)
to perform a SPARQL update operation via HTTP, which can be specified via the
`request_method` option:

1. Update via URL-encoded POST: by setting the options `request_method: :url_encoded`
2. Update via POST directly: by setting the options `request_method: :direct` (default)

---

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