Bindings

On this page

    SPARQL SELECT query results are represented as a stream of bindings (sometimes also referred to as BindingsStream), where each bindings object represents a mapping from zero or more variables to RDF terms.

    The SPARQL specification uses solution mapping as terminology to refer to bindings. This means that a bindings object is equivalent to a solution mapping, and a solution sequence is equivalent to a bindings stream.

    Bindings object are represented using the RDF/JS Bindings interface, and can be created using any RDF/JS BindingsFactory. Comunica provides the @comunica/utils-bindings-factory package that implements these interfaces.

    Below, several examples are shown on how these bindings objects can be used. Please refer to the README of @comunica/utils-bindings-factory for a complete overview of its operations.

    Reading values of bindings

    Bindings.has()

    The has() method is used to check if a value exists for the given variable. The variable can either be supplied as a string (without ? prefix), or as an RDF/JS variable.

    if (bindings.has('var1')) {
  console.log('Has var1!');
}
if (bindings.has(DF.variable('var2'))) {
  console.log('Has var2!');
}

    Bindings.get()

    The get() method is used to read the bound value of variable. The variable can either be supplied as a string (without ? prefix), or as an RDF/JS variable.

    import * as RDF from '@rdfjs/types';

const term1: RDF.Term | undefined = bindings.get('var1');
const term2: RDF.Term | undefined = bindings.get(DF.variable('var2'));

    Entry iteration

    Each bindings object is an Iterable over its key-value entries, where each entry is a tuple of type [RDF.Variable, RDF.Term].

    // Iterate over all entries
for (const [ key, value ] of bindings) {
  console.log(key);
  console.log(value);
}

// Save the entries in an array
const entries = [ ...bindings ];
    The iteration order is undefined, so you should not assume a specific order of keys. Instead, you can rely on the query result's metadata which defines variables in a fixed order.

    Bindings.toString

    The toString() method returns a compact string representation of the bindings object, which can be useful for debugging.

    console.log(bindings.toString());

/*
Can output in the form of:
{
  "a": "ex:a",
  "b": "ex:b",
  "c": "ex:c"
}
 */

    Creating bindings

    First, a bindings factory must be created:

    import * as RDF from '@rdfjs/types';
import { DataFactory } from 'rdf-data-factory';
import { BindingsFactory } from '@comunica/utils-bindings-factory';

const DF = new DataFactory();
const BF = new BindingsFactory(DF);

    Bindings can be created in different ways:

    const bindings1: RDF.Bindings = BF.bindings([
  [ DF.variable('var1'), DF.literal('abc') ],
  [ DF.variable('var2'), DF.literal('def') ],
]);

const bindings2: RDF.Bindings = BF.fromRecord({
  var1: DF.literal('abc'),
  var2: DF.literal('def'),
});