SPARQL.Client v0.2.2 SPARQL.Client View Source
A SPARQL protocol client.
The SPARQL Protocol consists of two HTTP operations:
- a query operation for performing SPARQL 1.0 and 1.1 Query Language queries
- an update operation for performing SPARQL Update Language requests, which is not implemented yet
Link to this section Summary
Functions
The query operation is used to send a SPARQL query to a service endpoint and receive the results of the query.
Link to this section Types
option()
View Source
option() ::
{:method, Tesla.Env.method()}
| {:url, Tesla.Env.url()}
| {:query, Tesla.Env.query()}
| {:headers, Tesla.Env.headers()}
| {:body, Tesla.Env.body()}
| {:opts, Tesla.Env.opts()}
option() :: {:method, Tesla.Env.method()} | {:url, Tesla.Env.url()} | {:query, Tesla.Env.query()} | {:headers, Tesla.Env.headers()} | {:body, Tesla.Env.body()} | {:opts, Tesla.Env.opts()}
Link to this section Functions
query(query, endpoint, options \\ %{}) View Source
The query operation is used to send a SPARQL query to a service endpoint and receive the results of the query.
The query can either be given as string or as an already parsed SPARQL.Query
.
with %SPARQL.Query{} = query <- SPARQL.Query.new("SELECT * WHERE { ?s ?p ?o }") do
SPARQL.Client.query(query, "http://dbpedia.org/sparql")
end
The type of the result returned depends on the query form:
SELECT
queries will return aSPARQL.Query.ResultSet
struct with a list ofSPARQL.Query.Result
structs in theresults
field.ASK
queries will return aSPARQL.Query.ResultSet
struct with the boolean result in theresults
fieldCONSTRUCT
andDESCRIBE
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
andprotocol_version: "1.1"
- query via URL-encoded POST: by setting the options as
request_method: :post
andprotocol_version: "1.0"
- query via POST directly: by setting the options as
request_method: :post
andprotocol_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 custom headers
You can specify custom headers for the HTTP request to the SPARQL service with
the headers
option and a map.
SPARQL.Client.query(query, "http://some.company.org/private/sparql",
headers: %{"Authorization" => "Basic XXX=="})
Specifying the response format
The SPARQL.Client
can handle all of 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
andASK
queries - Turtle being the preferred format for
CONSTRUCT
andDESCRIBE
queries
Although the returned result is mostly independent from 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 the default_graph
and named_graph
options and either a single dataset
names or lists of datasets.
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/"
])
Other options
max_redirects
: the number of redirects to follow before the operation fails (default:5
)request_opts
: will be passed as theopts
option value to theTesla.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]])
For a general introduction you may refer to the guides on the homepage.