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

Class GroupExpressionRef<T extends RelationalExpression>

java.lang.Object

com.apple.foundationdb.record.query.plan.temp.GroupExpressionRef<T>

Type Parameters:

T - the type of planner expression that is contained in this reference

All Implemented Interfaces:

Bindable, Correlated<ExpressionRef<T>>, ExpressionRef<T>

@API(EXPERIMENTAL)
public class GroupExpressionRef<T extends RelationalExpression>
extends Object
implements ExpressionRef<T>

A Cascades-style group expression, representing the members of set of RelationalExpressions that belong to the same equivalence class.

The memo data structure can compactly represent a large set of similar RelationalExpressions through careful memoization. The Cascades "group expression", represented by the GroupExpressionRef, is the key to that memoization by sharing optimization work on a sub-expression with other parts of the expression that reference the same sub-expression.

The reference abstraction is designed to make it difficult for authors of rules to mutate group expressions directly, which is undefined behavior. Note that a GroupExpressionRef cannot be "dereferenced" using the get() method if it contains more than one member. Expressions with more than one member should not be used outside of the query planner, and get() should not be used inside the query planner.

Nested Class Summary

Nested classes/interfaces inherited from interface com.apple.foundationdb.record.query.plan.temp.Correlated

Correlated.BoundEquivalence

Nested classes/interfaces inherited from interface com.apple.foundationdb.record.query.plan.temp.ExpressionRef

ExpressionRef.UngettableReferenceException

Method Summary

Modifier and Type	Method	Description
<U> U	acceptPropertyVisitor(PlannerProperty<U> property)
boolean	addPartialMatchForCandidate(MatchCandidate candidate, PartialMatch partialMatch)	Add the PartialMatch passed in to this reference for the MatchCandidate passed in.
Stream<PlannerBindings>	bindWithin(PlannerBindings outerBindings, ExpressionMatcher<? extends Bindable> matcher)	Try to bind the given matcher to the members of this reference.
void	clear()
boolean	containsAllInMemo(ExpressionRef<? extends RelationalExpression> otherRef, AliasMap equivalenceMap)
boolean	containsExactly(T expression)
boolean	containsInMemo(RelationalExpression expression)
static <T extends RelationalExpression> GroupExpressionRef<T>	empty()
<U extends RelationalExpression> ExpressionRef<U>	flatMapNullable(Function<T,ExpressionRef<U>> nullableFunc)
static <T extends RelationalExpression> GroupExpressionRef<T>	from(Collection<T> expressions)
T	get()	Return the expression contained in this reference.
Set<CorrelationIdentifier>	getCorrelatedTo()	Returns the set of CorrelationIdentifiers this entity is correlated to.
Set<MatchCandidate>	getMatchCandidates()	Return all match candidates that partially match this reference.
RelationalExpressionPointerSet<T>	getMembers()
ExpressionRef<T>	getNewRefWith(T expression)
Set<PartialMatch>	getPartialMatchesForCandidate(MatchCandidate candidate)	Return all partial matches for the MatchCandidate passed in.
Collection<PartialMatch>	getPartialMatchesForExpression(RelationalExpression expression)	Return all partial matches that match a given expression.
boolean	insert(T newValue)	Insert a new expression into this reference.
boolean	isExplored()
<U extends RelationalExpression> ExpressionRef<U>	map(Function<T,U> func)
static <T extends RelationalExpression> GroupExpressionRef<T>	of(T expression)
static <T extends RelationalExpression> GroupExpressionRef<T>	of(T... expressions)
GroupExpressionRef<T>	rebase(AliasMap translationMap)	Rebases this and all other objects this objects is composed of using a given translation map.
boolean	replace(T newValue)
boolean	semanticEquals(Object other, AliasMap aliasMap)	Determine equality with respect to an equivalence map between CorrelationIdentifiers based on semantic equality: equality of the plan fragments implementing under the given correlation bindings.
int	semanticHashCode()	Return a semantic hash code for this object.
void	setExplored()
String	show(boolean renderSingleGroups)	Method to render the graph rooted at this reference.
String	toString()

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.apple.foundationdb.record.query.plan.temp.ExpressionRef

bindTo

Method Detail

get

@Nonnull
public T get()

Description copied from interface: ExpressionRef

Return the expression contained in this reference. If the reference does not support getting its expresssion (for example, because it holds more than one expression, or none at all), this should throw an exception.

Specified by:

get in interface ExpressionRef<T extends RelationalExpression>

Returns:

the expression contained in this reference

replace

public boolean replace(@Nonnull
                       T newValue)

insert

public boolean insert(@Nonnull
                      T newValue)

Description copied from interface: ExpressionRef

Insert a new expression into this reference.

Specified by:

insert in interface ExpressionRef<T extends RelationalExpression>

Parameters:

newValue - the value to be inserted

Returns:

true if the value was not already part of the reference and was inserted, false if the given value was already contained in the reference and was therefore not inserted.

