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, aPlannerProperty
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 aExpressionMatcher
would. For example, the sort order and set of record types produced by aRelationalExpression
could be aPlannerProperty
.To avoid littering
RelationalExpression
classes with methods for various properties, properties are implemented using a variant of the hierarchical visitor pattern over a DAG ofRelationalExpression
s,Quantifier
s, andExpressionRef
s. 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)
, andevaluateAtRef(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 returntrue
. That implies that properties have been computed for sub-structures of the graph whenevaluateAtXXX()
is called and therefore are notnull
. That means that all such arguments can be assumed to be non-nullable even though parameters are annotated asNullable
. On the other hand, if the implementor also overridesshouldVisit
to returnfalse
, arguments toevaluateAtXXX
may become nullable or containnull
s if they are collections and should be dealt with gracefully.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods 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. IfshouldVisit()
returnsfalse
, thenevaluateAtExpression(RelationalExpression, List)
will not be called on the given expression.- Parameters:
expression
- the planner expression to visit- Returns:
true
if the children ofexpression
should be visited andfalse
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. IfshouldVisit()
returnsfalse
, thenevaluateAtRef(ExpressionRef, List)
will not be called on the given reference.- Parameters:
ref
- the expression reference to visit- Returns:
true
if the members ofref
should be visited andfalse
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. IfshouldVisit()
returnsfalse
, thenevaluateAtQuantifier(Quantifier, Object)
will not be called on the given quantifier.- Parameters:
quantifier
- the quantifier to visit- Returns:
true
if the expression referencequantifier
ranges over should be visited andfalse
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 visitchildResults
- the results of the property evaluated at the children ofexpression
- 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 visitmemberResults
- the results of the property evaluated at the members ofref
- 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 visitrangesOverResult
- the result of the property evaluated at theExpressionRef
quantifier
ranges over- Returns:
- the value of property at the given quantifier
-
-