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

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

public class OrderingScore<S extends Storable>
extends Object

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

An index matches a desired ordering if the arrangement of properties matches. Not all properties of the index need to be used, however. Also, gaps in the arrangement are allowed if a property identity filter matches. A property identity filter is of the form "a = ?".

An OrderingScore measures the number of ordering 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 a post-sort operation to achieve the desired results.

In general, an OrderingScore is better than another if it has more matched properties and fewer remainder properties. Index clustering, property count, and natural order is also considered.

Author:

Brian S O'Neill

See Also:

FilteringScore, CompositeScore

Method Summary

boolean	canMergeRemainderOrdering(OrderingScore<S> other) Returns true if the given score uses an index exactly the same as this one.
static <S extends Storable> OrderingScore<S>	evaluate(OrderedProperty<S>[] indexProperties, boolean unique, boolean clustered, Filter<S> filter, OrderingList<S> ordering) Evaluates the given index properties for its ordering capabilities against the given filter and order-by properties.
static <S extends Storable> OrderingScore<S>	evaluate(StorableIndex<S> index, Filter<S> filter, OrderingList<S> ordering) Evaluates the given index for its ordering capabilities against the given filter and order-by properties.
static Comparator<OrderingScore<?>>	fullComparator() Returns a comparator which determines which OrderingScores are better.
OrderingList<S>	getFreeOrdering() Returns potential ordering properties that the evaluated index can handle, if arranged to immediately follow the handled orderings.
int	getHandledCount() Returns the number of desired orderings the evaluated index supports.
OrderingList<S>	getHandledOrdering() Returns the ordering properties that the evaluated index supports.
int	getIndexPropertyCount() Returns the amount of properties in the evaluated index.
int	getRemainderCount() Returns the number of desired orderings the evaluated index does not support.
OrderingList<S>	getRemainderOrdering() Returns the ordering properties that the evaluated index does not support.
OrderingList<S>	getUnusedOrdering() Returns unused ordering properties of the evaluated index because they were filtered out.
boolean	isIndexClustered() Returns true if evaluated index is clustered.
OrderingList<S>	mergeRemainderOrdering(OrderingScore<S> other) Merges the remainder orderings of this score with the one given.
boolean	shouldReverseOrder() Returns true if evaluated index must be iterated in reverse to achieve the desired ordering.
String	toString()
OrderingScore<S>	withRemainderOrdering(OrderingList<S> ordering) Returns a new OrderingScore with the remainder replaced.

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> OrderingScore<S> evaluate(StorableIndex<S> index,
                                                             Filter<S> filter,
                                                             OrderingList<S> ordering)

Evaluates the given index for its ordering capabilities against the given filter and order-by properties.

Parameters:

index - index to evaluate

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

ordering - optional properties which define desired ordering

Throws:

IllegalArgumentException - if index is null or filter is not supported

evaluate

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

Evaluates the given index properties for its ordering capabilities against the given filter and order-by properties.

Parameters:

indexProperties - index properties to evaluate

unique - true if index is unique

clustered - true if index is clustered

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

ordering - optional properties which define desired ordering

Throws:

IllegalArgumentException - if index is null or filter is not supported

fullComparator

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

Returns a comparator which determines which OrderingScores are better. 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.

getIndexPropertyCount

public int getIndexPropertyCount()

Returns the amount of properties in the evaluated index.

getHandledCount

public int getHandledCount()

Returns the number of desired orderings the evaluated index supports. The number of orderings is reduced to eliminate redundancies.

getHandledOrdering

public OrderingList<S> getHandledOrdering()

Returns the ordering properties that the evaluated index supports. The list of orderings is reduced to eliminate redundancies. If any handled ordering properties originally had an unspecified direction, the correct direction is specified in this list.

Returns:

handled orderings, never null

getRemainderCount

public int getRemainderCount()

Returns the number of desired orderings the evaluated index does not support. The number of orderings is reduced to eliminate redundancies. When the remainder count is non-zero, a query plan which uses the evaluated index must perform a sort.

getRemainderOrdering

public OrderingList<S> getRemainderOrdering()

Returns the ordering properties that the evaluated index does not support. The list of orderings is reduced to eliminate redundancies.

Returns:

remainder orderings, never null

shouldReverseOrder

public boolean shouldReverseOrder()

Returns true if evaluated index must be iterated in reverse to achieve the desired ordering.

getFreeOrdering

public OrderingList<S> getFreeOrdering()

Returns potential ordering properties that the evaluated index can handle, if arranged to immediately follow the handled orderings. The direction of any free orderings may be UNSPECIFIED, which indicates that specific order is not relevant.

Returns:

free orderings, never null

getUnusedOrdering

public OrderingList<S> getUnusedOrdering()

Returns unused ordering properties of the evaluated index because they were filtered out. The direction of each unused ordering is UNSPECIFIED because specific order is not relevant.

Returns:

unused orderings, never null

canMergeRemainderOrdering

public boolean canMergeRemainderOrdering(OrderingScore<S> other)

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

mergeRemainderOrdering

public OrderingList<S> mergeRemainderOrdering(OrderingScore<S> other)

Merges the remainder orderings of this score with the one given. Call canMergeRemainderOrdering first to verify if the merge makes any sense.

withRemainderOrdering

public OrderingScore<S> withRemainderOrdering(OrderingList<S> ordering)

Returns a new OrderingScore with the remainder replaced. Handled count is not recalculated.

Since:

1.2

toString

public String toString()

Overrides:

toString in class Object