StringSparqlQueryable interface

    interface StringSparqlQueryable {
      optional Promise<Stream<Bindings>> queryBindings(String query, QueryStringContext? context);
      optional Promise<Stream<Quad>> queryQuads(String query, QueryStringContext? context);
      optional Promise<boolean> queryBoolean(String query, QueryStringContext? context);
      optional Promise<void> queryVoid(String query, QueryStringContext? context);
    };
    

A StringSparqlQueryable can be implemented by objects that want to expose a SPARQL-constrained query execution interface that accepts queries as a string.

queryBindings() is an optional method that asynchronously returns a Stream of Bindings objects. query is a query string that SHOULD be a SPARQL SELECT query. context is an optional context in which query execution options can be passed.

queryQuads() is an optional method that asynchronously returns a Stream of Quad objects. query is a query string that SHOULD be a SPARQL CONSTRUCT or DESCRIBE query. context is an optional context in which query execution options can be passed.

queryBoolean() is an optional method that asynchronously returns a boolean. query is a query string that SHOULD be a SPARQL ASK query. context is an optional context in which query execution options can be passed.

queryVoid() is an optional method that asynchronously returns a void. query is a query string that SHOULD be a SPARQL update query. context is an optional context in which query execution options can be passed.

AlgebraSparqlQueryable interface

    interface AlgebraSparqlQueryable {
      optional Promise<Stream<Bindings>> queryBindings(Algebra query, QueryStringContext? context);
      optional Promise<Stream<Quad>> queryQuads(Algebra query, QueryStringContext? context);
      optional Promise<boolean> queryBoolean(Algebra query, QueryStringContext? context);
      optional Promise<void> queryVoid(Algebra query, QueryStringContext? context);
    };
    

An AlgebraSparqlQueryable can be implemented by objects that want to expose a query execution interface that accepts queries as an Algebra object.

queryBindings() is an optional method that asynchronously returns a Stream of Bindings objects. query is a query Algebra object that SHOULD be a SPARQL SELECT query. context is an optional context in which query execution options can be passed.

queryQuads() is an optional method that asynchronously returns a Stream of Quad objects. query is a query Algebra object that SHOULD be a SPARQL CONSTRUCT or DESCRIBE query. context is an optional context in which query execution options can be passed.

queryBoolean() is an optional method that asynchronously returns a boolean. query is a query Algebra object that SHOULD be a SPARQL ASK query. context is an optional context in which query execution options can be passed.

queryVoid() is an optional method that asynchronously returns a void. query is a query Algebra object that SHOULD be a SPARQL update query. context is an optional context in which query execution options can be passed.

StringQueryable interface

    interface StringQueryable {
      Promise<Query> query(String query, QueryStringContext? context);
    };
    

A StringQueryable can be implemented by objects that want to expose a query execution interface that accepts queries as a string.

query() asynchronously returns a new Query object that can be executed later. query is a query string. context is an optional context in which query execution options can be passed.

AlgebraQueryable interface

    interface AlgebraQueryable {
      Promise<Query> query(Algebra query, QueryAlgebraContext? context);
    };
    

An AlgebraQueryable can be implemented by objects that want to expose a query execution interface that accepts queries as an Algebra object.

query() asynchronously returns a new Query object that can be executed later. query is a query Algebra object. context is an optional context in which query execution options can be passed.

Query interface

    interface Query {
      readonly attribute string resultType;
      Promise<any> execute(any options);
    };
    

Query is an abstract interface that represents a query that can be executed.

resultType represents the type of query results that will be obtained for a query's execution. Possible values include "bindings", "quads", "boolean", and "void".

execute() asynchronously returns the query result, where the signature depends on the resultType.

QueryBindings interface

    interface QueryBindings {
      readonly attribute string resultType;
      Promise<Stream<Bindings>> execute(QueryExecuteOptions<Variable>? options);
      Promise<QueryMetadata<Bindings>> metadata(QueryMetadataOptions? options);
    };
    

QueryBindings represents a query that returns a stream of Bindings, such as a SPARQL SELECT query.

resultType contains the constant "bindings".

execute() asynchronously returns a stream of Bindings. options is an optional argument in which execution options can be passed.

metadata() asynchronously returns a QueryMetadata object. options is an optional argument in which desired metadata options can be passed.

QueryQuads interface

    interface QueryQuads {
      readonly attribute string resultType;
      Promise<Stream<Quad>> execute(QueryExecuteOptions<("subject" or "predicate" or "object" or "graph")>? options);
      Promise<QueryMetadata<Quad>> metadata(QueryMetadataOptions? options);
    };
    

