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