containsExactly

public boolean containsExactly(@Nonnull
                               T expression)

containsAllInMemo

public boolean containsAllInMemo(@Nonnull
                                 ExpressionRef<? extends RelationalExpression> otherRef,
                                 @Nonnull
                                 AliasMap equivalenceMap)

Specified by:

containsAllInMemo in interface ExpressionRef<T extends RelationalExpression>

containsInMemo

public boolean containsInMemo(@Nonnull
                              RelationalExpression expression)

getCorrelatedTo

@Nonnull
public Set<CorrelationIdentifier> getCorrelatedTo()

Description copied from interface: Correlated

Returns the set of CorrelationIdentifiers this entity is correlated to. This means that without a process that binds these correlations to values, the RelationalExpression (or others that implement this interface) cannot even in principle produce a meaningful result. As often times entities that implement this interface use composition and effectively describe trees or DAGs, this method should be the set union of the CorrelationIdentifiers this object is correlated to as well as all children, constituent parts, etc.

Specified by:

getCorrelatedTo in interface Correlated<T extends RelationalExpression>

Returns:

the set of CorrelationIdentifiers this entity is correlated to

rebase

@Nonnull
public GroupExpressionRef<T> rebase(@Nonnull
                                    AliasMap translationMap)

Description copied from interface: Correlated

Rebases this and all other objects this objects is composed of using a given translation map.

Specified by:

rebase in interface Correlated<T extends RelationalExpression>

Parameters:

translationMap - a map defining a translation from CorrelationIdentifiers ids to CorrelationIdentifiers ids'. After the rebase, every correlation to an id contained ids that is contained or referred to directly or indirectly by this must have been transformed to use the mapped counterpart of id id' in ids'. IDs not contained in the translation map must remain unmodified by the rebase operation.

Returns:

a new entity that has been rebased

clear

public void clear()

setExplored

public void setExplored()

isExplored

public boolean isExplored()

getMembers

@Nonnull
public RelationalExpressionPointerSet<T> getMembers()

Specified by:

getMembers in interface ExpressionRef<T extends RelationalExpression>

getNewRefWith

@Nonnull
public ExpressionRef<T> getNewRefWith(@Nonnull
                                      T expression)

Specified by:

getNewRefWith in interface ExpressionRef<T extends RelationalExpression>

bindWithin

@Nonnull
public Stream<PlannerBindings> bindWithin(@Nonnull
                                          PlannerBindings outerBindings,
                                          @Nonnull
                                          ExpressionMatcher<? extends Bindable> matcher)

Description copied from interface: ExpressionRef

Try to bind the given matcher to the members of this reference. If this reference has more than one member, it should try to match to any of them and produce a stream of bindings covering all possible combinations. If possible, this should be done in a lazy fashion using the Stream API, so as to minimize unnecessary work.

Specified by:

bindWithin in interface ExpressionRef<T extends RelationalExpression>

Parameters:

outerBindings - preexisting bindings

matcher - an expression matcher to match the member(s) of this reference with

Returns:

a stream of bindings if the match succeeded or an empty stream if it failed

acceptPropertyVisitor

@Nullable
public <U> U acceptPropertyVisitor(@Nonnull
                                   PlannerProperty<U> property)

Specified by:

acceptPropertyVisitor in interface ExpressionRef<T extends RelationalExpression>

map

@Nonnull
public <U extends RelationalExpression> ExpressionRef<U> map(@Nonnull
                                                             Function<T,U> func)

Specified by:

map in interface ExpressionRef<T extends RelationalExpression>

flatMapNullable

@Nullable
public <U extends RelationalExpression> ExpressionRef<U> flatMapNullable(@Nonnull
                                                                         Function<T,ExpressionRef<U>> nullableFunc)

Specified by:

flatMapNullable in interface ExpressionRef<T extends RelationalExpression>

toString

public String toString()

Overrides:

toString in class Object

empty

public static <T extends RelationalExpression> GroupExpressionRef<T> empty()

of

public static <T extends RelationalExpression> GroupExpressionRef<T> of(@Nonnull
                                                                        T expression)

of

public static <T extends RelationalExpression> GroupExpressionRef<T> of(@Nonnull
                                                                        T... expressions)

from

public static <T extends RelationalExpression> GroupExpressionRef<T> from(@Nonnull
                                                                          Collection<T> expressions)

semanticEquals

public boolean semanticEquals(@Nullable
                              Object other,
                              @Nonnull
                              AliasMap aliasMap)

Description copied from interface: Correlated