QueryQuads represents a query that returns a stream of Quads, such as a SPARQL CONSTRUCT or DESCRIBE query.

resultType contains the constant "quads".

execute() asynchronously returns a stream of Quads. options is an optional argument in which execution options can be passed.

metadata() asynchronously returns a QueryMetadata object. options is an optional argument in which desired metadata options can be passed.

QueryBoolean interface

    interface QueryBoolean {
      readonly attribute string resultType;
      Promise<boolean> execute();
    };
    

QueryBoolean represents a query that returns a boolean, such as a SPARQL ASK query.

resultType contains the constant "boolean".

execute() asynchronously returns a boolean.

QueryVoid interface

    interface QueryVoid {
      readonly attribute string resultType;
      Promise<void> execute();
    };
    

QueryVoid represents a query that returns nothing, such as a SPARQL update query.

resultType contains the constant "void".

execute() asynchronously returns nothing.

QueryExecuteOptions interface

    interface QueryExecuteOptions<OrderType> {
      readonly attribute Array<QueryOperationOrderTerm<OrderType>> order;
    };
    

QueryExecuteOptions represents the options for executing a query.

order contains the desired order of query results.

QueryMetadataOptions interface

    interface QueryMetadataOptions {
      attribute ("estimate" or "exact")? cardinality;
      attribute boolean order;
      attribute boolean availableOrders;
    };
    

QueryMetadataOptions represents the options for requesting the metadata of a query.

cardinality indicates if an exact or estimated value for the cardinality metadata field should be returned.

order indicates if the order metadata field should be returned.

availableOrders indicates if the availableOrders metadata field should be returned.

QueryMetadata interface

    interface QueryMetadata<OrderType> {
      readonly attribute QueryResultCardinality? cardinality;
      readonly attribute Array<QueryOperationOrderTerm<OrderType>>? order;
      readonly attribute Array<QueryResultOrderCost<OrderType>>? availableOrders;
    };
    

QueryMetadata is an interface that contains side information about the query execution process.

cardinality represents the number of results of a query.

order represents the order of results in the query result.

availableOrders is an array of alternative orders that may be requested when executing a query.

QueryResultCardinality interface

    interface QueryResultCardinality {
      attribute ("estimate" or "exact") type;
      attribute unsigned long value;
    };
    

QueryResultCardinality represents the number of results of a query, which can either be an estimated value or exact.

type contains the value "estimate" or "exact", which respectively refer to an exact or estimate value.

value contains the cardinality value.

QueryOperationOrderTerm interface

    interface QueryOperationOrderTerm<OrderType> {
      attribute OrderType term;
      attribute ("asc" or "desc") direction;
    };
    

QueryOperationOrderTerm represents the ordering of a term of a given generic type.

term contains the term over which the order is applied.

direction contains the value "asc" or "desc", which respectively refer to an ascending or descending order.

QueryResultOrderCost interface

    interface QueryResultOrderCost<OrderType> {
      attribute QueryOperationCost cost;
      attribute Array<QueryOperationOrderTerm<OrderType>> terms;
    };
    

QueryResultOrderCost represents the cost of a specific ordering of query results.

cost represents the cost of executing this ordering.

terms represents the order of terms in an ordering.

QueryOperationCost interface

    interface QueryOperationCost {
      attribute unsigned long iterations;
      attribute unsigned long persistedItems;
      attribute unsigned long blockingItems;
      attribute unsigned long requestTime;
    };
    

QueryOperationCost represents the cost of a certain query operation.

iterations is estimation of how many iterations over items are executed. This can be used to determine the CPU cost.

persistedItems is estimation of how many items are stored in memory. This is used to determine the memory cost.

blockingItems is estimation of how many items block the stream. This is used to determine the time the stream is not progressing anymore.

requestTime is estimation of the time to request items from sources. This is used to determine the I/O cost.

QueryContext interface

    interface QueryContext {
      attribute Date? queryTimestamp;
    };
    

QueryContext is a base context interface.

queryTimestamp The date that should be used by SPARQL operations such as NOW().

QueryStringContext interface

    interface QueryStringContext : QueryContext {
      attribute QueryFormat? queryFormat;
      attribute string? baseIRI;
    };
    

A QueryStringContext is a context that can be passed together with a query string.

queryFormat The format in which the query string is defined.

baseIRI The base IRI for parsing the query.

QueryAlgebraContext interface

    interface QueryAlgebraContext : QueryContext {};
    

A QueryAlgebraContext is a context that can be passed together with a query Algebra object.

QuerySourceContext interface

    interface QuerySourceContext : QueryContext {
      attribute Array? sources;
    };
    

