View Source SPARQL.Client (SPARQL.Client v0.5.0)

A SPARQL protocol client.

The SPARQL 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.

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:

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,

Summary

Functions

add(endpoint, opts)

Executes a SPARQL ADD update operation against a service endpoint.

add(update, endpoint, opts)

Executes a SPARQL ADD update operation against a service endpoint.

ask(query, endpoint, opts \\ [])

Executes a SPARQL ASK query operation against a service endpoint.

clear(endpoint, opts)

Executes a SPARQL CLEAR update operation against a service endpoint.

clear(update, endpoint, opts)

Executes a SPARQL CLEAR update operation against a service endpoint.

construct(query, endpoint, opts \\ [])

Executes a SPARQL CONSTRUCT query operation against a service endpoint.

copy(endpoint, opts)

Executes a SPARQL COPY update operation against a service endpoint.

copy(update, endpoint, opts)

Executes a SPARQL COPY update operation against a service endpoint.

create(endpoint, opts)

Executes a SPARQL CREATE update operation against a service endpoint.

create(update, endpoint, opts)

Executes a SPARQL CREATE update operation against a service endpoint.

delete(update, endpoint, opts \\ [])

Executes a SPARQL DELETE update operation against a service endpoint.

delete_data(data_or_update, endpoint, opts \\ [])

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

describe(query, endpoint, opts \\ [])

Executes a SPARQL DESCRIBE query operation against a service endpoint.

drop(endpoint, opts)

Executes a SPARQL DROP update operation against a service endpoint.

drop(update, endpoint, opts)

Executes a SPARQL DROP update operation against a service endpoint.

insert(update, endpoint, opts \\ [])

Executes a SPARQL INSERT update operation against a service endpoint.

insert_data(data_or_update, endpoint, opts \\ [])

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

load(endpoint, opts)

Executes a SPARQL LOAD update operation against a service endpoint.

load(update, endpoint, opts)

Executes a SPARQL LOAD update operation against a service endpoint.

move(endpoint, opts)

Executes a SPARQL MOVE update operation against a service endpoint.

move(update, endpoint, opts)

Executes a SPARQL MOVE update operation against a service endpoint.

query(query, endpoint, opts \\ [])

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

select(query, endpoint, opts \\ [])

Executes a SPARQL SELECT query operation against a service endpoint.

update(update, endpoint, opts \\ [])

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

Functions

add(endpoint, opts)

Executes a SPARQL ADD update operation against a service endpoint.

The source graph must be specified with the :graph 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.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 for the available options.

add(update, endpoint, opts)

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 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 for the available options.

ask(query, endpoint, opts \\ [])

Executes a SPARQL ASK query operation against a service endpoint.

See documentation of the generic query/3 function and the module documentation for the available options.

clear(endpoint, opts)

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 or one of the special values :default, :named, :all.

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 for the available options.

clear(update, endpoint, opts)

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 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 for the available options.

construct(query, endpoint, opts \\ [])

Executes a SPARQL CONSTRUCT query operation against a service endpoint.

See documentation of the generic query/3 function and the module documentation for the available options.

copy(endpoint, opts)

Executes a SPARQL COPY update operation against a service endpoint.

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 for the available options.

copy(update, endpoint, opts)

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 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 for the available options.

create(endpoint, opts)

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 or one of the special values :default, :named, :all.

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 for the available options.

create(update, endpoint, opts)

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 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 for the available options.

delete(update, endpoint, opts \\ [])

Executes a SPARQL DELETE update operation against a service endpoint.

See documentation of the generic update/3 function and the module documentation for the available options.

delete_data(data_or_update, endpoint, opts \\ [])

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 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 for the available options.

describe(query, endpoint, opts \\ [])

Executes a SPARQL DESCRIBE query operation against a service endpoint.

See documentation of the generic query/3 function and the module documentation for the available options.

drop(endpoint, opts)

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 or one of the special values :default, :named, :all.

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 for the available options.

drop(update, endpoint, opts)

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 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 for the available options.

insert(update, endpoint, opts \\ [])

Executes a SPARQL INSERT update operation against a service endpoint.

See documentation of the generic update/3 function and the module documentation for the available options.

insert_data(data_or_update, endpoint, opts \\ [])

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 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 for the available options.

load(endpoint, opts)

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.

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)

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 for the available options.

load(update, endpoint, opts)

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 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 for the available options.

move(endpoint, opts)

Executes a SPARQL MOVE update operation against a service endpoint.

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 for the available options.

move(update, endpoint, opts)

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 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 for the available options.

query(query, endpoint, opts \\ [])

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

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 to perform a SPARQL query operation via HTTP, which can be specified via the :request_method and :protocol_version options:

query via GET: by setting the options as request_method: :get and protocol_version: "1.1"
query via URL-encoded POST: by setting the options as request_method: :post and protocol_version: "1.0"
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 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 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.

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(query, endpoint, opts \\ [])

Executes a SPARQL SELECT query operation against a service endpoint.

See documentation of the generic query/3 function and the module documentation for the available options.

update(update, endpoint, opts \\ [])

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 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 to perform a SPARQL update operation via HTTP, which can be specified via the request_method option:

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