Determine equality with respect to an equivalence map between CorrelationIdentifiers based on semantic equality: equality of the plan fragments implementing under the given correlation bindings. The contract of this variant of equals() differs from its regular Java counterpart. A correlation is mostly just one part inside of composition of objects that expresses a more complicated (correlated) structure such as a filter. For instance q1.x = 5 uses a correlation to q1. That entity representing the filter is said to be correlated to q1. Similarly, q1.x = 6 is a different filter and is not equal under any correlation mapping. In contrast, consider a predicate where everything except the correlation is the same, such as q2.x = 5. Without a binding, these two filters are not the same. However, the filters may be a part of some other entity that can express correlations: SELECT * FROM T as q1 WHERE q1.x = 5 is equal to SELECT * FROM T as q2 WHERE q2.x = 5. It does not matter that q1 and q2 are named differently. It is important, however, that their semantic meaning is the same. In the example both q1 and q2 refer to a record type T which presumably is the same record type. Therefore, these two query blocks are the same, even though they are labelled differently. In the context of this method, we can establish equality between q1.x = 5 and q2.x = 5 if we know that q1 and q2 refer to the same underlying entity. The equivalence map passed in encodes that equality between CorrelationIdentifiers. Note: This method has the same interaction with Object.hashCode() as the regular equals() method. As we can only ever establish true equality using equivalence maps, hashCode() implementations in implementors of this interface must not be dependent on any correlation identifiers used in the structure of the entity. Doing so might violate the fundamental property of hash codes: e1.equals(e2, ...) => e1.hashCode() == e2.hashCode()

Specified by:

semanticEquals in interface Correlated<T extends RelationalExpression>

Parameters:

other - the other object to establish equality with

aliasMap - a map of CorrelationIdentifiers ids to ids'. A correlation identifier id used in this should be considered equal to another correlation identifier id' used in other if either they are the same by Object.equals(java.lang.Object) of if there is a mapping from id to id'.

Returns:

true if both entities are considered equal using the equivalences passed in, false otherwise

semanticHashCode

public int semanticHashCode()

Description copied from interface: Correlated

Return a semantic hash code for this object. The hash code must obey the convention that for any two objects o1 and o2 and for every AliasMap aliasMap:

 o1.semanticEquals(o1, aliasMap) follows o1.semanticHash() == o2.semanticHash()
 

If the semantic hash code of two implementing objects is equal and Correlated.semanticEquals(java.lang.Object, com.apple.foundationdb.record.query.plan.temp.AliasMap) returns true for these two objects the plan fragments are considered to produce the same result under the given correlations bindings. The left side o1.semanticEquals(o1, aliasMap) depends on an AliasMap while o1.semanticHash() == o2.semanticHash() does not. Hence, the hash that is computed is identical regardless of possible bindings.

Specified by:

semanticHashCode in interface Correlated<T extends RelationalExpression>

Returns:

the semantic hash code

getMatchCandidates

@Nonnull
public Set<MatchCandidate> getMatchCandidates()

Description copied from interface: ExpressionRef

Return all match candidates that partially match this reference. This set must be a subset of all MatchCandidates in the PlanContext during planning. Note that it is possible that a particular match candidate matches this reference more than once.

Specified by:

getMatchCandidates in interface ExpressionRef<T extends RelationalExpression>

Returns:

a set of match candidates that partially match this reference.

getPartialMatchesForExpression

@Nonnull
public Collection<PartialMatch> getPartialMatchesForExpression(@Nonnull
                                                               RelationalExpression expression)

Description copied from interface: ExpressionRef

Return all partial matches that match a given expression. This method is agnostic of the MatchCandidate that created the partial match.

Specified by:

getPartialMatchesForExpression in interface ExpressionRef<T extends RelationalExpression>

Parameters:

expression - expression to return partial matches for. This expression has to be a member of this reference

Returns:

a collection of partial matches that matches the give expression to some candidate

getPartialMatchesForCandidate

@Nonnull
public Set<PartialMatch> getPartialMatchesForCandidate(MatchCandidate candidate)

Description copied from interface: ExpressionRef

Return all partial matches for the MatchCandidate passed in.

Specified by:

getPartialMatchesForCandidate in interface ExpressionRef<T extends RelationalExpression>

Parameters:

candidate - match candidate

Returns:

a set of partial matches for candidate

addPartialMatchForCandidate

public boolean addPartialMatchForCandidate(MatchCandidate candidate,
                                           PartialMatch partialMatch)

Description copied from interface: ExpressionRef

Add the PartialMatch passed in to this reference for the MatchCandidate passed in.

Specified by:

addPartialMatchForCandidate in interface ExpressionRef<T extends RelationalExpression>

Parameters:

candidate - match candidate this partial match relates to

partialMatch - a new partial match.

Returns:

true if this call added a new partial, false if the partial match passed in was already contained in this reference

show

@Nonnull
public String show(boolean renderSingleGroups)

Method to render the graph rooted at this reference. This is needed for graph integration into IntelliJ as IntelliJ only ever evaluates selfish methods. Add this method as a custom renderer for the type GroupExpressionRef. During debugging you can then click show() on an instance and enjoy the query graph it represents rendered in your standard browser.

Parameters:

renderSingleGroups - whether to render group references with just one member

Returns:

the String "done"