A QuerySourceContext can be used by query engines that accept custom data sources during query execution.

sources An array of data sources the query engine must use.

QueryFormat interface

    interface QueryFormat {
      attribute string language;
      attribute string version;
      attribute Array<string>? extensions;
    };
    

A QueryFormat represents the format of a string query, and may influence parsing or execution behaviour.

language The query language, e.g. "sparql".

version The version of the query language, e.g. "1.1".

language An optional array of extensions on the query language. The representation of these extensions is undefined.

Goals

• Query engines should be able to interact with bindings created by different libraries.
• Bindings are immutable
• Interfaces do no specify how bindings are stored in memory

Bindings interface

    interface Bindings {
      iterable<(Variable, Term)>;

      readonly attribute string type;
      readonly attribute unsigned long size;

      boolean has((Variable or string) key);
      Term? get((Variable or string) key);
      Bindings set((Variable or string) key, Term value);
      Bindings delete((Variable or string) key);
      iterable<Variable> keys();
      iterable<Term> values();
      boolean equals(optional Bindings? other);
      void forEach(BindingsEntryCallback callback);
      Bindings filter(BindingsFilterCallback callback);
      Bindings map(BindingsMapCallback callback);
      Bindings merge(Bindings other);
      Bindings mergeWith(BindingsMergeCallback callback, Bindings other);
    };
    
    callback BindingsEntryCallback = undefined (Term value, Variable key);
    callback BindingsFilterCallback = boolean (Term value, Variable key);
    callback BindingsMapCallback = Term (Term value, Variable key);
    callback BindingsMergeCallback = Term (Term self, Term other, Variable key);
    

A Bindings is an object that represents the mapping of variables to RDF values using an immutable Map-like representation. This means that methods such as set and delete do not modify this instance, but they return a new Bindings instance that contains the modification.

Every Bindings object is an iterable over its entries, where each entry is a tuple of Variable key and Term value.

Attributes

type contains the constant "bindings".

size is a field that contains the number of entries in this Bindings object.

Methods

has checks if a binding exist for the given variable. key can be a Variable or string. If it is a string, no `?` prefix must be given.

get returns the Term value bound to the given variable, or undefined if no binding exists. key can be a Variable or string. If it is a string, no `?` prefix must be given.

set returns a new Bindings object by adding the given variable and value mapping. If the variable already exists in the binding, then the existing mapping is overwritten. key can be a Variable or string. If it is a string, no `?` prefix must be given. value is the Term value that must be bound.

delete returns a new Bindings object by removing the given variable. If the variable does not exist in the binding, a copy of the Bindings object is returned. key can be a Variable or string. If it is a string, no `?` prefix must be given.

keys returns an iterable of Variable instances for which mappings exist.

values returns an iterable of Term values for which mappings exist.

equals returns true when called with parameter other on an object Bindings if all of the conditions below hold:

• other is neither null nor undefined;
• The keys in the this and the other Bindings object are equal (following the semantics of Variable.equals);
• For each key, the values within each Bindings object are equal (following the semantics of Term.equals);

forEach invokes the callback for all entries in this Bindings object, with the entry value Term as first argument, and the entry key Variable as second argument.

filter returns a new Bindings object by filtering entries using callback, with the entry value Term as first argument, and the entry key Variable as second argument. Returning true indicates that this entry must be contained in the resulting Bindings object.

map returns a new Bindings object by mapping entries using callback, with the entry value Term as first argument, and the entry key Variable as second argument. The original Term value is replaced by the returned Term value in the resulting Bindings object.

merge merges this Bindings object with another Bindings object. If a merge conflict occurs (this and other have an equal variable with unequal value), then undefined is returned.

mergeWith merges this Bindings object with another Bindings object, where merge conflicts can be resolved using callback. callback is invoked with the value Term of the first Bindings object as first argument, the value Term of the second Bindings object as second argument, and the key Variable as third argument, where the returned Term is considered the merged value.

BindingsFactory interface

    interface BindingsFactory {
      Bindings bindings(Array<(Variable, Term)>? entries);
      Bindings fromBindings(Bindings bindings);
    };
    

bindings() returns a new Bindings using the given entries, where the entries are represented as an array of key-value pairs.

fromBindings() returns a copy of the given Bindings using this factory.

Goals

• Query engines MUST be able to push down filters into sources.
• Query engines MUST be able to detect what expressions are supported by sources.
• Query engines MUST be able to obtain the estimated cardinality of any supported expression.

FilterableSource interface

    interface FilterableSource {
      FilterResult matchExpression (
        optional Term? subject,
        optional Term? predicate,
        optional Term? obj,
        optional Term? graph,
        optional Expression? expression
      );
    };
    

