Need private packages and team management tools?Check out npm Teams »


1.12.0 • Public • Published

Comunica SPARQL

npm version Docker Pulls

Linked Data on the Web is being published in different ways, such as data dumps, subject pages, results of SPARQL queries, and Triple Pattern Fragments. This client is able to solve queries over such heterogeneous interfaces.

Concretely, Comunica SPARQL is a module that is preconfigured with a configuration file to initialize the Comunica engine with actors to evaluate SPARQL queries over heterogeneous interfaces.

It's main distinguishing features are the following:

  • High modularity enabling easy extensions and customization.
  • Federated querying over heterogeneous interfaces.
  • Can run using Node.JS, in the browser, and via the command-line.

Comunica can either be invoked dynamically using a configuration file, or statically using a pre-compiled configuration file. The latter will be faster to start because the dependency-injection phase can be avoided.

This actor can not query over local files for security reasons, but Comunica SPARQL file can.


Comunica requires Node.JS 8.0 or higher and is tested on OSX and Linux.

The easiest way to install the client is by installing it from NPM as follows:

$ [sudo] npm install -g @comunica/actor-init-sparql

Alternatively, you can install from the latest GitHub sources. For this, please refer to the README of the Comunica monorepo.

Execute SPARQL queries

This actor can be used to execute SPARQL queries from the command line, HTTP (SPARQL protocol), within a Node.JS application, or from a browser.

Usage from the command line

Show 100 triples from

$ comunica-sparql "CONSTRUCT WHERE { ?s ?p ?o } LIMIT 100"

Show all triples from

$ comunica-sparql "CONSTRUCT WHERE { ?s ?p ?o }"

Combine multiple sources:

$ comunica-sparql file@ "CONSTRUCT WHERE { ?s ?p ?o } LIMIT 100"

Show the help with all options:

$ comunica-sparql --help

The dynamic variant of this executable is comunica-dynamic-sparql. An alternative config file can be passed via the COMUNICA_CONFIG environment variable.

When you are working with this module in the Comunica monorepo development environment, this command can be invoked directly as follows (when inside the packages/actor-init-sparql folder):

node bin/query.js "CONSTRUCT WHERE { ?s ?p ?o } LIMIT 100"

Use bin/query-dynamic.js when running dynamically inside the Comunica monorepo development environment.

Usage as a SPARQL endpoint

Start a webservice exposing via the SPARQL protocol, i.e., a SPARQL endpoint.

$ comunica-sparql-http "\"sources\": [\"\"]}"


$ comunica-sparql-http "\"sources\": [{ \"type\" : \"file\"\"value\" : \"\" }]}"

Show the help with all options:

$ comunica-sparql-http --help

The SPARQL endpoint can only be started dynamically. An alternative config file can be passed via the COMUNICA_CONFIG environment variable.

Use bin/http.js when running in the Comunica monorepo development environment.

Usage within application

The easiest way to create an engine (with default config) is as follows:

const newEngine = require('@comunica/actor-init-sparql').newEngine;
const myEngine = newEngine();

Alternatively, an engine can also be created dynamically with a custom config:

const newEngineDynamic = require('@comunica/actor-init-sparql').newEngineDynamic;
const myEngine = await newEngineDynamic({ configResourceUrl: 'path/to/config.json' });

Once you have created your query engine, you can use it to call the async query(queryString, context) method, which returns an output of type that depends on the given query string.

For example, a SELECT query can be executed as follows:

const result = await myEngine.query('SELECT * WHERE { ?s ?p <>. ?s ?p ?o } LIMIT 100',
  { sources: [''] })
result.bindingsStream.on('data', (data) => console.log(data.toObject()));

Optionally, specific types of sources can be specified (otherwise, the type of source will be detected automatically):

const result = await myEngine.query('SELECT * WHERE { ?s ?p <>. ?s ?p ?o } LIMIT 100',
  { sources: [
    { type: 'sparql', value: '' },
    { type: 'file', value: '' },
    { type: 'rdfjsSource', value: new N3Store() },
  ] })
result.bindingsStream.on('data', (data) => console.log(data.toObject()));

Note: Some SPARQL endpoints may be recognised as a file instead of a SPARQL endpoint due to them not supporting SPARQL Service Description, which may produce incorrect results. For these cases, the sparql type MUST be set.

For CONSTRUCT and DESCRIBE queries, results can be collected as follows.

const result = await myEngine.query('CONSTRUCT WHERE { ?s ?p <> } LIMIT 100',
  { sources: [''] })
result.quadStream.on('data', (data) => console.log(data));

Finally, ASK queries return async booleans.

const result = await myEngine.query('ASK { ?s ?p <> }',
  { sources: [''] })
const isPresent = await result.booleanResult;

Context options:

Key Description
sources An array of data sources, e.g. [ { value: '' } ]. Optionally, a source can have a type field to force a specific type. For example, [ { type: 'file', value: '' } ] will make sure the source is seen as a file with all hypermedia ignored. Source types can be forced as: sparql, file, rdfjsSource
initialBindings Variables that have to be pre-bound to values in the query, using the Bindings datastructure, e.g. Bindings({ '?s': literal('sl') }).
queryFormat Name of the provided query's format. Defaults to sparql, can also be graphql
baseIRI Base IRI for relative IRIs in SPARQL queries, e.g.
log Logger to use, e.g. new LoggerPretty({ level: 'warn' }).
datetime Datetime to handle time travel with Memento, e.g. new Date().
lenient If failing requests and parsing errors should be logged instead of causing a hard crash. Defaults to false.

(Optional) Result formatting

As mentioned before, query results are either a bindingsStream (for SELECT queries), quadStream (for CONSTRUCT queries), or booleanResult (for ASK queries).

