Miss any of our Open RFC calls?Watch the recordings here! »

@comunica/actor-init-sparql

1.18.0 • Public • Published

Comunica SPARQL

npm version Docker Pulls

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:

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.

Read more about querying from the command line.

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.

Read more about setting up a SPARQL endpoint.

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;

Read more about querying an application.

Learn more

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

Install

npm i @comunica/actor-init-sparql

DownloadsWeekly Downloads

2,686

Version

1.18.0

License

MIT

Unpacked Size

215 kB

Total Files

47

Last publish

Collaborators

  • avatar
  • avatar
  • avatar
  • avatar