A FilterableSource is an object that produces a FilterableSourceResult that can emit quads. The emitted quads can be directly contained in this FilterableSource object, or they can be generated on the fly.

FilterableSource is not necessarily an extension of the RDF/JS Source interface, but implementers MAY decide to implement both at the same time.

matchExpression() Returns a FilterableSourceResult that contains a quad stream that processes all quads matching the quad pattern and the expression.

When a Term parameter is defined, and is a NamedNode, Literal or BlankNode, it must match each produced quad, according to the Quad.equals semantics. When a Term parameter is a Variable, or it is undefined, it acts as a wildcard, and can match with any Term.

When matching with graph set to undefined or null it MUST match all the graphs (sometimes called the union graph). To match only the default graph set graph to a DefaultGraph

When an Expression parameter is defined, the complete quad stream is filtered according to this expression. When it is undefined, no filter is applied.

If parameters of type Variable with an equal variable name are in place, then the corresponding quad components in the resulting quad stream MUST be equal.

Expression's MAY contain Variable Term's. If their variable names are equal to Variable's in the given quad pattern, then the Expression MUST be instantiated for each variable's binding in the resulting quad stream when applying the Expression filter.

FilterResult interface

    interface FilterResult {
      Stream quads();
      Promise<QueryResultMetadata> metadata(optional QueryResultMetadataOptions? options);
      Promise<boolean> isSupported();
    };
    

A FilterResult is an object that represents the result of a filter expression of FilterableSource for a given quad pattern and expression. It MAY create results lazily after one of its methods is invoked.

quads() Returns a Stream containing all the quads that matched the given quad pattern and expression.

metadata() Asynchronously returns a QueryResultMetadata, that contains the metadata of the current result.

isSupported() Asynchronously returns a boolean indicating if the requested expression is supported by the FilterableSource. If it returns true, quads() and metadata() MAY produce a valid result. If it returns false, quads() MUST return a stream emitting an error, and metadata() MUST reject.

QueryResultMetadata interface

    interface QueryResultMetadata {
      attribute QueryResultMetadataCount? count;
    };
    

A QueryResultMetadata is an object that represents contains metadata bout a certain query result, such as invoking FilterableSource.matchExpression.

count is an optional field that contains metadata about the number of quads in the result stream.

QueryResultMetadataCount interface

    interface QueryResultMetadataCount {
      attribute string type;
      attribute number value;
    };
    

QueryResultMetadataCount is part of the QueryResultMetadata interface to represent metadata about the number of quads in the result stream.

type indicates the type of counting that was done, and MUST either be "estimate" or "exact".

value indicates an estimate of the number of quads in the stream if type = "estimate", or the exact number of quads in the stream if type = "exact".

QueryResultMetadataOptions interface

    interface QueryResultMetadataOptions {
      attribute string? count;
    };
    

A QueryResultMetadataOptions is an object that gives suggestions on what type of metadata is desired, such as when invoking FilterResult.metadata.

count is an optional field that MAY either contain "estimate" or "exact". If defined, this type MUST correspond to the type in QueryResultMetadataCount.

Expression interface

    interface Expression {
      attribute string expressionType;
    };
    

QueryResultMetadataOptions is an abstract interface that represents a generic expression over a stream of quads.

expressionType contains a value that identifies the concrete interface of the expression, since the Expression itself is not directly instantiated. Possible values include "operator" and "term".

OperatorExpression interface

    interface OperatorExpression {
      attribute string expressionType;
      attribute string operator;
      attribute FrozenArray<Expression> args;
    };
    

An OperatorExpression is represents an expression that applies a given operator on given sub-expressions.

expressionType contains the constant "operator".

operator contains a value that identifies an operator. Possible values can be found in the list of operators.

args contains an array of Expression's on to which the given operator applies. The length of this array depends on the operator.

TermExpression interface

    interface TermExpression {
      attribute string expressionType;
      attribute Term term;
    };
    

A TermExpression is an expression that contains a Term.

expressionType contains the constant "term".

term contains a Term.

ExpressionFactory interface

    interface ExpressionFactory {
      OperatorExpression operatorExpression(string operator, sequence<Expression> args);
      TermExpression termExpression(Term term);
    };
    

ExpressionFactory enables expressions to be created in an idiomatic manner.

operatorExpression creates a new OperatorExpression instance for the given operator and array of arguments.

termExpression creates a new TermExpression instance for the given term.

Relational operators

Term functions

String functions

Numerical functions

Date and time functions

Hash functions

XPath constructor functions

Functional forms