com.apple.foundationdb.record.query

Class QueryToKeyMatcher

java.lang.Object

com.apple.foundationdb.record.query.QueryToKeyMatcher

@API(value=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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	QueryToKeyMatcher.Match The result of matching a particular KeyExpression.
static class	QueryToKeyMatcher.MatchType Whether a match was a successful, and if it was, whether the resulting keys have a single value.

Constructor Summary

Constructors

Constructor and Description
QueryToKeyMatcher(QueryComponent rootQuery)

Method Summary

Modifier and Type	Method and Description
QueryToKeyMatcher.Match	matches(KeyExpression expression) Deprecated. use matchesSatisfyingQuery(KeyExpression) instead
QueryToKeyMatcher.Match	matchesCoveringKey(KeyExpression expression) Attempt to match the expression to this matcher's root query and use every column in the key.
QueryToKeyMatcher.Match	matchesCoveringKey(KeyExpression expression, FilterSatisfiedMask filterMask) Attempt to match the expression to this matcher's root query and use every column in the key.
QueryToKeyMatcher.Match	matchesSatisfyingQuery(KeyExpression expression) Attempt to match the expression to this matcher's root query and satisfy every filter.
QueryToKeyMatcher.Match	matchesSatisfyingQuery(KeyExpression expression, FilterSatisfiedMask filterMask) Attempt to match the expression to this matcher's root query and satisfy every filter.

Methods inherited from class java.lang.Object

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

Constructor Detail

QueryToKeyMatcher

public QueryToKeyMatcher(@Nonnull
                         QueryComponent rootQuery)

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

matches

@Nonnull
 @Deprecated
public QueryToKeyMatcher.Match matches(@Nonnull
                                                             KeyExpression expression)

Deprecated. use matchesSatisfyingQuery(KeyExpression) instead

Attempt to match the expression to this matcher's root query and satisfy every filter. This has been deprecated in favor of matchesSatisfyingQuery(KeyExpression).

Parameters:

expression - the key expression to match the root query to

Returns:

a match if the entire expression is satisfied by this expression