@comunica/query-sparql-link-traversal

Comunica SPARQL Link Traversal

Comunica SPARQL Link Traversal is a SPARQL query engine for JavaScript that follows links to detect new sources.

Warning: due to the uncontrolled nature of the Web, it is recommended to always enable lenient mode when doing link traversal.

This module is part of the Comunica framework.

Install

$ yarn add @comunica/query-sparql-link-traversal

or

$ npm install -g @comunica/query-sparql-link-traversal

Usage

Find the common friends of 2 people:

$ comunica-sparql-link-traversal \
  "SELECT DISTINCT * WHERE {
    <https://www.rubensworks.net/#me> foaf:knows ?person.
    <https://ruben.verborgh.org/profile/#me> foaf:knows ?person.
    ?person foaf:name ?name.
  }" --lenient

If no sources are provided, the URLs inside the query will be considered starting sources. Since passing sources is optional, the following is equivalent:

$ comunica-sparql-link-traversal https://www.rubensworks.net/ https://ruben.verborgh.org/profile/ \
  "SELECT DISTINCT * WHERE {
    <https://www.rubensworks.net/#me> foaf:knows ?person.
    <https://ruben.verborgh.org/profile/#me> foaf:knows ?person.
    ?person foaf:name ?name.
  }" --lenient

Show the help with all options:

$ comunica-sparql-link-traversal --help

Just like Comunica SPARQL, a dynamic variant (comunica-dynamic-sparql-link-traversal) also exists.

Read more about querying from the command line.

Usage within application

This engine can be used in JavaScript/TypeScript applications as follows:

const QueryEngine = require('@comunica/query-sparql-link-traversal').QueryEngine;
const myEngine = new QueryEngine();

const bindingsStream = await myEngine.queryBindings(`
  SELECT DISTINCT * WHERE {
    <https://www.rubensworks.net/#me> foaf:knows ?person.
    <https://ruben.verborgh.org/profile/#me> foaf:knows ?person.
    ?person foaf:name ?name.
  }`, {
    // Sources field is optional. Will be derived from query if not provided.
    sources: ['https://www.rubensworks.net/'],
    lenient: true,
});

// 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 an array (easier)
const bindings = await bindingsStream.toArray();
console.log(bindings[0].get('s').value);
console.log(bindings[0].get('s').termType);

Read more about querying an application.

Usage as a SPARQL endpoint

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

$ comunica-sparql-link-traversal-http --lenient

Start a webservice exposing traversal from https://www.rubensworks.net/ via the SPARQL protocol, i.e., a SPARQL endpoint.

$ comunica-sparql-link-traversal-http https://www.rubensworks.net/ --lenient

Show the help with all options:

$ comunica-sparql-link-traversal-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.