Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
bin Update to ts-jest 23.10.x, Closes #276 Oct 1, 2018
components Add Memento datetime context shortcut Sep 18, 2018
config
lib Remove disabling of stacktraces Sep 5, 2018
spec Fix spec engine using an old version of the spec runner Sep 28, 2018
test Update to ts-jest 23.10.x, Closes #276 Oct 1, 2018
.dockerignore Add .dockerignore file for optimizing Docker building Jun 29, 2018
.gitignore Remove unneeded files in actor-init-sparql package Mar 9, 2018
.npmignore Add SPARQL init actor Dec 4, 2017
Dockerfile Add Dockerfile for actor-init-sparql Jun 21, 2018
README.md Document logger usage in README Aug 20, 2018
index-browser.ts Expose bindingsStreamToGraphQl to browser API as well Jul 27, 2018
index.ts Make browser version of the SPARQL init actor consistent with Node Jun 29, 2018
package.json Bump to release version v1.4.4 Nov 13, 2018
tsconfig.json Add web-safe variant of ActorInitSparql Jan 23, 2018
tslint.json Add SPARQL init actor Dec 4, 2017
webpack.config.js Upgrade asynciterator to v2.0.1 Nov 9, 2018

README.md

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.

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 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/2015-10/en "CONSTRUCT WHERE { ?s ?p ?o } LIMIT 100"

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

Usage from HTTP

Start a webservice exposing http://fragments.dbpedia.org/2015-10/en via the SPARQL protocol.

$ comunica-sparql-http "{ \"sources\": [{ \"type\": \"entrypoint\", \"value\" : \"http://fragments.dbpedia.org/2015/en\" }]}""

Show the help with all options:

$ comunica-sparql-http --help

The HTTP service 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

Static:

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

const myEngine = newEngine();
myEngine.query('SELECT * { ?s ?p <http://dbpedia.org/resource/Belgium>. ?s ?p ?o } LIMIT 100',
  { sources: [ { type: 'hypermedia', value: 'http://fragments.dbpedia.org/2015/en' } ] })
  .then(function (result) {
    result.bindingsStream.on('data', function (data) {
      console.log(data.toObject());
    });
  });

Dynamic:

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

newEngineDynamic().then(function (myEngine) {
  myEngine.query('SELECT * { ?s ?p <http://dbpedia.org/resource/Belgium>. ?s ?p ?o } LIMIT 100',
    { sources: [ { type: 'hypermedia', value: 'http://fragments.dbpedia.org/2015/en' } ] })
    .then(function (result) {
      result.bindingsStream.on('data', function (data) {
        console.log(data.toObject());
      });
    });
});

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 context = {
  sources: [ { type: 'hypermedia', value: 'http://fragments.dbpedia.org/2016-04/en' } ],
  queryFormat: 'graphql',
  "@context": {
    "label": { "@id": "http://www.w3.org/2000/01/rdf-schema#label", "@singular": true },
    "label_en": { "@id": "http://www.w3.org/2000/01/rdf-schema#label", "@language": "en" },
    "writer": { "@id": "http://dbpedia.org/ontology/writer", "@singular": true },
    "artist": { "@id": "http://dbpedia.org/ontology/musicalArtist", "@singular": true },
    "artist_label": { "@singular": true }
  }
};
myEngine.query('{ label writer(label_en: \"Michael Jackson\") artist { label } }',context)
  .then(function (result) { return bindingsStreamToGraphQl(result.bindingsStream, context); })
  .then(console.log);

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);

Usage within browser

This engine can run in the browser using Webpack. To created a web-packed version of the engine, run yarn run browser (when inside the packages/actor-init-sparql folder) to create comunica-browser.js.

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 <http://dbpedia.org/resource/Belgium>. ?s ?p ?o } LIMIT 100',
  { sources: [ { type: 'hypermedia', value: 'http://fragments.dbpedia.org/2015/en' } ] })
  .then(function (result) {
    result.bindingsStream.on('data', function (data) {
      console.log(data.toObject());
    });
  });

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