		stars 🌟	issues ⚠️	updated 🛠	created 🐣	size 🏋️‍♀️
	@comunica/actor-init-sparql	210	90	Jun 16, 2021	Oct 18, 2017

Comunica SPARQL

Comunica SPARQL is a SPARQL query engine for JavaScript for querying over decentralized RDF knowledge graphs on the Web.

It's main distinguishing features are the following:

Execute SPARQL 1.1 or GraphQL-LD queries.
Federated querying over heterogeneous interfaces, such as RDF files, SPARQL endpoints, Triple Pattern Fragments, or Solid data pods.
High modularity enabling easy extensions and customization.
Runs in JavaScript using Node.JS, in the browser, and via the command-line.
Update sources using SPARQL 1.1 Update queries (currently only over RDF/JS stores).

Learn more about Comunica on our website.

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

Internally, this is a Comunica module that is configured with modules to execute SPARQL queries.

Installation

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 http://fragments.dbpedia.org/2015-10/en:

$ comunica-sparql http://fragments.dbpedia.org/2015-10/en "CONSTRUCT WHERE { ?s ?p ?o } LIMIT 100"

Show all triples from http://dbpedia.org/resource/Belgium:

$ comunica-sparql http://dbpedia.org/resource/Belgium "CONSTRUCT WHERE { ?s ?p ?o }"

Combine multiple sources:

$ comunica-sparql http://fragments.dbpedia.org/2015-10/en \
  file@http://dbpedia.org/resource/Belgium "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 http://fragments.dbpedia.org/2016-04/en "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 http://fragments.dbpedia.org/2015-10/en via the SPARQL protocol, i.e., a SPARQL endpoint.

$ comunica-sparql-http http://fragments.dbpedia.org/2015/en

This command has a similar signature to comunica-sparql, minus the query input options.

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 ?s ?p ?o WHERE {
    ?s ?p <http://dbpedia.org/resource/Belgium>.
    ?s ?p ?o
  } LIMIT 100`, {
  sources: ['http://fragments.dbpedia.org/2015/en'],
});

// Consume results as a stream (best performance)
result.bindingsStream.on('data', (binding) => {
    console.log(binding.get('?s').value);
    console.log(binding.get('?s').termType);

    console.log(binding.get('?p').value);

    console.log(binding.get('?o').value);
});

// Consume results as an array (easier)
const bindings = await result.bindings();
console.log(bindings[0].get('?s').value);
console.log(bindings[0].get('?s').termType);

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

const result = await myEngine.query(`...`, {
  sources: [
    'http://fragments.dbpedia.org/2015/en',
    { type: 'hypermedia', value: 'http://fragments.dbpedia.org/2016/en' },
    { type: 'file', value: 'https://www.rubensworks.net/' },
    new N3Store(),
    { type: 'sparql', value: 'https://dbpedia.org/sparql' },
  ],
});

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 ?o
  } LIMIT 100`, {
  sources: ['http://fragments.dbpedia.org/2015/en'],
});

// Consume results as a stream (best performance)
result.quadStream.on('data', (quad) => {
    console.log(quad.subject.value);
    console.log(quad.predicate.value);
    console.log(quad.object.value);
    console.log(quad.graph.value);
});

// Consume results as an array (easier)
const quads = await result.quads();
console.log(quads[0].subject.value);
console.log(quads[0].predicate.value);
console.log(quads[0].object.value);
console.log(quads[0].graph.value);

Finally, ASK queries return async booleans.

const result = await myEngine.query(`
  ASK {
    ?s ?p <http://dbpedia.org/resource/Belgium>
  }`, {
  sources: ['http://fragments.dbpedia.org/2015/en'],
})
const hasMatches = await result.booleanResult;

Learn more

This README just shows the tip of the iceberg! Learn more about Comunica's functionalities in the following guides:

@comunica/actor-init-sparql

Stats

Readme