Using the @comunica/actor-sparql-serialize-* actors, Comunica allows these results to be serialized into standard formats in a streaming manner.

For example, serializing results to the SPARQL/JSON format can be done as follows:

const result = await myEngine.query('SELECT * WHERE { ?s ?p <>. ?s ?p ?o } LIMIT 100',
  { sources: [''] });
const { data } = await myEngine.resultToString(result, 'application/sparql-results+json');

Passing a media type as second argument is optional. If none is supplied, then application/json will be picked for bindings, application/trig for quads, and simple for booleans.

By default, the following result formats are available:

Media type Description
application/json A custom, simplified JSON result format.
simple A custom, text-based result format.
application/sparql-results+json The SPARQL/JSON results format.
application/sparql-results+xml The SPARQL/XML results format.
stats A custom results format for testing and debugging.
table A text-based visual table result format.
tree A tree-based result format for GraphQL-LD result compacting.
application/trig The TriG RDF serialization.
application/n-quads The N-Quads RDF serialization.
text/turtle The Turtle RDF serialization.
application/n-triples The N-Triples RDF serialization.
text/n3 The Notation3 serialization.
application/ld+json The JSON-LD RDF serialization.

This list of available formats can also be retrieved dynamically by invoking the (asynchronous) engine.getResultMediaTypes() method.

On the command-line, the result format can be set using the -t flag:

$ comunica-sparql "SELECT * WHERE { ?s ?p ?o }" -t 'application/sparql-results+json'

All available result formats can be listed from the command-line using --listformats:

$ comunica-sparql --listformats

(Optional) Cache handling

When remote documents are fetched over HTTP, a Comunica engine can cache documents to optimize future reuse. If your application works over volatile resources, then you may want to invalidate this cache, which can be done as follows:

myEngine.invalidateHttpCache(); // Invalidate the full cache
myEngine.invalidateHttpCache(''); // Invalidate a single document

(Optional) GraphQL-LD

Instead of SPARQL queries, you can also define GraphQL queries (with a JSON-LD context).

If you want to convert your results to a GraphQL tree, then you will need the @comunica/actor-sparql-serialize-tree dependency, otherwise you can consume the bindings stream manually.

const newEngine = require('@comunica/actor-init-sparql').newEngine;
const bindingsStreamToGraphQl = require('@comunica/actor-sparql-serialize-tree').bindingsStreamToGraphQl;
const myEngine = newEngine();
const config = {
  sources: [''],
  queryFormat: 'graphql',
  "@context": {
    "label": { "@id": "" },
    "label_en": { "@id": "", "@language": "en" },
    "writer": { "@id": "" },
    "artist": { "@id": "" }
myEngine.query('{ label @single writer(label_en: \"Michael Jackson\") @single artist @single { label @single } }', config)
  .then(function (result) { return bindingsStreamToGraphQl(result.bindingsStream, result.context); })

To run GraphQL queries from the command line, set the -i flag to graphql and refer to your config file with the JSON-LD context (@context) through the -c flag. To output your results as a GraphQL tree, set the MIME type of the output with -t to tree. For example:

$ comunica-sparql -q "{ label @single }" -c config-with-context.json -i graphql -t tree

(Optional) Logging

Optionally, a custom logger can be used inside Comunica. By default, @comunica/logger-void is used, which will simply void all log calls. (This default can be changed in the configuration file)

Alternatively, @comunica/logger-pretty, @comunica/logger-bunyan, or a custom logger implementing the Logger interface can be used.

These loggers can be configured through the context as follows:

import {LoggerPretty} from "@comunica/logger-pretty";
const context = {
  log: new LoggerPretty({ level: 'warn' });
myEngine.query('...', context);

(Optional) Proxy

Optionally, you can configure a proxy to redirect all HTTP(S) traffic. This is for example useful when Comunica is used in a Web browser where a proxy enables CORS headers on all responses.

Via the command line, a proxy can be enabled as follows:

$ comunica-sparql "CONSTRUCT WHERE { ?s ?p ?o } LIMIT 100" -p

This will cause all requests to be modified by appending the original URL to the proxy URL

A proxy can also be configured via the programmatic API as follows:

const ProxyHandlerStatic = require("@comunica/actor-http-proxy").ProxyHandlerStatic;
const result = await myEngine.query('SELECT * WHERE { ?s ?p <>. ?s ?p ?o } LIMIT 100',
    sources: [ { type: 'hypermedia', value: '' } ],
    httpProxyHandler: new ProxyHandlerStatic(''),

Next to ProxyHandlerStatic, more advanced proxy handlers can be created by implementing IProxyHandler.

Usage within browser

(Just want to quickly demo queries in the browser? Have a look at our Web client)

This engine can run in the browser using Webpack. To create a web-packed version of the engine, run yarn run browser (when inside the packages/actor-init-sparql folder) to create comunica-browser.js. Alternatively, just use a pre-built version from our CDN.

Include this file in your webpage as follows:

<script src="path/to/comunica-browser.js"></script>

After that, Comunica.newEngine can be called via JavaScript.

const myEngine = Comunica.newEngine();
myEngine.query('SELECT * { ?s ?p <>. ?s ?p ?o } LIMIT 100',
  { sources: [''] })
  .then(function (result) {
    result.bindingsStream.on('data', function (data) {

The browser script is pre-compiled using a config file and can therefore only be invoked dynamically. See the prepare and browser scripts in package.json to compile using a custom config file.

If you want to use GraphQL-LD here as well, you can do this similar as in the Node.JS API using Comunica.bindingsStreamToGraphQl


npm i @comunica/actor-init-sparql

DownloadsWeekly Downloads






Unpacked Size

208 kB

Total Files


Last publish


  • avatar
  • avatar
  • avatar