RowIndexEntry (apache-cassandra API)
Date: 2018-02-14

org.apache.cassandra.db

## Class RowIndexEntry<T>

- java.lang.Object
- - org.apache.cassandra.db.RowIndexEntry<T>

- All Implemented Interfaces:
    IMeasurableMemory

      public class RowIndexEntry<T>
      extends java.lang.Object
      implements IMeasurableMemory

  Binary format of `RowIndexEntry` is defined as follows: `(long) position (64 bit long, vint encoded) (int) serialized size of data that follows (32 bit int, vint encoded) -- following for indexed entries only (so serialized size > 0) (int) DeletionTime.localDeletionTime (long) DeletionTime.markedForDeletionAt (int) number of IndexInfo objects (32 bit int, vint encoded) (*) serialized IndexInfo objects, see below (*) offsets of serialized IndexInfo objects, since version "ma" (3.0) Each IndexInfo object's offset is relative to the first IndexInfo object.`

  See `IndexInfo` for a description of the serialized format.

  For each partition, the layout of the index file looks like this:

  1. partition key - prefixed with `short` length
  2. serialized `RowIndexEntry` objects

  Generally, we distinguish between index entries that have index samples (list of `IndexInfo` objects) and those who don't. For each portion of data for a single partition in the data file, an index sample is created. The size of that portion is defined by `Config.column_index_size_in_kb`.

  Index entries with less than 2 index samples, will just store the position in the data file.

  Note: legacy sstables for index entries are those sstable formats that do not have an offsets table to index samples (`IndexInfo` objects). These are those sstables created on Cassandra versions earlier than 3.0.

  For index entries with index samples we store the index samples (`IndexInfo` objects). The bigger the partition, the more index samples are created. Since a huge amount of index samples will "pollute" the heap and cause huge GC pressure, Cassandra 3.6 (CASSANDRA-11206) distinguishes between index entries with an "acceptable" amount of index samples per partition and those with an "enormous" amount of index samples. The barrier is controlled by the configuration parameter `Config.column_index_cache_size_in_kb`. Index entries with a total serialized size of index samples up to `column_index_cache_size_in_kb` will be held in an array. Index entries exceeding that value will always be accessed from disk.

  This results in these classes:

  - `RowIndexEntry` just stores the offset in the data file.
  - `IndexedEntry` is for index entries with index samples and used for both current and legacy sstables, which do not exceed `Config.column_index_cache_size_in_kb`.
  - `ShallowIndexedEntry` is for index entries with index samples that exceed `Config.column_index_cache_size_in_kb` for sstables with an offset table to the index samples.
  - `LegacyShallowIndexedEntry` is for index entries with index samples that exceed `Config.column_index_cache_size_in_kb` but for legacy sstables.

  Since access to index samples on disk (obviously) requires some file reader, that functionality is encapsulated in implementations of `RowIndexEntry.IndexInfoRetriever`. There is an implementation to access index samples of legacy sstables (without the offsets table), an implementation of access sstables with an offsets table.

  Until now (Cassandra 3.x), we still support reading from legacy sstables - i.e. sstables created by Cassandra < 3.0 (see `BigFormat`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `RowIndexEntry.IndexInfoRetriever` Base class to access `IndexInfo` objects.
    `static interface` | `RowIndexEntry.IndexSerializer<T>`
    `static class` | `RowIndexEntry.Serializer`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `long` | `position`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RowIndexEntry(long position)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `columnsIndexCount()`
    `static RowIndexEntry<IndexInfo>` | `create(long dataFilePosition, long indexFilePosition, DeletionTime deletionTime, long headerLength, int columnIndexCount, int indexedPartSize, java.util.List<IndexInfo> indexSamples, int[] offsets, ISerializer<IndexInfo> idxInfoSerializer)`
    `DeletionTime` | `deletionTime()`
    `long` | `headerLength()` The length of the row header (partition key, partition deletion and static row).
    `boolean` | `indexOnHeap()`
    `boolean` | `isIndexed()`
    `RowIndexEntry.IndexInfoRetriever` | `openWithIndex(FileHandle indexFile)`
    `void` | `serialize(DataOutputPlus out, IndexInfo.Serializer idxInfoSerializer, java.nio.ByteBuffer indexInfo)`
    `void` | `serializeForCache(DataOutputPlus out)`
    `long` | `unsharedHeapSize()`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### position

          public final long position

  - ### Constructor Detail

    - #### RowIndexEntry

          public RowIndexEntry(long position)

  - ### Method Detail

    - #### isIndexed

          public boolean isIndexed()

      Returns:
        true if this index entry contains the row-level tombstone and column summary. Otherwise, caller should fetch these from the row header.

    - #### indexOnHeap

          public boolean indexOnHeap()

    - #### deletionTime

          public DeletionTime deletionTime()

    - #### headerLength

          public long headerLength()

      The length of the row header (partition key, partition deletion and static row). This value is only provided for indexed entries and this method will throw `UnsupportedOperationException` if `!isIndexed()`.

    - #### columnsIndexCount

          public int columnsIndexCount()

    - #### unsharedHeapSize

          public long unsharedHeapSize()

      Specified by:
        `unsharedHeapSize` in interface `IMeasurableMemory`
      Returns:
        the amount of on-heap memory retained by the object that might be reclaimed if the object were reclaimed, i.e. it should try to exclude globally cached data where possible, or counting portions of arrays that are referenced by the object but used by other objects only (e.g. slabbed byte-buffers), etc.

    - #### create

          public static RowIndexEntry<IndexInfo> create(long dataFilePosition,
                                                        long indexFilePosition,
                                                        DeletionTime deletionTime,
                                                        long headerLength,
                                                        int columnIndexCount,
                                                        int indexedPartSize,
                                                        java.util.List<IndexInfo> indexSamples,
                                                        int[] offsets,
                                                        ISerializer<IndexInfo> idxInfoSerializer)

      Parameters:
        `dataFilePosition` - position of the partition in the `Component.Type.DATA` file
        `indexFilePosition` - position in the `Component.Type.PRIMARY_INDEX` of the `RowIndexEntry`
        `deletionTime` - deletion time of `RowIndexEntry`
        `headerLength` - deletion time of `RowIndexEntry`
        `columnIndexCount` - number of `IndexInfo` entries in the `RowIndexEntry`
        `indexedPartSize` - serialized size of all serialized `IndexInfo` objects and their offsets
        `indexSamples` - list with IndexInfo offsets (if total serialized size is less than `Config.column_index_cache_size_in_kb`
        `offsets` - offsets of IndexInfo offsets
        `idxInfoSerializer` - the `IndexInfo` serializer

    - #### openWithIndex

          public RowIndexEntry.IndexInfoRetriever openWithIndex(FileHandle indexFile)

    - #### serialize

          public void serialize(DataOutputPlus out,
                                IndexInfo.Serializer idxInfoSerializer,
                                java.nio.ByteBuffer indexInfo)
                         throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### serializeForCache

          public void serializeForCache(DataOutputPlus out)
                                 throws java.io.IOException

      Throws:
        `java.io.IOException`

Copyright © 2018 The Apache Software Foundation