com.amazon.carbonado.qe
Class FilteringScore<S extends Storable>

java.lang.Object
  com.amazon.carbonado.qe.FilteringScore<S>

public class FilteringScore<S extends Storable>
extends Object

Evaluates an index for how well it matches a query's desired filtering. A filtering score is not a single absolute value – instead it has a relative weight when compared to other scores.

An index matches a desired filtering if the arrangement of properties and its relational operator matches. A matching = operator is an identity match. A range match is determined by a matching operator of >, >=, <, or <=. Filters with a != operator are ignored. Although not all index properties need to be used, the first must be and no gaps are allowed.

A FilteringScore measures the number of filter properties that are matched and the number that are remaining. If there are remainder properties, then the user of the evaluated index will need to perform an additional filtering operation to achieve the desired results.

In general, a FilteringScore is better than another if it has more matched properties and fewer remainder properties. Matching more identity properties is given preference over matching range properties. Index clustering is also considered for score comparison.

Author:

Brian S O'Neill

See Also:

OrderingScore, CompositeScore

Method Summary

boolean	canMergeRemainderFilter(FilteringScore<S> other) Returns true if the given score uses an index exactly the same as this one.
static <S extends Storable> FilteringScore<S>	evaluate(OrderedProperty<S>[] indexProperties, boolean unique, boolean clustered, Filter<S> filter) Evaluates the given index properties for its filtering capabilities against the given filter.
static <S extends Storable> FilteringScore<S>	evaluate(StorableIndex<S> index, Filter<S> filter) Evaluates the given index for its filtering capabilities against the given filter.
static Comparator<FilteringScore<?>>	fullComparator() Returns a comparator which determines which FilteringScores are better.
int	getArrangementScore() Returns a value which indicates how well the index property order matches the property filter specification order.
int	getCoveringCount() Returns number of covering property filters which are supported by the evaluated index.
Filter<S>	getCoveringFilter() Returns the composite covering filter supported by the evaluated index, or null if the covering count is zero.
List<? extends Filter<S>>	getCoveringFilters() Returns the covering filters which are supported by the evaluated index, which is a subset of the remainder filters.
Filter<S>	getCoveringRemainderFilter() Returns the composite remainder filter without including the covering filter.
List<PropertyFilter<S>>	getExclusiveRangeEndFilters() Returns the range end property filters supported by the evaluated index whose operator is only RelOp.LT.
List<PropertyFilter<S>>	getExclusiveRangeStartFilters() Returns the range start property filters supported by the evaluated index whose operator is only RelOp.GT.
int	getHandledCount() Returns the count of all handled property filters.
Filter<S>	getHandledFilter() Returns the composite handled filter, or null if no matches at all.
int	getIdentityCount() Returns number of consecutive left-aligned index properties which match property filters with an operator of RelOp.EQ.
Filter<S>	getIdentityFilter() Returns the composite identity filter, or null if no identity property filters.
List<PropertyFilter<S>>	getIdentityFilters() Returns the identity property filters supported by the evaluated index.
List<PropertyFilter<S>>	getInclusiveRangeEndFilters() Returns the range end property filters supported by the evaluated index whose operator is only RelOp.LE.
List<PropertyFilter<S>>	getInclusiveRangeStartFilters() Returns the range start property filters supported by the evaluated index whose operator is only RelOp.GE.
int	getIndexPropertyCount() Returns the amount of properties in the evaluated index.
Comparable	getPreferenceScore() Returns a value which indicates user index preference, based on the original ordering of elements in the filter.
List<PropertyFilter<S>>	getRangeEndFilters() Returns the range end property filters supported by the evaluated index.
List<PropertyFilter<S>>	getRangeStartFilters() Returns the range start property filters supported by the evaluated index.
int	getRemainderCount() Returns number of property filters not supported by the evaluated index.
Filter<S>	getRemainderFilter() Returns the composite remainder filter not supported by the evaluated index, or null if no remainder.
List<? extends Filter<S>>	getRemainderFilters() Returns the filters not supported by the evaluated index.
boolean	hasAnyMatches() Returns true if the identity count is greater than zero or if there is a range match.
boolean	hasRangeEnd() Returns true if any property filter with an operator of RelOp.LT or RelOp.LE matches an index property.
boolean	hasRangeMatch() Returns true if there is both a range start and range end.
boolean	hasRangeStart() Returns true if any property filter with an operator of RelOp.GT or RelOp.GE matches an index property.
boolean	isIndexClustered() Returns true if evaluated index is clustered.
boolean	isIndexUnique() Returns true if evaluated index is unique.
boolean	isKeyMatch() Returns true if evaluated index is unique and each of its properties has an identity match.
Filter<S>	mergeRemainderFilter(FilteringScore<S> other) Merges the remainder filter of this score with the one given using an 'or' operation.
static Comparator<FilteringScore<?>>	rangeComparator() Returns a partial comparator which determines which FilteringScores are better by examining only identity and range matches.
boolean	shouldReverseRange() Returns true if there is a range start or end match, but natural order of matching property is descending.
String	toString()
FilteringScore<S>	withRemainderFilter(Filter<S> filter) Returns a new FilteringScore with the remainder replaced and covering matches recalculated.

