Skip to content

SPARQL

SPARQL support is activated and configured through the public repository which is maintained in parallel to the main repository. SPARQL queries can be made either against the whole repository or a single context. The public repository contains only what the guest user can read: the metadata of public entries and, since 6.1, the resource graphs of public graph entries.

Configuration

The supported configuration settings are:

entrystore.repository.public=on|off (default: off)
entrystore.repository.public.type=memory|native (default: memory)
entrystore.repository.public.path=file:///srv/../../public
entrystore.repository.public.indexes=cspo,spoc,posc
entrystore.repository.public.rebuild-on-startup=on|off (default: off)
entrystore.repository.public.sparql.max-execution-time=<seconds> (default: 10)
entrystore.repository.public.sparql.max-response-bytes=<bytes> (6.x, default: 67108864, i.e. 64 MiB)
entrystore.repository.public.sparql.max-concurrent-queries=<number> (6.1, default: 4)
entrystore.repository.public.sparql.max-wait-time=<seconds> (6.1, default: 1)
entrystore.repository.public.sparql.expose-entry-graphs=on|off (6.1, default: off)

The type is either memory or native. The memory setting allows for faster SPARQL queries but requires an adequate amount of memory; since 6.1 the public repository also holds the resource graphs of public graph entries, so prefer the native store for large graph resources. As the memory store does not persist, a rebuild of the public repository takes place automatically upon start or restart of the EntryStore repository.

max-execution-time, max-response-bytes and max-concurrent-queries must be greater than 0 and max-wait-time must not be negative, otherwise EntryStore does not start. A query that runs longer than max-execution-time is answered with 504, a result larger than max-response-bytes with 413 (or a dropped connection if parts of the result have already been sent).

At most max-concurrent-queries queries are evaluated at the same time, on all SPARQL endpoints together and for all callers. A query that gets no slot within max-wait-time is answered with 503 and a Retry-After header; with 0 it is answered immediately. Each waiting request holds a thread, so keep max-wait-time well below the request timeout. A query holds its slot until its result is fully written or the connection times out. While queries are rejected, EntryStore logs a WARN at most once per minute with the number of rejected queries. Raise max-concurrent-queries if the heap allows it; per-client limits belong in the reverse proxy.

EntryStore 5.x

5.x has no response size limit and no concurrency limit, and a max-execution-time of 0 disables the time limit.

A rebuild on startup is performed under the following circumstances:

  • when explicitly turned on
  • when the public repository is empty (in the case of the native store), e.g. when it is used for the first time
  • on every startup when the configured store type is "memory"

To rebuild a native public repository, either start once with rebuild-on-startup=on or stop EntryStore and delete the contents of the directory configured in entrystore.repository.public.path. Keep the directory itself: if it is missing, EntryStore does not start.

Named graphs

The public repository stores each part of an entry that the guest user can read twice: in a named graph of its own and in the graph of its context ({base}/{context-id}). The parts are the local metadata (graph: the entry's metadata URI), the cached external metadata (its cached external metadata URI; it also requires read access to the entry's own metadata) and, for local graph entries, the resource graph (the entry's resource URI). The graph of a context holds the union of its entries' graphs.

Since 6.1:

  • Each part is published if the guest can read it. Before, an entry with any part the guest could not read was not published at all.
  • The resource graphs of public graph entries are published. Before, they were missing because of an error.
  • A statement that several entries of a context state stays in the context graph until the last of them is removed or no longer states it. Before, removing one of the entries also removed the statement from the context graph.
  • Deleting a context, or changing its access control, clears its context graph and the graphs of all its entries at once; the entries the guest can still read are then published again.

Since 6.1 the global endpoint exposes only the context graphs, unless expose-entry-graphs is set to on:

  • Patterns outside GRAPH read the union of the context graphs. A solution is returned once for each context that holds its statements, not once for each copy.
  • GRAPH ?g binds only context graphs. GRAPH, FROM and FROM NAMED with the URI of an entry's graph match nothing.
  • Limitation: inside GRAPH with a graph variable, zero-length matches of the property paths p* and p? can be missing when both ends of the path are unbound, and for p* also matches from a node to itself.

With expose-entry-graphs=on, the entry graphs are visible as in 5.x: GRAPH patterns and FROM lists match every graph that holds a statement, including both copies. Patterns outside GRAPH in queries without FROM or FROM NAMED still read only the context graphs.

EntryStore 5.x

5.x (and 6.0) exposes all named graphs. A query without FROM reads the union of all graphs, in which every public statement appears twice, so solutions of queries without DISTINCT repeat and aggregates such as COUNT are inflated. Queries with DISTINCT return the same results in 5.x and 6.1.

Usage

Queries can be made through either GET or POST requests. There are endpoints for every single context and a global endpoint. Only SELECT queries are supported. Queries with a SERVICE clause (federated queries) are rejected with 400 in 6.x, as are malformed queries. If the public repository is not activated, the endpoints answer with 501.

Note: Named Graph information is lost when querying against a specific context.

Context endpoint

http://{base}/{context-id}/sparql

For a context ID that does not exist or is not public, the context endpoint answers with 200 and an empty result, not with 404.

Global endpoint

http://{base}/sparql

Parameters for GET requests

  • query: the SPARQL query. Mandatory parameter which has to be URL encoded.
  • format: the format of the result. Possible values: application/sparql-results+json (or application/json), application/sparql-results+xml (or application/xml), text/csv (or application/sparql-results+csv), text/tab-separated-values (6.x) and application/x-binary-rdf-results-table. Optional parameter; if it is omitted the format is negotiated through the Accept header, and the default is binary output (application/x-binary-rdf-results-table).

In 6.x the response carries the media type of the selected format, e.g. application/sparql-results+json also when format=application/json was requested. An unsupported format is answered with 400, an Accept header that contains no supported type with 406.

The callback parameter (JSONP) has no effect on the SPARQL endpoints in 6.x; use CORS instead.

EntryStore 5.x

5.x responds with application/json, application/xml or text/csv as media type, falls back to binary output for an unsupported format, does not support TSV, and wraps JSON results in a JavaScript method if the callback parameter is provided (JSONP).

Parameters for POST requests

The parameters must be sent form-encoded (application/x-www-form-urlencoded) in the body of the POST request. The body must not be larger than 32 KB.

  • query: the SPARQL query.
  • output: the format of the result. Possible values: json, xml, csv or tsv (6.x). Optional parameter, default is json.

In 6.x an unsupported output value is answered with 400, a different content type with 415, and query or output in the URL query string instead of the body with 400. Other URL parameters, such as infer=false, are ignored (6.0 answered them with 400 as well).

EntryStore 5.x

5.x does not support tsv and returns binary output for an unsupported output value.