Package com.apple.foundationdb.record.query.plan.temp

Interface PlannerProperty<T>

Type Parameters:

T - the result type of the property

All Known Implementing Classes:

CreatesDuplicatesProperty, ExpressionCountProperty, FieldWithComparisonCountProperty, OrderingProperty, PlannerGraphProperty, PredicateCountProperty, RecordTypesProperty, RelationalExpressionDepthProperty, TypeFilterCountProperty, UnmatchedFieldsProperty

@API(EXPERIMENTAL)
public interface PlannerProperty<T>

An interface for certain Cascades-style properties, which are measurable features of an expression other than the structure of the expression tree. In particular, a PlannerProperty is a property that depends on (much of) the contents of the subtree rooted at the expression on which it is evaluated, rather than just a finite depth set of paths as a ExpressionMatcher would. For example, the sort order and set of record types produced by a RelationalExpression could be a PlannerProperty.

To avoid littering RelationalExpression classes with methods for various properties, properties are implemented using a variant of the hierarchical visitor pattern over a DAG of RelationalExpressions, Quantifiers, and ExpressionRefs. A property can be evaluated against an expression tree by having the visitor traverse a DAG of heterogeneous objects where expressions are said to own quantifiers which range over expression references which then contain expressions again. Shared subgraphs are visited multiple times. If desired, the caller must ensure that a subgraph is not visited more than once.

Note that the methods evaluateAtExpression(com.apple.foundationdb.record.query.plan.temp.RelationalExpression, java.util.List<T>), evaluateAtQuantifier(com.apple.foundationdb.record.query.plan.temp.Quantifier, T), and evaluateAtRef(com.apple.foundationdb.record.query.plan.temp.ExpressionRef<? extends com.apple.foundationdb.record.query.plan.temp.RelationalExpression>, java.util.List<T>) are handed the results of the visitor evaluated at their owned quantifiers, references, and members respectively. Since most properties are easy to describe as a recursion with depth one, this makes properties easier to read and write.

Note that the default implementations provided in this interface walk the entire DAG, i.e. all shouldVisit(com.apple.foundationdb.record.query.plan.temp.RelationalExpression) methods return true. That implies that properties have been computed for sub-structures of the graph when evaluateAtXXX() is called and therefore are not null. That means that all such arguments can be assumed to be non-nullable even though parameters are annotated as Nullable. On the other hand, if the implementor also overrides shouldVisit to return false, arguments to evaluateAtXXX may become nullable or contain nulls if they are collections and should be dealt with gracefully.

Method Summary

Modifier and Type	Method	Description
T	evaluateAtExpression(RelationalExpression expression, List<T> childResults)	Evaluate the property at the given expression, using the results of evaluating the property at its children.
default T	evaluateAtQuantifier(Quantifier quantifier, T rangesOverResult)	Evaluate the property at the given quantifier, using the result of evaluating the property at the reference the quantifier ranges over.
T	evaluateAtRef(ExpressionRef<? extends RelationalExpression> ref, List<T> memberResults)	Evaluate the property at the given reference, using the results of evaluating the property at its members.
default boolean	shouldVisit(ExpressionRef<? extends RelationalExpression> ref)	Return whether the property should visit the given reference and, transitively, the members of the reference.
default boolean	shouldVisit(Quantifier quantifier)	Return whether the property should visit the given quantifier and the references that the quantifier ranges over.
default boolean	shouldVisit(RelationalExpression expression)	Return whether the property should visit the subgraph rooted at the given expression.

Method Detail

shouldVisit

default boolean shouldVisit(@Nonnull
                            RelationalExpression expression)

Return whether the property should visit the subgraph rooted at the given expression. Called on nodes in the expression graph in visit pre-order of the depth-first traversal of the graph. That is, as each node is visited for the first time, shouldVisit() is called on that node. If shouldVisit() returns false, then evaluateAtExpression(RelationalExpression, List) will not be called on the given expression.

Parameters:

expression - the planner expression to visit

Returns:

true if the children of expression should be visited and false if they should not be visited

shouldVisit

default boolean shouldVisit(@Nonnull
                            ExpressionRef<? extends RelationalExpression> ref)

Return whether the property should visit the given reference and, transitively, the members of the reference. Called on expression references in the graph in visit pre-order of the depth-first traversal of the graph. That is, as a reference is visited, shouldVisit() is called on that reference. If shouldVisit() returns false, then evaluateAtRef(ExpressionRef, List) will not be called on the given reference.

Parameters:

ref - the expression reference to visit

Returns:

true if the members of ref should be visited and false if they should not be visited

shouldVisit

default boolean shouldVisit(@Nonnull
                            Quantifier quantifier)

Return whether the property should visit the given quantifier and the references that the quantifier ranges over. Called on quantifiers in the graph in visit pre-order of the depth-first traversal of the graph. That is, as a quantifier is visited, shouldVisit() is called on that quantifier. If shouldVisit() returns false, then evaluateAtQuantifier(Quantifier, Object) will not be called on the given quantifier.

Parameters:

quantifier - the quantifier to visit

Returns:

true if the expression reference quantifier ranges over should be visited and false if it should not be visited

evaluateAtExpression

@Nonnull
T evaluateAtExpression(@Nonnull
                       RelationalExpression expression,
                       @Nonnull
                       List<T> childResults)

Evaluate the property at the given expression, using the results of evaluating the property at its children. Called on nodes in the graph in visit post-order of the depth-first traversal of the graph. That is, as each expression is visited (after all of its children have been visited, if applicable), evaluateAtExpression() is called on that expression.

Parameters:

expression - the cursor to visit

childResults - the results of the property evaluated at the children of expression

Returns:

the value of property at the given expression

evaluateAtRef

@Nonnull
T evaluateAtRef(@Nonnull
                ExpressionRef<? extends RelationalExpression> ref,
                @Nonnull
                List<T> memberResults)

Evaluate the property at the given reference, using the results of evaluating the property at its members. Called on nodes in the graph in visit post-order of the depth-first traversal of the graph. That is, as each reference is visited (after all of its members have been visited, if applicable), evaluateAtRef() is called on that reference.

Parameters:

ref - the expression reference to visit

memberResults - the results of the property evaluated at the members of ref

Returns:

the value of property at the given reference

evaluateAtQuantifier

@Nonnull
default T evaluateAtQuantifier(@Nonnull
                               Quantifier quantifier,
                               @Nullable
                               T rangesOverResult)

Evaluate the property at the given quantifier, using the result of evaluating the property at the reference the quantifier ranges over. Called on quantifiers in the graph in visit post-order of the depth-first traversal of the graph. That is, as each quantifier is visited (after the expression reference it ranges over has been visited, if applicable), evaluateAtQuantifier() is called on that quantifier.

Parameters:

quantifier - the quantifier to visit

rangesOverResult - the result of the property evaluated at the ExpressionRef quantifier ranges over

Returns:

the value of property at the given quantifier