Package org.eclipse.rdf4j.federated.evaluation

Class FederationEvalStrategy

java.lang.Object

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

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

org.eclipse.rdf4j.federated.evaluation.FederationEvalStrategy

All Implemented Interfaces:

EvaluationStrategy, FederatedServiceResolver, FederatedServiceResolverClient

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	Description
protected SourceSelectionCache	cache
protected Executor	executor
protected FederationContext	federationContext

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

dataset, serviceResolver, tripleSource

Constructor Summary

Constructors

Constructor	Description
FederationEvalStrategy(FederationContext federationContext)

Method Summary

Modifier and Type	Method	Description
Value	evaluate(ConjunctiveFilterExpr node, BindingSet bindings)
Value	evaluate(FilterExpr node, BindingSet bindings)
CloseableIteration<BindingSet>	evaluate(DescribeOperator operator, BindingSet bindings)
CloseableIteration<BindingSet>	evaluate(TupleExpr expr, BindingSet bindings)	Deprecated, for removal: This API element is subject to removal in a future version.
Value	evaluate(ValueExpr expr, BindingSet bindings)	Deprecated, for removal: This API element is subject to removal in a future version.
protected CloseableIteration<BindingSet>	evaluateArbitrayLengthPath(FedXArbitraryLengthPath alp, BindingSet bindings)
protected CloseableIteration<BindingSet>	evaluateAtStatementSources(Object preparedQuery, List<StatementSource> statementSources, QueryInfo queryInfo)
protected CloseableIteration<BindingSet>	evaluateAtStatementSources(String preparedQuery, List<StatementSource> statementSources, QueryInfo queryInfo)
protected CloseableIteration<BindingSet>	evaluateAtStatementSources(TupleExpr preparedQuery, List<StatementSource> statementSources, QueryInfo queryInfo)
abstract CloseableIteration<BindingSet>	evaluateBoundJoinStatementPattern(StatementTupleExpr stmt, List<BindingSet> bindings)	Evaluate a bound join at the relevant endpoint, i.e.
abstract CloseableIteration<BindingSet>	evaluateExclusiveGroup(ExclusiveGroup group, BindingSet bindings)
protected CloseableIteration<BindingSet>	evaluateExclusiveTupleExpr(ExclusiveTupleExpr expr, BindingSet bindings)	Evaluate an ExclusiveTupleExpr.
abstract CloseableIteration<BindingSet>	evaluateGroupedCheck(CheckStatementPattern stmt, List<BindingSet> bindings)	Perform a grouped check at the relevant endpoints, i.e.
protected CloseableIteration<BindingSet>	evaluateLeftJoin(FedXLeftJoin leftJoin, BindingSet bindings)	Evaluate a FedXLeftJoin (i.e.
CloseableIteration<BindingSet>	evaluateNaryUnion(NUnion union, BindingSet bindings)
CloseableIteration<BindingSet>	evaluateNJoin(NJoin join, BindingSet bindings)
CloseableIteration<BindingSet>	evaluateService(FedXService service, List<BindingSet> bindings)	Evaluate a SERVICE using vectored evaluation, taking the provided bindings as input.
CloseableIteration<BindingSet>	evaluateService(FedXService service, BindingSet bindings)
CloseableIteration<BindingSet>	evaluateSingleSourceQuery(SingleSourceQuery query, BindingSet bindings)
protected CloseableIteration<BindingSet>	evaluateZeroLengthPath(FedXZeroLengthPath zlp, BindingSet bindings)
protected abstract CloseableIteration<BindingSet>	executeJoin(ControlledWorkerScheduler<BindingSet> joinScheduler, CloseableIteration<BindingSet> leftIter, TupleExpr rightArg, Set<String> joinVariables, BindingSet bindings, QueryInfo queryInfo)	Execute the join in a separate thread using some join executor.
protected List<Endpoint>	getMembersFromContext(FederationEvaluationStatistics evaluationStatisticss)	Returns the federation members that are active in the current federation.
CloseableIteration<Statement>	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 Set<Endpoint>	performSourceSelection(FedXArbitraryLengthPath pathExpr, StatementPattern stmt, List<Endpoint> members, SourceSelectionCache cache, QueryInfo queryInfo)	Perform source selection on the statement pattern representing the path expression.
QueryEvaluationStep	precompile(TupleExpr expr, QueryEvaluationContext context)
QueryValueEvaluationStep	precompile(ValueExpr expr, QueryEvaluationContext context)
protected QueryValueEvaluationStep	prepare(ConjunctiveFilterExpr node, QueryEvaluationContext context)
protected QueryEvaluationStep	prepare(FedXArbitraryLengthPath alp, QueryEvaluationContext context)
protected QueryEvaluationStep	prepare(FedXZeroLengthPath zlp, QueryEvaluationContext context)
protected QueryValueEvaluationStep	prepare(FilterExpr node, QueryEvaluationContext context)
protected QueryEvaluationStep	prepare(DescribeOperator operator, QueryEvaluationContext context)
protected QueryEvaluationStep	prepareExclusiveTupleExpr(ExclusiveTupleExpr expr, QueryEvaluationContext context)
protected QueryEvaluationStep	prepareLeftJoin(FedXLeftJoin leftJoin, QueryEvaluationContext context)
QueryEvaluationStep	prepareNaryUnion(NUnion union, QueryEvaluationContext context)
protected QueryEvaluationStep	prepareNJoin(NJoin join, QueryEvaluationContext context)
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.DefaultEvaluationStrategy

evaluate, evaluate, evaluate, getCollectionFactory, getFederatedServiceResolver, getLimit, getQueryEvaluationMode, getService, getVarValue, isReducedOrDistinct, isTrue, isTrue, precompile, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, prepare, setCollectionFactory, setFederatedServiceResolver, setOptimizerPipeline, setQueryEvaluationMode, setTrackResultSize, setTrackTime, supplyBinaryValueEvaluation, supplyUnaryValueEvaluation

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.eclipse.rdf4j.query.algebra.evaluation.EvaluationStrategy

isTrackResultSize

Field Details

executor

protected Executor executor

cache

protected SourceSelectionCache cache

federationContext

protected FederationContext federationContext

Constructor Details

FederationEvalStrategy

public FederationEvalStrategy(FederationContext federationContext)

Method Details

optimize

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

Description copied from class: DefaultEvaluationStrategy

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

Specified by:

optimize in interface EvaluationStrategy

Overrides:

optimize in class DefaultEvaluationStrategy

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:

• DefaultEvaluationStrategy.setOptimizerPipeline(QueryOptimizerPipeline)

getMembersFromContext

protected List<Endpoint> getMembersFromContext(FederationEvaluationStatistics evaluationStatisticss)

Returns the federation members that are active in the current federation. By default it is all federation members. If the passed Dataset is a FedXDataset, the defined FedXDataset.getEndpoints() are used.

Parameters:

evaluationStatisticss - to keep the current query context

Returns:

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

performSourceSelection

protected Set<Endpoint> performSourceSelection(FedXArbitraryLengthPath pathExpr,
 StatementPattern stmt,
 List<Endpoint> members,
 SourceSelectionCache cache,
 QueryInfo queryInfo)

Perform source selection on the statement pattern representing the path expression. Source selection must be a subset of the provided members. The implementation expects to replace the statement, e.g. with StatementSourcePattern, ExclusiveStatement or EmptyStatementPattern

Parameters:

pathExpr -

stmt -

members -

cache -

queryInfo -

Returns:

identified relevant members

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

@Deprecated(forRemoval=true)
public CloseableIteration<BindingSet> evaluate(TupleExpr expr,
 BindingSet bindings)
                                        throws QueryEvaluationException

Deprecated, for removal: This API element is subject to removal in a future version.

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 DefaultEvaluationStrategy

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

precompile

public QueryEvaluationStep precompile(TupleExpr expr,
 QueryEvaluationContext context)
                               throws QueryEvaluationException

Specified by:

precompile in interface EvaluationStrategy

Overrides:

precompile in class DefaultEvaluationStrategy

Throws:

QueryEvaluationException

getStatements

public CloseableIteration<Statement> 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> evaluateService(FedXService service,
 BindingSet bindings)
                                               throws QueryEvaluationException

Throws:

QueryEvaluationException

evaluateSingleSourceQuery

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

Throws:

QueryEvaluationException

evaluateNJoin

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

Throws:

QueryEvaluationException

prepareNJoin

protected QueryEvaluationStep prepareNJoin(NJoin join,
 QueryEvaluationContext context)
                                    throws QueryEvaluationException

Throws:

QueryEvaluationException

evaluateArbitrayLengthPath

protected CloseableIteration<BindingSet> evaluateArbitrayLengthPath(FedXArbitraryLengthPath alp,
 BindingSet bindings)
                                                             throws QueryEvaluationException

Throws:

QueryEvaluationException

prepare

protected QueryEvaluationStep prepare(FedXArbitraryLengthPath alp,
 QueryEvaluationContext context)
                               throws QueryEvaluationException

Throws:

QueryEvaluationException

evaluateZeroLengthPath

protected CloseableIteration<BindingSet> evaluateZeroLengthPath(FedXZeroLengthPath zlp,
 BindingSet bindings)
                                                         throws QueryEvaluationException

Throws:

QueryEvaluationException

prepare

protected QueryEvaluationStep prepare(FedXZeroLengthPath zlp,
 QueryEvaluationContext context)
                               throws QueryEvaluationException

Throws:

QueryEvaluationException

evaluateLeftJoin

protected CloseableIteration<BindingSet> 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:

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

prepareLeftJoin

protected QueryEvaluationStep prepareLeftJoin(FedXLeftJoin leftJoin,
 QueryEvaluationContext context)
                                       throws QueryEvaluationException

Throws:

QueryEvaluationException

evaluateNaryUnion

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

Throws:

QueryEvaluationException

prepareNaryUnion

public QueryEvaluationStep prepareNaryUnion(NUnion union,
 QueryEvaluationContext context)
                                     throws QueryEvaluationException

Throws:

QueryEvaluationException

executeJoin

protected abstract CloseableIteration<BindingSet> executeJoin(ControlledWorkerScheduler<BindingSet> joinScheduler,
 CloseableIteration<BindingSet> 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> evaluateExclusiveGroup(ExclusiveGroup group,
 BindingSet bindings)
                                                               throws RepositoryException,
MalformedQueryException,
QueryEvaluationException

Throws:

RepositoryException

MalformedQueryException

QueryEvaluationException

evaluateExclusiveTupleExpr

protected CloseableIteration<BindingSet> 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

prepareExclusiveTupleExpr

protected QueryEvaluationStep prepareExclusiveTupleExpr(ExclusiveTupleExpr expr,
 QueryEvaluationContext context)
                                                 throws RepositoryException,
MalformedQueryException,
QueryEvaluationException

Throws:

RepositoryException

MalformedQueryException

QueryEvaluationException

evaluateBoundJoinStatementPattern

public abstract CloseableIteration<BindingSet> 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> 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> 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

@Deprecated(forRemoval=true)
public Value evaluate(ValueExpr expr,
 BindingSet bindings)
               throws ValueExprEvaluationException,
QueryEvaluationException

Deprecated, for removal: This API element is subject to removal in a future version.

Description copied from interface: EvaluationStrategy

Gets the value of this expression.

Specified by:

evaluate in interface EvaluationStrategy

Overrides:

evaluate in class DefaultEvaluationStrategy

Parameters:

expr -

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

precompile

public QueryValueEvaluationStep precompile(ValueExpr expr,
 QueryEvaluationContext context)
                                    throws ValueExprEvaluationException,
QueryEvaluationException

Specified by:

precompile in interface EvaluationStrategy

Overrides:

precompile in class DefaultEvaluationStrategy

Throws:

ValueExprEvaluationException

QueryEvaluationException

evaluate

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

Throws:

ValueExprEvaluationException

QueryEvaluationException

prepare

protected QueryValueEvaluationStep prepare(FilterExpr node,
 QueryEvaluationContext context)
                                    throws ValueExprEvaluationException,
QueryEvaluationException

Throws:

ValueExprEvaluationException

QueryEvaluationException

evaluate

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

Throws:

ValueExprEvaluationException

QueryEvaluationException

prepare

protected QueryValueEvaluationStep prepare(ConjunctiveFilterExpr node,
 QueryEvaluationContext context)
                                    throws ValueExprEvaluationException,
QueryEvaluationException

Throws:

ValueExprEvaluationException

QueryEvaluationException

evaluate

public CloseableIteration<BindingSet> evaluate(DescribeOperator operator,
 BindingSet bindings)
                                        throws QueryEvaluationException

Throws:

QueryEvaluationException

prepare

protected QueryEvaluationStep prepare(DescribeOperator operator,
 QueryEvaluationContext context)
                               throws QueryEvaluationException

Overrides:

prepare in class DefaultEvaluationStrategy

Throws:

QueryEvaluationException

evaluateAtStatementSources

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

Throws:

QueryEvaluationException

evaluateAtStatementSources

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

Throws:

QueryEvaluationException

evaluateAtStatementSources

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

Throws:

QueryEvaluationException