Package com.apple.foundationdb.record.query

Class QueryToKeyMatcher

  • @API(INTERNAL)
public class QueryToKeyMatcher
extends Object
    Match a query filter, represented by a QueryComponent, to a KeyExpression. In particular, this will find a sequence of comparisons that can be applied to the elements of a key expression in order to satisfy some (or all) of the query. For example, if the query filter is WHERE x = 1 AND y = 2 and this is matched against concat(x, y), then this will return [EQUALS 1, EQUALS 2]. This indicates that if one, for example, had an index on concat(x, y), then scanning over all index entries beginning with (1, 2) would satisfy the query.

    There are two methods that attempt to match the query to a key expression. The first is the matchesSatisfyingQuery() method. This should be used if one wants to make sure that one can use the given key expression to retrieve all records that match the given query (i.e., the whether the fields included in the key expression contain enough information to satisfy the entire query). If there are unsatisfied components in the filter, this will return a match with type NO_MATCH. The other mode is the matchesCoveringKey() method. This attempts to find a list of comparisons such that every column of the key expression has been set by some component of the filter. However, there may be components of the filter that are unsatisfied.

    By way of example, if the filter is WHERE x = 1 AND y = 2 and the expression is just on field x, then if one calls the matchesSatisfyingQuery method, the matcher will return NO_MATCH, but it will return [EQUALS 1] if the matchesCoveringKey method is called. By contrast, if the filter is WHERE x = 1 AND y = 2 and the expression is concat(x, y, z), then calling matchesSatisfyingQuery will return [EQUALS 1, EQUALS 2], but calling matchesCoveringKey will return NO_MATCH.

    • Method Detail

      • matchesCoveringKey

        @Nonnull
public QueryToKeyMatcher.Match matchesCoveringKey​(@Nonnull
                                                  KeyExpression expression)
        Attempt to match the expression to this matcher's root query and use every column in the key. This will not track which components of the query are used when covering the given expression. To do that, call matchesCoveringKey(KeyExpression, FilterSatisfiedMask) and provide a non-null value for the filterMask parameter.
        Parameters:
        expression - the key expression to match the root query to
        Returns:
        a match if the entire expression is covered by the root query

      • matchesCoveringKey

        @Nonnull
public QueryToKeyMatcher.Match matchesCoveringKey​(@Nonnull
                                                  KeyExpression expression,
                                                  @Nullable
                                                  FilterSatisfiedMask filterMask)
        Attempt to match the expression to this matcher's root query and use every column in the key. This will track which components of the query were used when covering the given expression if filterMask is non-null.
        Parameters:
        expression - the key expression to match the root query to
        filterMask - a mask over this matcher's root query to track which filters have been satisfied
        Returns:
        a match if the entire expression is covered by the root query

      • matchesSatisfyingQuery

        @Nonnull
public QueryToKeyMatcher.Match matchesSatisfyingQuery​(@Nonnull
                                                      KeyExpression expression)
        Attempt to match the expression to this matcher's root query and satisfy every filter. Most of the time when calling this method, tracking which filters have been satisfied should be unnecessary as either they will be satisfied or this function will return a match with NO_MATCH as its match type. However, if this is needed, one can call matchesSatisfyingQuery(KeyExpression, FilterSatisfiedMask) and provide a non-null value for the filterMask parameter.
        Parameters:
        expression - the key expression to match the root query to
        Returns:
        a match if the entire expression is satisfied by this expression

      • matchesSatisfyingQuery

        @Nonnull
public QueryToKeyMatcher.Match matchesSatisfyingQuery​(@Nonnull
                                                      KeyExpression expression,
                                                      @Nullable
                                                      FilterSatisfiedMask filterMask)
        Attempt to match the expression to this matcher's root query and satisfy every filter. Most of the time when calling this method, tracking which filters have been satisfied should be unnecessary as either they will be satisfied or this function will return a match with NO_MATCH as its match type. However, if this is needed, one can provide a non-null value for the filterMask parameter.
        Parameters:
        expression - the key expression to match the root query to
        filterMask - a mask over this matcher's root query to track which filters have been satisfied
        Returns:
        a match if the entire expression is satisfied by this expression