Package com.apple.foundationdb.record.provider.foundationdb.indexes

Class RankIndexMaintainer

  • @API(MAINTAINED)
public class RankIndexMaintainer
extends StandardIndexMaintainer
    An index maintainer for keeping a RankedSet of record field values.

    A ranked-set is a persistent skip-list that efficiently implements two complementary functions:

    • rank: Given a value, where would this value be in an ordered enumeration of all values in the set?
    • select: Given an ordinal position in the ordered enumeration of values, what is the specific value at that position?

    Any number of fields in a RANK index can optionally separate records into non-overlapping groups. Each group, determined by the values of those fields, has separate ranking and therefore a separate ranked-set.

    Physical layout: a RANK index maintains two subspaces in the database:

    • primary subspace: an ordinary B-tree index on [group, ..., score, ...].
    • secondary subspace: a ranked-set per group, that is, with any group key as a prefix.

    The overhead of the secondary subspace is one key-value pair for each value at the finest level (0) of the ranked-set skip-list, plus additional key-value pairs at coarser levels, with a probability of 1/16ⁿ for level n.

    Store operations: The basic rank and select functions are exposed by the index as aggregate functions, that is, as operations on the whole record store rather than specific records.

    • FunctionNames.RANK_FOR_SCORE: the rank operation; given a tuple of group keys and score values, return the ordinal position of that score
    • FunctionNames.SCORE_FOR_RANK: the select operation; given a tuple of group keys and a rank ordinal, return the score at that position or an error if out of range
    • FunctionNames.SCORE_FOR_RANK_ELSE_SKIP: similarly, given a tuple of group keys and a rank ordinal, return the score at that position, or a special value if out of range

    Because the ranked-set skip-list keeps a count of entries, the index can also perform the FunctionNames.COUNT_DISTINCT aggregate function, and, equivalently when the index does not permit ties, that is, when the index is declared unique, the more basic FunctionNames.COUNT aggregate function.

    Record operations: Given a record, FunctionNames.RANK record function returns the rank of that record according to the index. This is done by evaluating the same key expressions used by index maintenance against the record to determine any group keys and score values. These are then given to the ranked-set's rank function.

    Scan operations: The index can be used to return a range of records within a group in rank order.

    This is done as follows:

    1. Take the group keys from the common prefix of the range endpoints to determine which ranked-set to use.
    2. Convert each of the rank endpoints of the range into score endpoints using select.
    3. Add back the group prefixes to those scores.
    4. Return a BY_VALUE scan between those grouped score endpoints.