Package org.apache.druid.segment

Interface Cursor

All Known Subinterfaces:
HistoricalCursor
All Known Implementing Classes:
FrameCursor, PostJoinCursor, RowBasedCursor, ShimCursor, UnnestColumnValueSelectorCursor, UnnestDimensionCursor
public interface Cursor
Cursor is an interface for iteration over a range of data points, used during query execution. Cursors are available from CursorFactory.makeCursorHolder(CursorBuildSpec) via CursorHolder.asCursor().

A typical usage pattern might look something like this: 

   try (CursorHolder cursorHolder = adapter.makeCursorHolder(...)) {
     Cursor cursor = cursorHolder.asCursor();
     ColumnSelectorFactory factory = cursor.getColumnSelectorFactory();
     ColumnValueSelector timeSelector = factory.makeColumnValueSelector("__time");
     // ...
     while (!cursor.isDone()) {}
       long time = timeSelector.getLong();
       // do stuff with column values
       // ...
       cursor.advance();
     }
   }
QueryableIndexCursorHolder.QueryableIndexCursor is an implementation for historical segments, and IncrementalIndexCursorHolder.IncrementalIndexCursor is an implementation for IncrementalIndex.

Cursor is conceptually similar to TimeAndDimsPointer, but the latter is used for historical segment creation rather than query execution (as Cursor). If those abstractions could be collapsed (and if it is worthwhile) is yet to be determined.

  • Method Details

    • getColumnSelectorFactory

      ColumnSelectorFactory getColumnSelectorFactory()
      Get a ColumnSelectorFactory whose selectors will be backed by the row values at the current position of the cursor

    • advance

      void advance()
      Advance the cursor to the next position, checking if thread has been interrupted after advancing and possibly throwing QueryInterruptedException if so. Callers should check isDone() or isDoneOrInterrupted() before getting the next value from a selector.

    • advanceUninterruptibly

      void advanceUninterruptibly()
      Advance to the cursor to the next position. Callers should check isDone() or isDoneOrInterrupted() before getting the next value from a selector. However, underlying implementation may still check for thread interruption if advancing the cursor is a long-running operation.

    • isDone

      boolean isDone()
      Check if the current cursor position is valid, returning false if there are values to read from selectors created by getColumnSelectorFactory(). If true, any such selectors will no longer produce values.

    • isDoneOrInterrupted

      boolean isDoneOrInterrupted()
      Check if the current cursor position is valid, or if the thread has been interrupted.
      See Also:

    • reset

      void reset()
      Reset to start of cursor. Most cursor implementations are backed by immutable data, but there is generically no guarantee that advancing through a cursor again will read exactly the same data or even number of rows, since the underlying data might be mutable in some cases.