Methods inherited from class java.lang.Object

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

Method Detail

evaluate

public static <S extends Storable> FilteringScore<S> evaluate(StorableIndex<S> index,
                                                              Filter<S> filter)

Evaluates the given index for its filtering capabilities against the given filter.

Parameters:

index - index to evaluate

filter - filter which cannot contain any logical 'or' operations.

Throws:

IllegalArgumentException - if index is null or filter is not supported

evaluate

public static <S extends Storable> FilteringScore<S> evaluate(OrderedProperty<S>[] indexProperties,
                                                              boolean unique,
                                                              boolean clustered,
                                                              Filter<S> filter)

Evaluates the given index properties for its filtering capabilities against the given filter.

Parameters:

indexProperties - index properties to evaluate

unique - true if index is unique

clustered - true if index is clustered

filter - filter which cannot contain any logical 'or' operations.

Throws:

IllegalArgumentException - if index is null or filter is not supported

rangeComparator

public static Comparator<FilteringScore<?>> rangeComparator()

Returns a partial comparator which determines which FilteringScores are better by examining only identity and range matches. It does not matter if the scores were evaluated for different indexes or storable types. The comparator returns <0 if first score is better, 0 if equal, or >0 if second is better.

fullComparator

public static Comparator<FilteringScore<?>> fullComparator()

Returns a comparator which determines which FilteringScores are better. It compares identity matches, range matches, open range matches and property arrangement. It does not matter if the scores were evaluated for different indexes or storable types. The comparator returns <0 if first score is better, 0 if equal, or >0 if second is better.

isIndexClustered

public boolean isIndexClustered()

Returns true if evaluated index is clustered. Scans of clustered indexes are generally faster.

isIndexUnique

public boolean isIndexUnique()

Returns true if evaluated index is unique.

getIndexPropertyCount

public int getIndexPropertyCount()

Returns the amount of properties in the evaluated index.

getIdentityCount

public int getIdentityCount()

Returns number of consecutive left-aligned index properties which match property filters with an operator of RelOp.EQ.

getIdentityFilters

public List<PropertyFilter<S>> getIdentityFilters()

Returns the identity property filters supported by the evaluated index. The order of the list matches the order in which the properties appear in the index. The operator of each filter is RelOp.EQ.

getIdentityFilter

public Filter<S> getIdentityFilter()

Returns the composite identity filter, or null if no identity property filters.

hasRangeStart

public boolean hasRangeStart()

Returns true if any property filter with an operator of RelOp.GT or RelOp.GE matches an index property. The index property used for the range is the first one following the identity count.

getRangeStartFilters

public List<PropertyFilter<S>> getRangeStartFilters()

Returns the range start property filters supported by the evaluated index. The operator of each filter is either RelOp.GT or RelOp.GE. The property of each filter is identical, and the properties are also identical to any range end filters.

getExclusiveRangeStartFilters

public List<PropertyFilter<S>> getExclusiveRangeStartFilters()

Returns the range start property filters supported by the evaluated index whose operator is only RelOp.GT. This list is a subset of those returned by getRangeStartFilters().

getInclusiveRangeStartFilters

