Package io.trino.spi.block

Interface Block

All Known Subinterfaces:
ValueBlock
All Known Implementing Classes:
ArrayBlock, ByteArrayBlock, DictionaryBlock, Fixed12Block, Int128ArrayBlock, IntArrayBlock, LazyBlock, LongArrayBlock, MapBlock, RowBlock, RunLengthEncodedBlock, ShortArrayBlock, VariableWidthBlock
public sealed interface Block permits DictionaryBlock, RunLengthEncodedBlock, LazyBlock, ValueBlock

  • Method Summary

    Modifier and Type
    Method
    Description
    Block
    copyPositions(int[] positions, int offset, int length)
    Returns a block containing the specified positions.
    Block
    copyRegion(int position, int length)
    Returns a block starting at the specified position and extends for the specified length.
    Block
    copyWithAppendedNull()
    Returns a block that contains a copy of the contents of the current block, and an appended null at the end.
    OptionalInt
    fixedSizeInBytesPerPosition()
    Returns the number of bytes (in terms of getSizeInBytes()) required per position that this block contains, assuming that the number of bytes required is a known static quantity and not dependent on any particular specific position.
    default byte
    getByte(int position, int offset)
    Gets a byte at offset in the value at position.
    default List<Block>
    getChildren()
    Gets the direct child blocks of this block.
    String
    getEncodingName()
    Get the encoding for this block.
    long
    getEstimatedDataSizeForStats(int position)
    Returns the estimated in memory data size for stats of position.
    default int
    getInt(int position, int offset)
    Gets a little endian int at offset in the value at position.
    default Block
    getLoadedBlock()
    Returns a fully loaded block that assures all data is in memory.
    default long
    getLogicalSizeInBytes()
    Returns the size of the block contents, regardless of internal representation.
    default long
    getLong(int position, int offset)
    Gets a little endian long at offset in the value at position.
    default <T> T
    getObject(int position, Class<T> clazz)
    Gets an object in the value at position.
    int
    getPositionCount()
    Returns the number of positions in this block.
    default Block
    getPositions(int[] positions, int offset, int length)
    Create a new block from the current block by keeping the same elements only with respect to positions that starts at offset and has length of length.
    long
    getPositionsSizeInBytes(boolean[] positions, int selectedPositionsCount)
    Returns the size of all positions marked true in the positions array.
    Block
    getRegion(int positionOffset, int length)
    Returns a block starting at the specified position and extends for the specified length.
    long
    getRegionSizeInBytes(int position, int length)
    Returns the size of block.getRegion(position, length).
    long
    getRetainedSizeInBytes()
    Returns the retained size of this block in memory, including over-allocations.
    default short
    getShort(int position, int offset)
    Gets a little endian short at offset in the value at position.
    ValueBlock
    getSingleValueBlock(int position)
    Gets the value at the specified position as a single element block.
    long
    getSizeInBytes()
    Returns the size of this block as if it was compacted, ignoring any over-allocations and any unloaded nested blocks.
    default io.airlift.slice.Slice
    getSlice(int position, int offset, int length)
    Gets a slice at offset in the value at position.
    default int
    getSliceLength(int position)
    Gets the length of the value at the position.
    ValueBlock
    getUnderlyingValueBlock()
    Returns the underlying value block underlying this block.
    int
    getUnderlyingValuePosition(int position)
    Returns the position in the underlying value block corresponding to the specified position in this block.
    default boolean
    isLoaded()
    Returns true if block data is fully loaded into memory.
    boolean
    isNull(int position)
    Is the specified position null?
    default boolean
    mayHaveNull()
    Is it possible the block may have a null value? If false, the block cannot contain a null, but if true, the block may or may not have a null.
    void
    retainedBytesForEachPart(ObjLongConsumer<Object> consumer)
    consumer visits each of the internal data container and accepts the size for it.

  • Method Details

    • getSliceLength

      default int getSliceLength(int position)
      Gets the length of the value at the position. This method must be implemented if @{code getSlice} is implemented.

    • getByte

      default byte getByte(int position, int offset)
      Gets a byte at offset in the value at position.

    • getShort

      default short getShort(int position, int offset)
      Gets a little endian short at offset in the value at position.

    • getInt

      default int getInt(int position, int offset)
      Gets a little endian int at offset in the value at position.

    • getLong

      default long getLong(int position, int offset)
      Gets a little endian long at offset in the value at position.

    • getSlice

      default io.airlift.slice.Slice getSlice(int position, int offset, int length)
      Gets a slice at offset in the value at position.

    • getObject

      default <T> T getObject(int position, Class<T> clazz)
      Gets an object in the value at position.

    • getSingleValueBlock

      ValueBlock getSingleValueBlock(int position)
      Gets the value at the specified position as a single element block. The method must copy the data into a new block.

      This method is useful for operators that hold on to a single value without holding on to the entire block.

      Throws:
      IllegalArgumentException - if this position is not valid

    • getPositionCount

      int getPositionCount()
      Returns the number of positions in this block.

    • getSizeInBytes

      long getSizeInBytes()
      Returns the size of this block as if it was compacted, ignoring any over-allocations and any unloaded nested blocks. For example, in dictionary blocks, this only counts each dictionary entry once, rather than each time a value is referenced.

    • getLogicalSizeInBytes

      default long getLogicalSizeInBytes()
      Returns the size of the block contents, regardless of internal representation. The same logical data values should always have the same size, no matter what block type is used or how they are represented within a specific block.

      This can differ substantially from getSizeInBytes() for certain block types. For RLE, it will be N times larger. For dictionary, it will be larger based on how many times dictionary entries are reused.

    • getRegionSizeInBytes

      long getRegionSizeInBytes(int position, int length)
      Returns the size of block.getRegion(position, length). The method can be expensive. Do not use it outside an implementation of Block.

    • fixedSizeInBytesPerPosition

      OptionalInt fixedSizeInBytesPerPosition()
      Returns the number of bytes (in terms of getSizeInBytes()) required per position that this block contains, assuming that the number of bytes required is a known static quantity and not dependent on any particular specific position. This allows for some complex block wrappings to potentially avoid having to call getPositionsSizeInBytes(boolean[], int) which would require computing the specific positions selected
      Returns:
      The size in bytes, per position, if this block type does not require specific position information to compute its size

    • getPositionsSizeInBytes

      long getPositionsSizeInBytes(boolean[] positions, int selectedPositionsCount)
      Returns the size of all positions marked true in the positions array. This is equivalent to multiple calls of block.getRegionSizeInBytes(position, length) where you mark all positions for the regions first. The 'selectedPositionsCount' variable may be used to skip iterating through the positions array in case this is a fixed-width block

    • getRetainedSizeInBytes

      long getRetainedSizeInBytes()
      Returns the retained size of this block in memory, including over-allocations. This method is called from the inner most execution loop and must be fast.

    • getEstimatedDataSizeForStats

      long getEstimatedDataSizeForStats(int position)
      Returns the estimated in memory data size for stats of position. Do not use it for other purpose.

    • retainedBytesForEachPart

      void retainedBytesForEachPart(ObjLongConsumer<Object> consumer)
      consumer visits each of the internal data container and accepts the size for it. This method can be helpful in cases such as memory counting for internal data structure. Also, the method should be non-recursive, only visit the elements at the top level, and specifically should not call retainedBytesForEachPart on nested blocks consumer should be called at least once with the current block and must include the instance size of the current block

    • getEncodingName

      String getEncodingName()
      Get the encoding for this block.

    • getPositions

      default Block getPositions(int[] positions, int offset, int length)
      Create a new block from the current block by keeping the same elements only with respect to positions that starts at offset and has length of length. The implementation may return a view over the data in this block or may return a copy, and the implementation is allowed to retain the positions array for use in the view.

    • copyPositions

      Block copyPositions(int[] positions, int offset, int length)
      Returns a block containing the specified positions. Positions to copy are stored in a subarray within positions array that starts at offset and has length of length. All specified positions must be valid for this block.

      The returned block must be a compact representation of the original block.

    • getRegion

      Block getRegion(int positionOffset, int length)
      Returns a block starting at the specified position and extends for the specified length. The specified region must be entirely contained within this block.

      The region can be a view over this block. If this block is released the region block may also be released. If the region block is released this block may also be released.

    • copyRegion

      Block copyRegion(int position, int length)
      Returns a block starting at the specified position and extends for the specified length. The specified region must be entirely contained within this block.

      The region returned must be a compact representation of the original block, unless their internal representation will be exactly the same. This method is useful for operators that hold on to a range of values without holding on to the entire block.

    • mayHaveNull

      default boolean mayHaveNull()
      Is it possible the block may have a null value? If false, the block cannot contain a null, but if true, the block may or may not have a null.

    • isNull

      boolean isNull(int position)
      Is the specified position null?
      Throws:
      IllegalArgumentException - if this position is not valid. The method may return false without throwing exception when there are no nulls in the block, even if the position is invalid

    • isLoaded

      default boolean isLoaded()
      Returns true if block data is fully loaded into memory.

    • getLoadedBlock

      default Block getLoadedBlock()
      Returns a fully loaded block that assures all data is in memory. Neither the returned block nor any nested block will be a LazyBlock. The same block will be returned if neither the current block nor any nested blocks are LazyBlock,

      This allows streaming data sources to skip sections that are not accessed in a query.

    • getChildren

      default List<Block> getChildren()
      Gets the direct child blocks of this block.

    • copyWithAppendedNull

      Block copyWithAppendedNull()
      Returns a block that contains a copy of the contents of the current block, and an appended null at the end. The original block will not be modified. The purpose of this method is to leverage the contents of a block and the structure of the implementation to efficiently produce a copy of the block with a NULL element inserted - so that it can be used as a dictionary. This method is expected to be invoked on completely built Block instances i.e. not on in-progress block builders.

    • getUnderlyingValueBlock

      ValueBlock getUnderlyingValueBlock()
      Returns the underlying value block underlying this block.

    • getUnderlyingValuePosition

      int getUnderlyingValuePosition(int position)
      Returns the position in the underlying value block corresponding to the specified position in this block.