Module @comunica/query-sparql - v4.0.2

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.

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.

Supported by

Comunica is a community-driven project, sustained by the Comunica Association. If you are using Comunica, becoming a sponsor or member is a way to make Comunica sustainable in the long-term.

Our top sponsors are shown below!

Installation

Comunica requires Node.JS 14.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/query-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 https://fragments.dbpedia.org/2015-10/en "CONSTRUCT WHERE { ?s ?p ?o } LIMIT 100"

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

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

Combine multiple sources:

$ comunica-sparql https://fragments.dbpedia.org/2015-10/en \
  file@https://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 engines/query-sparql folder):

node bin/query.js https://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 https://fragments.dbpedia.org/2015-10/en via the SPARQL protocol, i.e., a SPARQL endpoint.

$ comunica-sparql-http https://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 QueryEngine = require('@comunica/query-sparql').QueryEngine;

const myEngine = new QueryEngine();

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

const QueryEngineFactory = require('@comunica/query-sparql').QueryEngineFactory;

const myEngine = await new QueryEngineFactory().create({ configPath: 'path/to/config.json' });

Once you have created your query engine, you can use it to call one of the async query methods, such as queryBindings for SELECT queries, queryQuads for CONSTRUCT and DESCRIBE queries, queryBoolean for ASK queries, or queryVoid for update queries.

All query methods have the require a query string and a context object, with the return type depending on the query type.

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

const bindingsStream = await myEngine.queryBindings(`
  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)
bindingsStream.on('data', (binding) => {
  console.log(binding.toString()); // Quick way to print bindings for testing

  console.log(binding.has('s')); // Will be true

  // Obtaining values
  console.log(binding.get('s').value);
  console.log(binding.get('s').termType);
  console.log(binding.get('p').value);
  console.log(binding.get('o').value);
});
bindingsStream.on('end', () => {
  // The data-listener will not be called anymore once we get here.
});
bindingsStream.on('error', (error) => {
  console.error(error);
});

// Consume results as async iterable (easier)
for await (const binding of bindingsStream) {
  console.log(binding.toString());
}

// Consume results as an array (easier)
const bindings = await bindingsStream.toArray();
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 bindingsStream = await myEngine.queryBindings(`...`, {
  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 quadStream = await myEngine.queryQuads(`
  CONSTRUCT WHERE {
    ?s ?p ?o
  } LIMIT 100`, {
  sources: ['http://fragments.dbpedia.org/2015/en'],
});

// Consume results as a stream (best performance)
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 asynciterable (easier)
for await (const quad of quadStream) {
  console.log(quad.subject.value);
}

// Consume results as an array (easier)
const quads = await quadStream.toArray();
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 hasMatches = await myEngine.queryAsk(`
  ASK {
    ?s ?p <http://dbpedia.org/resource/Belgium>
  }`, {
  sources: ['http://fragments.dbpedia.org/2015/en'],
})

Learn more

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

Classes

QueryEngine
QueryEngineFactory