public List<PropertyFilter<S>> getInclusiveRangeStartFilters()

Returns the range start property filters supported by the evaluated index whose operator is only RelOp.GE. This list is a subset of those returned by getRangeStartFilters().

hasRangeEnd

public boolean hasRangeEnd()

Returns true if any property filter with an operator of RelOp.LT or RelOp.LE matches an index property. The index property used for the range is the first one following the identity count.

getRangeEndFilters

public List<PropertyFilter<S>> getRangeEndFilters()

Returns the range end property filters supported by the evaluated index. The operator of each filter is either RelOp.LT or RelOp.LE. The property of each filter is identical, and the properties are also identical to any range start filters.

getExclusiveRangeEndFilters

public List<PropertyFilter<S>> getExclusiveRangeEndFilters()

Returns the range end property filters supported by the evaluated index whose operator is only RelOp.LT. This list is a subset of those returned by getRangeEndFilters().

getInclusiveRangeEndFilters

public List<PropertyFilter<S>> getInclusiveRangeEndFilters()

Returns the range end property filters supported by the evaluated index whose operator is only RelOp.LE. This list is a subset of those returned by getRangeEndFilters().

getHandledCount

public int getHandledCount()

Returns the count of all handled property filters.

getHandledFilter

public Filter<S> getHandledFilter()

Returns the composite handled filter, or null if no matches at all.

hasRangeMatch

public boolean hasRangeMatch()

Returns true if there is both a range start and range end.

hasAnyMatches

public boolean hasAnyMatches()

Returns true if the identity count is greater than zero or if there is a range match.

getArrangementScore

public int getArrangementScore()

Returns a value which indicates how well the index property order matches the property filter specification order. A higher value can indicate that the index is a slightly better match.

Returns:

arrangement value, never negative

getPreferenceScore

public Comparable getPreferenceScore()

Returns a value which indicates user index preference, based on the original ordering of elements in the filter. A higher value can indicate that the index is a slightly better match.

Returns:

preference value which can be compared to another one

getRemainderCount

public int getRemainderCount()

Returns number of property filters not supported by the evaluated index.

getRemainderFilters

public List<? extends Filter<S>> getRemainderFilters()

Returns the filters not supported by the evaluated index.

getRemainderFilter

public Filter<S> getRemainderFilter()

Returns the composite remainder filter not supported by the evaluated index, or null if no remainder.

getCoveringCount

public int getCoveringCount()

Returns number of covering property filters which are supported by the evaluated index. This count is no more than the remainder count. If hasAnyMatches returns false, then the covering count is zero.

Since:

1.2

getCoveringFilters

public List<? extends Filter<S>> getCoveringFilters()

Returns the covering filters which are supported by the evaluated index, which is a subset of the remainder filters.

Since:

1.2

getCoveringFilter

public Filter<S> getCoveringFilter()

Returns the composite covering filter supported by the evaluated index, or null if the covering count is zero.

Since:

1.2

getCoveringRemainderFilter

public Filter<S> getCoveringRemainderFilter()

Returns the composite remainder filter without including the covering filter. Returns null if no remainder.

Since:

1.2

isKeyMatch

public boolean isKeyMatch()

Returns true if evaluated index is unique and each of its properties has an identity match. When index and filter are used in a query, expect at most one result.

shouldReverseRange

public boolean shouldReverseRange()

Returns true if there is a range start or end match, but natural order of matching property is descending.

canMergeRemainderFilter

public boolean canMergeRemainderFilter(FilteringScore<S> other)

Returns true if the given score uses an index exactly the same as this one. The only allowed differences are in the remainder filter.

mergeRemainderFilter

public Filter<S> mergeRemainderFilter(FilteringScore<S> other)

Merges the remainder filter of this score with the one given using an 'or' operation. Call canMergeRemainderFilter first to verify if the merge makes any sense. Returns null if no remainder filter at all.

withRemainderFilter

public FilteringScore<S> withRemainderFilter(Filter<S> filter)

Returns a new FilteringScore with the remainder replaced and covering matches recalculated. Other matches are not recalculated.

Since:

1.2

toString

public String toString()

Overrides:

toString in class Object