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

Class FilterSatisfiedMask

  • @API(INTERNAL)
public class FilterSatisfiedMask
extends Object
    A mask that can be applied over a QueryComponent 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.

    • 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 return true 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 to true, 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 to false means that it might still be needed in some kind of post-filter. In general, users should use reset() 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 return null 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 to null if the filter is being marked as unsatisfied for whatever reason. However, users should generally call reset() 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

      • 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 a QueryComponent that is equal to the original QueryComponent 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 return null
        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 return true. 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 return true if every child is satisfied and false otherwise. If this filter is unsatisfied and it does not traverse down this mask's children, then it will return false.

        This is supposed to be functionally equivalent to calling getUnsatisfiedFilter() and checking to see if the result is null. 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 a FilterSatisfiedMask.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 - if other is not a mask of the same filter as this mask

      • of

        @Nonnull
public static FilterSatisfiedMask of​(@Nonnull
                                     QueryComponent filter)
        Create a mask around a QueryComponent. 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