Module org.elasticsearch.compute
Package org.elasticsearch.compute.data

Class Page

java.lang.Object
org.elasticsearch.compute.data.Page
All Implemented Interfaces:
Closeable, AutoCloseable, Writeable, org.elasticsearch.core.Releasable
public final class Page extends Object implements Writeable, org.elasticsearch.core.Releasable
A page is a column-oriented data abstraction that allows data to be passed between operators in batches.

A page has a fixed number of positions (or rows), exposed via getPositionCount(). It is further composed of a number of Blocks, which represent the columnar data. The number of blocks can be retrieved via getBlockCount(), and the respective blocks can be retrieved via their index getBlock(int).

Pages are immutable and can be passed between threads.

  • Constructor Details

    • Page

      public Page(Block... blocks)
      Creates a new page with the given blocks. Every block has the same number of positions.
      Parameters:
      blocks - the blocks
      Throws:
      IllegalArgumentException - if all blocks do not have the same number of positions

    • Page

      public Page(int positionCount, Block... blocks)
      Creates a new page with the given positionCount and blocks. Assumes that every block has the same number of positions as the positionCount that's passed in - there is no validation of this.
      Parameters:
      positionCount - the block position count
      blocks - the blocks

    • Page

      public Page(BatchMetadata batchMetadata, Block... blocks)
      Create a new page with the given blocks and batch metadata.

    • Page

      public Page(StreamInput in) throws IOException
      Throws:
      IOException

  • Method Details

    • writeTo

      public void writeTo(StreamOutput out) throws IOException
      Specified by:
      writeTo in interface Writeable
      Throws:
      IOException

    • getBlock

      public <B extends Block> B getBlock(int blockIndex)
      Returns the block at the given block index.
      Parameters:
      blockIndex - the block index
      Returns:
      the block

    • appendBlock

      public Page appendBlock(Block block)
      Creates a new page, appending the given block to the existing blocks in this Page.
      Parameters:
      block - the block to append
      Returns:
      a new Page with the block appended
      Throws:
      IllegalArgumentException - if the given block does not have the same number of positions as the blocks in this Page

    • appendBlocks

      public Page appendBlocks(Block[] toAdd)
      Creates a new page, appending the given blocks to the existing blocks in this Page.
      Parameters:
      toAdd - the blocks to append
      Returns:
      a new Page with the block appended
      Throws:
      IllegalArgumentException - if one of the given blocks does not have the same number of positions as the blocks in this Page

    • appendPage

      public Page appendPage(Page toAdd)
      Creates a new page, appending the blocks of the given block to the existing blocks in this Page.
      Parameters:
      toAdd - the page to append
      Returns:
      a new Page
      Throws:
      IllegalArgumentException - if any blocks of the given page does not have the same number of positions as the blocks in this Page

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getPositionCount

      public int getPositionCount()
      Returns the number of positions (rows) in this page.
      Returns:
      the number of positions

    • getBlockCount

      public int getBlockCount()
      Returns the number of blocks in this page. Blocks can then be retrieved via getBlock(int) where channel ranges from 0 to getBlockCount.
      Returns:
      the number of blocks in this page

    • batchMetadata

      @Nullable public BatchMetadata batchMetadata()

    • withBatchMetadata

      public Page withBatchMetadata(BatchMetadata metadata)
      Creates a new page with the same blocks but with the given batch metadata. The blocks are shared (ref count incremented) with the original page.

    • isBatchMarkerOnly

      public boolean isBatchMarkerOnly()
      Check if this page is a batch marker (empty page with isLastPageInBatch=true). Marker pages are used to signal batch completion for batches that produce no output.

    • createBatchMarkerPage

      public static Page createBatchMarkerPage(long batchId, int pageIndexInBatch)
      Creates an empty marker page for batch completion. A marker page is an empty page with isLastPageInBatch=true.

    • ramBytesUsedByBlocks

      public long ramBytesUsedByBlocks()

    • releaseBlocks

      public void releaseBlocks()
      Release all blocks in this page, decrementing any breakers accounting for these blocks.

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Specified by:
      close in interface org.elasticsearch.core.Releasable

    • allowPassingToDifferentDriver

      public void allowPassingToDifferentDriver()
      Before passing a Page to another Driver, it is necessary to switch the owning block factories of its Blocks to their parents, which are associated with the global circuit breaker. This ensures that when the new driver releases this Page, it returns memory directly to the parent block factory instead of the local block factory. This is important because the local block factory is not thread safe and doesn't support simultaneous access by more than one thread.

    • shallowCopy

      public Page shallowCopy()
      Makes a shallow copy of the Page, RefCounted.incRef()ing all of the Blocks.

    • projectBlocks

      public Page projectBlocks(int[] blockMapping)
      Returns a new page with blocks in the containing Blocks shifted around or removed. The new Page will have as many blocks as the length of the provided array. Those blocks will be set to the block at the position of the value of each entry in the parameter.

    • filter

      public Page filter(boolean mayContainDuplicates, int... positions)
      Creates a new page that only exposes the positions provided.
      Parameters:
      mayContainDuplicates - may the positions array contain duplicate positions?
      positions - the positions to retain
      Returns:
      a filtered page

    • slice

      public Page slice(int beginInclusive, int endExclusive)
      Return a subset of this Page from position beginInclusive to position endExclusive. This will always return a new Page but will skip performing any copies if the slice is a noop.

      NOTE: Implementations will not try to optimize zero length slices as we expect them to be rare.