Passing a context


On this page

    When passing a query to a Comunica query engine, you can pass additional information to the engine using a context object.

    1. How to use the context

    When querying in a JavaScript application, the context must be passed as second argument to the query() method of a Comunica engine.

    For example, a context that defines the sources to query over is passed as follows:

    const newEngine = require('@comunica/actor-init-sparql').newEngine;
    const myEngine = newEngine();
    
    const result = await myEngine.query(`SELECT * WHERE { ?s ?p ?o }`, {
      sources: ['http://fragments.dbpedia.org/2015/en'],
    });

    The sources field is the only entry that is required in the context. All other entries that are discussed hereafter are optional.

    During query execution, the context is converted into an immutable object to ensure that the original context entries remain unchanged during the whole query execution.

    2. Overview

    The following table gives an overview of all possible context entries that can be passed.

    KeyDescription
    sourcesAn array of data sources
    lenientIf HTTP and parsing failures are ignored
    initialBindingsVariables that have to be pre-bound to values in the query
    queryFormatName of the provided query's format
    baseIRIBase IRI for relative IRIs in SPARQL queries
    logA custom logger instance
    datetimeSpecify a custom date
    httpProxyHandlerA proxy for all HTTP requests
    httpIncludeCredentials(browser-only) If current credentials should be included for HTTP requests

    3. Defining sources

    Using the sources context entry, data sources can be defined that Comunica should query over. The value of this must be an array, where the array may contain both strings or objects:

    • Array elements that are strings are interpreted as URLs, such as 'https://www.rubensworks.net/' or 'http://fragments.dbpedia.org/2016-04/en'.
    • Object array elements can be different things:
      • A hash containing type and value, such as { type: 'sparql', value: 'https://dbpedia.org/sparql' }.
      • An RDF/JS source object, such as new N3Store().

    String-based sources will lead to Comunica trying to determine their source type automatically. Hash-based sources allows you to enforce a specific source type.

    Learn more about all available source type.
    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 example, all of the following source elements are valid:

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

    4. Lenient execution

    By default, Comunica will throw an error when it encounters an invalid RDF document or HTTP URL. It is possible to ignore these errors and make Comunica ignore such invalid documents and URLs by setting lenient to true:

    const result = await myEngine.query(`SELECT * WHERE { ?s ?p ?o }`, {
      sources: ['http://fragments.dbpedia.org/2015/en'],
      lenient: true,
    });

    5. Binding variables

    Using the initialBindings context entry, it is possible to bind certain variables in the given query to terms before the query execution starts. This may be valuable in case your SPARQL query is used as a template with some variables that need to be filled in.

    This can be done by passing a Bindings object as value to the initialBindings context entry:

    import { Bindings } from '@comunica/bus-query-operation';
    import { DataFactory } from 'rdf-data-factory';
    
    const factory = new DataFactory();
    
    const result = await myEngine.query(`SELECT * WHERE {
      {?s ?p ?template1 } UNION { ?s ?p ?template2 }
    }`, {
      sources: ['http://fragments.dbpedia.org/2015/en'],
      initialBindings: new Bindings({
        '?template1': factory.literal('Value1'),
        '?template2': factory.literal('Value2'),
      }),
    });

    The keys in the Bindings hash must be variable names starting with ?. The values must be valid RDF/JS terms, which can for example be constructed using rdf-data-factory.

    6. Setting the query format

    By default, queries in Comunica are interpreted as SPARQL queries. As such, the queryFormat entry defaults to sparql.

    Since Comunica is not tied to any specific query format, it is possible to change this to something else, such as graphql. More information on this can be found in the GraphQL-LD guide.

    7. Setting a Base IRI

    Terms in SPARQL queries can be relative to a certain Base IRI. Typically, you would use the BASE keyword in a SPARQL query to set this Base IRI. If you want to set this Base IRI without modifying the query, then you can define it in the context using baseIRI:

    const result = await myEngine.query(`SELECT * WHERE {
      ?s </relative> ?o
    }`, {
      sources: ['http://fragments.dbpedia.org/2015/en'],
      baseIRI: 'http://example.org/',
    });

    8. Enabling a logger

    A logger can be set using log. More information on this can be found in the logging guide.

    9. Setting a custom date

    Using datetime, a custom date can be set in Comunica. The range of this field must always be a JavaScript Date object:

    const result = await myEngine.query(`SELECT * WHERE { ?s ?p ?o }`, {
      sources: ['http://fragments.dbpedia.org/2015/en'],
      date: new Date(),
    });

    This date is primarily used for the SPARQL NOW() operator. It is also used when performing time travel querying using the Memento protocl.

    10. Enabling an HTTP proxy

    All HTTP requests can be run through a proxy using httpProxyHandler. More information on this can be found in the HTTP proxy guide.

    11. Include credentials in HTTP requests

    Only applicable when running in the browser

    If this option is enabled, then all cross-site requests will be made using credentials of the current page. This includes cookies, authorization headers or TLS client certificates.

    Enabling this option has no effect on same-site requests.

    const result = await myEngine.query(`SELECT * WHERE { ?s ?p ?o }`, {
      sources: ['http://fragments.dbpedia.org/2015/en'],
      httpIncludeCredentials: true,
    });

    12. Send requests via HTTP basic authentication

    Via HTTP Basic Authentication one can include username and password credentials in HTTP requests. More information on this can be found in the HTTP basic authentication guide.