Class FilterSatisfiedMask
- java.lang.Object
-
- com.apple.foundationdb.record.query.plan.planning.FilterSatisfiedMask
-
@API(INTERNAL) public class FilterSatisfiedMask extends Object
A mask that can be applied over aQueryComponent
to determine whether a filter and any sub-filters or child components have been satisfied. This can be used to track which sub-components of a given filter have already been satisfied by a planned query and which ones might require an additional filter on the returned results.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
FilterSatisfiedMask.FilterMismatchException
Thrown in instances where one expects the underlying filter associated with anotherFilterSatisfiedMask
to match this one but they do not.class
FilterSatisfiedMask.FilterNotFoundException
Thrown if the user requests a child mask from a component, but the mask does not contain that component in any of its children.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
allSatisfied()
Determine if the whole filter has been satisfied.FilterSatisfiedMask
getChild(QueryComponent childFilter)
Return the child mask associated with a child of the mask's filter.List<FilterSatisfiedMask>
getChildren()
Get the list of children of this filter.KeyExpression
getExpression()
Get the expression that satisfied this filter.QueryComponent
getFilter()
Get the filter that this mask is masking.QueryComponent
getUnsatisfiedFilter()
Construct aQueryComponent
that is equal to the originalQueryComponent
but with any satisfied filters removed.List<QueryComponent>
getUnsatisfiedFilters()
Create a list of filters that are not satisfied.boolean
isSatisfied()
Return whether this filter is known to have been satisfied.void
mergeWith(FilterSatisfiedMask other)
Merge in another mask over the same filter.static FilterSatisfiedMask
of(QueryComponent filter)
Create a mask around aQueryComponent
.void
reset()
Reset this mask so all filters are marked as unsatisfied.void
setExpression(KeyExpression expression)
Set the expression that satisfied this filter.void
setSatisfied(boolean satisfied)
Set whether this filter has been satisfied.String
toString()
-
-
-
Method Detail
-
isSatisfied
public boolean isSatisfied()
Return whether this filter is known to have been satisfied. This will not this will not traverse down the children of this filter, but it might returntrue
if someone has already performed a traversal and marked this filter as satisfied.- Returns:
- whether this filter is known to have been satisfied
-
setSatisfied
public void setSatisfied(boolean satisfied)
Set whether this filter has been satisfied. If set totrue
, this means that the filter is no longer needed because a query plan has already been able to filter out any records that would match it. Setting it tofalse
means that it might still be needed in some kind of post-filter. In general, users should usereset()
if they need to say that a filter has not been satisfied, as (unlike this method), that method traverses down the children of this filter and recursively marks them all as unsatisfied.- Parameters:
satisfied
- whether this filter has been satisfied already
-
getExpression
@Nullable public KeyExpression getExpression()
Get the expression that satisfied this filter. Setting this expression is optional, and this may returnnull
if the filter has not been satisfied or if the expression was not set.- Returns:
- the expression that satisfied this filter or
null
-
setExpression
public void setExpression(@Nullable KeyExpression expression)
Set the expression that satisfied this filter. Users should generally set this to a non-null
value, though it should be set tonull
if the filter is being marked as unsatisfied for whatever reason. However, users should generally callreset()
if that is the case as that method will recursively reset all of this mask's children as well.- Parameters:
expression
- the expression that satisifed this filter
-
getFilter
@Nonnull public QueryComponent getFilter()
Get the filter that this mask is masking. In other words, this mask provides an annotated tree over the returned filter tracking with sub-filters have and have not been satisfied.- Returns:
- the filter this mask is masking
-
getChildren
@Nonnull public List<FilterSatisfiedMask> getChildren()
Get the list of children of this filter. It might be empty if the child itself does not have any children. The children are returned in the same order as the children of this mask's filter, and the filters of the returned children will be pointer-equal to the children of the mask.- Returns:
- the list of children of this filter
-
getChild
@Nonnull public FilterSatisfiedMask getChild(@Nonnull QueryComponent childFilter)
Return the child mask associated with a child of the mask's filter. In particular, this will check for pointer-equality between the filter provided and all children of this filter. It will then return the mask from the child list that matches. If none is found, it will throw anFilterSatisfiedMask.FilterNotFoundException
.- Parameters:
childFilter
- a child of the mask's filter- Returns:
- the child of this mask that is associated with the given filter
- Throws:
FilterSatisfiedMask.FilterNotFoundException
- if the given filter is not associated with any of the mask's children
-
reset
public void reset()
Reset this mask so all filters are marked as unsatisfied. This will traverse down any children and reset them as well.
-
getUnsatisfiedFilters
@Nonnull public List<QueryComponent> getUnsatisfiedFilters()
Create a list of filters that are not satisfied. This is mostly for maintaining compatibility with existing code within the planner that expects an unsatisfied filter list rather than an unsatisfied filter tree. This will return an empty list if the filter is satisfied.- Returns:
- a list of filters that are not satisfied according to this mask
-
getUnsatisfiedFilter
@Nullable public QueryComponent getUnsatisfiedFilter()
Construct aQueryComponent
that is equal to the originalQueryComponent
but with any satisfied filters removed. In other words, if one has been able to satisfy some sub-component of this filter through something like an index scan, then that part of the filter will be removed from the filter. If the entire filter has been satisfied, this will returnnull
- Returns:
- a filter equivalent to the unsatisfied components of the base filter
-
allSatisfied
public boolean allSatisfied()
Determine if the whole filter has been satisfied. If the filter itself has been marked as satisfied, then this will returntrue
. Otherwise, if the filter is a type where if the children have been satisfied, the filter has also been satisfied, then this traverses down the children to see if they have all been satisfied. It will then returntrue
if every child is satisfied andfalse
otherwise. If this filter is unsatisfied and it does not traverse down this mask's children, then it will returnfalse
.This is supposed to be functionally equivalent to calling
getUnsatisfiedFilter()
and checking to see if the result isnull
. This does not attempt to construct the unsatisfied filter if one exists, so this should be cheaper to call.- Returns:
- whether the whole filter is known to have been satisfied
-
mergeWith
public void mergeWith(@Nonnull FilterSatisfiedMask other)
Merge in another mask over the same filter. This will mark any filter that is satisfied in the other mask as satisfied within this mask. This is useful as it allows the planner to do something like speculatively mark certain fields as satisfied and then only mark them as satisfied in a main mask if the speculative work actually can be used. This will throw aFilterSatisfiedMask.FilterMismatchException
if the mask provided is not a filter over the same filter as this mask. The other mask's filter must be reference-equal to this mask's filter, not just logically equal.- Parameters:
other
- another mask over the same filter- Throws:
FilterSatisfiedMask.FilterMismatchException
- ifother
is not a mask of the same filter as this mask
-
of
@Nonnull public static FilterSatisfiedMask of(@Nonnull QueryComponent filter)
Create a mask around aQueryComponent
. This will traverse down any children of the filter and produce a full tree. It initializes all filters to being unsatisfied.- Parameters:
filter
- the filter to create the mask for- Returns:
- a mask initially claiming this filter and its sub-components are all unsatisfied
-
-