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'),
    });