org.eclipse.rdf4j.federated.evaluation

Class FederationEvalStrategy

java.lang.Object

org.eclipse.rdf4j.query.algebra.evaluation.impl.StrictEvaluationStrategy

org.eclipse.rdf4j.federated.evaluation.FederationEvalStrategy

All Implemented Interfaces:

EvaluationStrategy, FederatedServiceResolver, FederatedServiceResolverClient, UUIDable

Direct Known Subclasses:

SailFederationEvalStrategy, SparqlFederationEvalStrategy

public abstract class FederationEvalStrategy
extends StrictEvaluationStrategy

Base class for the Evaluation strategies.

Author:

Andreas Schwarte

See Also:

SailFederationEvalStrategy, SparqlFederationEvalStrategy

Field Summary

Fields

Modifier and Type	Field and Description
protected SourceSelectionCache	cache
protected Executor	executor
protected FederationContext	federationContext

Fields inherited from class org.eclipse.rdf4j.query.algebra.evaluation.impl.StrictEvaluationStrategy

dataset, serviceResolver, tripleSource

Constructor Summary

Constructors

Constructor and Description
FederationEvalStrategy(FederationContext federationContext)

Method Summary

Modifier and Type	Method and Description
protected SourceSelectionCache	createSourceSelectionCache() Create the SourceSelectionCache
Value	evaluate(ConjunctiveFilterExpr node, BindingSet bindings)
Value	evaluate(FilterExpr node, BindingSet bindings)
CloseableIteration<BindingSet,QueryEvaluationException>	evaluate(TupleExpr expr, BindingSet bindings) Evaluates the tuple expression against the supplied triple source with the specified set of variable bindings as input.
Value	evaluate(ValueExpr expr, BindingSet bindings) Gets the value of this expression.
protected CloseableIteration<BindingSet,QueryEvaluationException>	evaluateAtStatementSources(Object preparedQuery, List<StatementSource> statementSources, QueryInfo queryInfo)
protected CloseableIteration<BindingSet,QueryEvaluationException>	evaluateAtStatementSources(String preparedQuery, List<StatementSource> statementSources, QueryInfo queryInfo)
protected CloseableIteration<BindingSet,QueryEvaluationException>	evaluateAtStatementSources(TupleExpr preparedQuery, List<StatementSource> statementSources, QueryInfo queryInfo)
abstract CloseableIteration<BindingSet,QueryEvaluationException>	evaluateBoundJoinStatementPattern(StatementTupleExpr stmt, List<BindingSet> bindings) Evaluate a bound join at the relevant endpoint, i.e.
abstract CloseableIteration<BindingSet,QueryEvaluationException>	evaluateExclusiveGroup(ExclusiveGroup group, BindingSet bindings)
protected CloseableIteration<BindingSet,QueryEvaluationException>	evaluateExclusiveTupleExpr(ExclusiveTupleExpr expr, BindingSet bindings) Evaluate an ExclusiveTupleExpr.
abstract CloseableIteration<BindingSet,QueryEvaluationException>	evaluateGroupedCheck(CheckStatementPattern stmt, List<BindingSet> bindings) Perform a grouped check at the relevant endpoints, i.e.
protected CloseableIteration<BindingSet,QueryEvaluationException>	evaluateLeftJoin(FedXLeftJoin leftJoin, BindingSet bindings) Evaluate a FedXLeftJoin (i.e.
CloseableIteration<BindingSet,QueryEvaluationException>	evaluateNaryUnion(NUnion union, BindingSet bindings)
CloseableIteration<BindingSet,QueryEvaluationException>	evaluateNJoin(NJoin join, BindingSet bindings)
CloseableIteration<BindingSet,QueryEvaluationException>	evaluateService(FedXService service, BindingSet bindings)
CloseableIteration<BindingSet,QueryEvaluationException>	evaluateService(FedXService service, List<BindingSet> bindings) Evaluate a SERVICE using vectored evaluation, taking the provided bindings as input.
CloseableIteration<BindingSet,QueryEvaluationException>	evaluateSingleSourceQuery(SingleSourceQuery query, BindingSet bindings)
protected abstract CloseableIteration<BindingSet,QueryEvaluationException>	executeJoin(ControlledWorkerScheduler<BindingSet> joinScheduler, CloseableIteration<BindingSet,QueryEvaluationException> leftIter, TupleExpr rightArg, Set<String> joinVariables, BindingSet bindings, QueryInfo queryInfo) Execute the join in a separate thread using some join executor.
CloseableIteration<Statement,QueryEvaluationException>	getStatements(QueryInfo queryInfo, Resource subj, IRI pred, Value obj, Resource... contexts) Retrieve the statements matching the provided subject, predicate and object value from the federation members.
TupleExpr	optimize(TupleExpr expr, EvaluationStatistics evaluationStatistics, BindingSet bindings) Execute the QueryOptimizerPipeline on the given TupleExpr to optimize its execution plan.
protected void	optimizeExclusiveExpressions(TupleExpr query, QueryInfo queryInfo, GenericInfoOptimizer info) Optimize ExclusiveTupleExpr, e.g.
protected void	optimizeJoinOrder(TupleExpr query, QueryInfo queryInfo, GenericInfoOptimizer info)
protected Set<Endpoint>	performSourceSelection(List<Endpoint> members, SourceSelectionCache cache, QueryInfo queryInfo, GenericInfoOptimizer info) Perform source selection for all statements of the query.
protected boolean	propagateServices(List<Service> serviceNodes) Whether to propagate a SingleSourceQuery containing SERVICE clauses.

Methods inherited from class org.eclipse.rdf4j.query.algebra.evaluation.impl.StrictEvaluationStrategy

evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, evaluate, getLimit, getService, getUUID, getVarValue, getZeroLengthPathIterator, isReducedOrDistinct, isTrue, isUnbound, setFederatedServiceResolver, setOptimizerPipeline, setTrackResultSize, setTrackTime

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

executor

protected Executor executor

cache

protected SourceSelectionCache cache

federationContext

protected FederationContext federationContext

Constructor Detail

FederationEvalStrategy

public FederationEvalStrategy(FederationContext federationContext)

Method Detail

createSourceSelectionCache

protected SourceSelectionCache createSourceSelectionCache()

Create the SourceSelectionCache

Returns:

the SourceSelectionCache

See Also:

FedXConfig.getSourceSelectionCacheSpec()

optimize

public TupleExpr optimize(TupleExpr expr,
                          EvaluationStatistics evaluationStatistics,
                          BindingSet bindings)

Description copied from class: StrictEvaluationStrategy

Execute the QueryOptimizerPipeline on the given TupleExpr to optimize its execution plan.

Specified by:

optimize in interface EvaluationStrategy

Overrides:

optimize in class StrictEvaluationStrategy

Parameters:

expr - the TupleExpr to optimize.

evaluationStatistics - this param is ignored!

bindings - a-priori bindings supplied for the query, which can potentially be inlined.

Returns:

the optimized TupleExpr.

See Also:

StrictEvaluationStrategy.setOptimizerPipeline(QueryOptimizerPipeline)

performSourceSelection

protected Set<Endpoint> performSourceSelection(List<Endpoint> members,
                                               SourceSelectionCache cache,
                                               QueryInfo queryInfo,
                                               GenericInfoOptimizer info)

Perform source selection for all statements of the query. As a result of this method all statement nodes are annotated with their relevant sources.

Parameters:

members -

cache -

queryInfo -

info -

Returns:

the set of relevant endpoints for the entire query

optimizeJoinOrder

protected void optimizeJoinOrder(TupleExpr query,
                                 QueryInfo queryInfo,
                                 GenericInfoOptimizer info)

propagateServices

protected boolean propagateServices(List<Service> serviceNodes)

Whether to propagate a SingleSourceQuery containing SERVICE clauses. By default, the query is always evaluated within the FedX engine if it contains a SERVICE clause.

Customized implementation may propagate a SingleSourceQuery including the SERVICE clause (e.g. for Wikidata the Label service can only be accessed in the wikidata endpoint.

Parameters:

serviceNodes -

Returns:

if true, a SingleSourceQuery containing SERVICE clauses is propagated as-is

optimizeExclusiveExpressions

protected void optimizeExclusiveExpressions(TupleExpr query,
                                            QueryInfo queryInfo,
                                            GenericInfoOptimizer info)

Optimize ExclusiveTupleExpr, e.g. restructure the exclusive parts of the query AST.

Parameters:

query -

queryInfo -

info -

evaluate

public CloseableIteration<BindingSet,QueryEvaluationException> evaluate(TupleExpr expr,
                                                                        BindingSet bindings)
                                                                 throws QueryEvaluationException

Description copied from interface: EvaluationStrategy

Evaluates the tuple expression against the supplied triple source with the specified set of variable bindings as input.

Specified by:

evaluate in interface EvaluationStrategy

Overrides:

evaluate in class StrictEvaluationStrategy

Parameters:

expr - The Tuple Expression to evaluate

bindings - The variables bindings to use for evaluating the expression, if applicable.

Returns:

A closeable iterator over the variable binding sets that match the tuple expression.

Throws:

QueryEvaluationException

getStatements

public CloseableIteration<Statement,QueryEvaluationException> getStatements(QueryInfo queryInfo,
                                                                            Resource subj,
                                                                            IRI pred,
                                                                            Value obj,
                                                                            Resource... contexts)
                                                                     throws RepositoryException,
                                                                            MalformedQueryException,
                                                                            QueryEvaluationException

Retrieve the statements matching the provided subject, predicate and object value from the federation members.

For a bound statement, i.e. a statement with no free variables, the statement itself is returned if some member has this statement, an empty iteration otherwise.

If the statement has free variables, i.e. one of the provided arguments in null, the union of results from relevant statement sources is constructed.

Parameters:

subj -

pred -

obj -

contexts -

Returns:

the statement iteration

Throws:

RepositoryException

MalformedQueryException

QueryEvaluationException

evaluateService

public CloseableIteration<BindingSet,QueryEvaluationException> evaluateService(FedXService service,
                                                                               BindingSet bindings)
                                                                        throws QueryEvaluationException

Throws:

QueryEvaluationException

evaluateSingleSourceQuery

public CloseableIteration<BindingSet,QueryEvaluationException> evaluateSingleSourceQuery(SingleSourceQuery query,
                                                                                         BindingSet bindings)
                                                                                  throws QueryEvaluationException

Throws:

QueryEvaluationException

evaluateNJoin

public CloseableIteration<BindingSet,QueryEvaluationException> evaluateNJoin(NJoin join,
                                                                             BindingSet bindings)
                                                                      throws QueryEvaluationException

Throws:

QueryEvaluationException

evaluateLeftJoin

protected CloseableIteration<BindingSet,QueryEvaluationException> evaluateLeftJoin(FedXLeftJoin leftJoin,
                                                                                   BindingSet bindings)
                                                                            throws QueryEvaluationException

Evaluate a FedXLeftJoin (i.e. an OPTIONAL clause)

Parameters:

leftJoin -

bindings -

Returns:

the resulting iteration

Throws:

QueryEvaluationException

See Also:

StrictEvaluationStrategy.evaluate(org.eclipse.rdf4j.query.algebra.LeftJoin, BindingSet)

evaluateNaryUnion

public CloseableIteration<BindingSet,QueryEvaluationException> evaluateNaryUnion(NUnion union,
                                                                                 BindingSet bindings)
                                                                          throws QueryEvaluationException

Throws:

QueryEvaluationException

executeJoin

protected abstract CloseableIteration<BindingSet,QueryEvaluationException> executeJoin(ControlledWorkerScheduler<BindingSet> joinScheduler,
                                                                                       CloseableIteration<BindingSet,QueryEvaluationException> leftIter,
                                                                                       TupleExpr rightArg,
                                                                                       Set<String> joinVariables,
                                                                                       BindingSet bindings,
                                                                                       QueryInfo queryInfo)
                                                                                throws QueryEvaluationException

Execute the join in a separate thread using some join executor. Join executors are for instance: - SynchronousJoin - SynchronousBoundJoin - ControlledWorkerJoin - ControlledWorkerBoundJoin For endpoint federation use controlled worker bound join, for local federation use controlled worker join. The other operators are there for completeness. Use executor to execute the join (it is a runnable).

Parameters:

joinScheduler -

leftIter -

rightArg -

joinVariables -

bindings -

Returns:

the result

Throws:

QueryEvaluationException

evaluateExclusiveGroup

public abstract CloseableIteration<BindingSet,QueryEvaluationException> evaluateExclusiveGroup(ExclusiveGroup group,
                                                                                               BindingSet bindings)
                                                                                        throws RepositoryException,
                                                                                               MalformedQueryException,
                                                                                               QueryEvaluationException

Throws:

RepositoryException

MalformedQueryException

QueryEvaluationException

evaluateExclusiveTupleExpr

protected CloseableIteration<BindingSet,QueryEvaluationException> evaluateExclusiveTupleExpr(ExclusiveTupleExpr expr,
                                                                                             BindingSet bindings)
                                                                                      throws RepositoryException,
                                                                                             MalformedQueryException,
                                                                                             QueryEvaluationException

Evaluate an ExclusiveTupleExpr. The default implementation converts the given expression to a SELECT query string and evaluates it at the source.

Parameters:

expr -

bindings -

Returns:

the result

Throws:

RepositoryException

MalformedQueryException

QueryEvaluationException

evaluateBoundJoinStatementPattern

public abstract CloseableIteration<BindingSet,QueryEvaluationException> evaluateBoundJoinStatementPattern(StatementTupleExpr stmt,
                                                                                                          List<BindingSet> bindings)
                                                                                                   throws QueryEvaluationException

Evaluate a bound join at the relevant endpoint, i.e. i.e. for a group of bindings retrieve results for the bound statement from the relevant endpoints

Parameters:

stmt -

bindings -

Returns:

the result iteration

Throws:

QueryEvaluationException

evaluateGroupedCheck

public abstract CloseableIteration<BindingSet,QueryEvaluationException> evaluateGroupedCheck(CheckStatementPattern stmt,
                                                                                             List<BindingSet> bindings)
                                                                                      throws QueryEvaluationException

Perform a grouped check at the relevant endpoints, i.e. for a group of bindings keep only those for which at least one endpoint provides a result to the bound statement.

Parameters:

stmt -

bindings -

Returns:

the result iteration

Throws:

QueryEvaluationException

evaluateService

public CloseableIteration<BindingSet,QueryEvaluationException> evaluateService(FedXService service,
                                                                               List<BindingSet> bindings)
                                                                        throws QueryEvaluationException

Evaluate a SERVICE using vectored evaluation, taking the provided bindings as input. See ControlledWorkerBoundJoin and FedXConfig.getEnableServiceAsBoundJoin()

Parameters:

service -

bindings -

Returns:

the result iteration

Throws:

QueryEvaluationException

evaluate

public Value evaluate(ValueExpr expr,
                      BindingSet bindings)
               throws ValueExprEvaluationException,
                      QueryEvaluationException

Description copied from interface: EvaluationStrategy

Gets the value of this expression.

Specified by:

evaluate in interface EvaluationStrategy

Overrides:

evaluate in class StrictEvaluationStrategy

bindings - The variables bindings to use for evaluating the expression, if applicable.

Returns:

The Value that this expression evaluates to, or null if the expression could not be evaluated.

Throws:

ValueExprEvaluationException

QueryEvaluationException

evaluate

public Value evaluate(FilterExpr node,
                      BindingSet bindings)
               throws ValueExprEvaluationException,
                      QueryEvaluationException

Throws:

ValueExprEvaluationException

QueryEvaluationException

evaluate

public Value evaluate(ConjunctiveFilterExpr node,
                      BindingSet bindings)
               throws ValueExprEvaluationException,
                      QueryEvaluationException

Throws:

ValueExprEvaluationException

QueryEvaluationException

evaluateAtStatementSources

protected CloseableIteration<BindingSet,QueryEvaluationException> evaluateAtStatementSources(Object preparedQuery,
                                                                                             List<StatementSource> statementSources,
                                                                                             QueryInfo queryInfo)
                                                                                      throws QueryEvaluationException

Throws:

QueryEvaluationException

evaluateAtStatementSources

protected CloseableIteration<BindingSet,QueryEvaluationException> evaluateAtStatementSources(String preparedQuery,
                                                                                             List<StatementSource> statementSources,
                                                                                             QueryInfo queryInfo)
                                                                                      throws QueryEvaluationException

Throws:

QueryEvaluationException

evaluateAtStatementSources

protected CloseableIteration<BindingSet,QueryEvaluationException> evaluateAtStatementSources(TupleExpr preparedQuery,
                                                                                             List<StatementSource> statementSources,
                                                                                             QueryInfo queryInfo)
                                                                                      throws QueryEvaluationException

Throws:

QueryEvaluationException