Package org.apache.hadoop.hbase.client

Class Result

java.lang.Object
org.apache.hadoop.hbase.client.Result
All Implemented Interfaces:
CellScannable, CellScanner, ExtendedCellScannable, ExtendedCellScanner
@Public public class Result extends Object implements ExtendedCellScannable, ExtendedCellScanner
Single row result of a Get or Scan query.

This class is NOT THREAD SAFE.

Convenience methods are available that return various Map structures and values directly.

To get a complete mapping of all cells in the Result, which can include multiple families and multiple versions, use getMap().

To get a mapping of each family to its columns (qualifiers and values), including only the latest version of each, use getNoVersionMap(). To get a mapping of qualifiers to latest values for an individual family use getFamilyMap(byte[]).

To get the latest value for a specific family and qualifier use getValue(byte[], byte[]). A Result is backed by an array of Cell objects, each representing an HBase cell defined by the row, family, qualifier, timestamp, and value.

The underlying Cell objects can be accessed through the method listCells(). This will create a List from the internal Cell []. Better is to exploit the fact that a new Result instance is a primed CellScanner; just call advance() and current() to iterate over Cells as you would any CellScanner. Call cellScanner() to reset should you need to iterate the same Result over again (CellScanners are one-shot). If you need to overwrite a Result with another Result instance -- as in the old 'mapred' RecordReader next invocations -- then create an empty Result with the null constructor and in then use copyFrom(Result)

  • Field Details

  • Constructor Details

    • Result

      public Result()
      Creates an empty Result w/ no KeyValue payload; returns null if you call rawCells(). Use this to represent no results if null won't do or in old 'mapred' as opposed to 'mapreduce' package MapReduce where you need to overwrite a Result instance with a copyFrom(Result) call.

    • Result

      private Result(boolean readonly)
      Allows to construct special purpose immutable Result objects, such as EMPTY_RESULT.
      Parameters:
      readonly - whether this Result instance is readonly

    • Result

      private Result(Cursor cursor)

    • Result

      private Result(ExtendedCell[] cells, Boolean exists, boolean stale, boolean mayHaveMoreCellsInRow)
      Private ctor. Use create(Cell[]).

  • Method Details

    • create

      public static Result create(List<? extends Cell> cells)
      Instantiate a Result with the specified List of KeyValues.
      Note: You must ensure that the keyvalues are already sorted.
      Parameters:
      cells - List of cells

    • create

      public static Result create(List<? extends Cell> cells, Boolean exists)

    • create

      public static Result create(List<? extends Cell> cells, Boolean exists, boolean stale)

    • create

      public static Result create(List<? extends Cell> cells, Boolean exists, boolean stale, boolean mayHaveMoreCellsInRow)

    • create

      public static Result create(Cell[] cells)
      Instantiate a Result with the specified array of KeyValues.
      Note: You must ensure that the keyvalues are already sorted.
      Parameters:
      cells - array of cells

    • create

      public static Result create(Cell[] cells, Boolean exists, boolean stale)

    • create

      public static Result create(Cell[] cells, Boolean exists, boolean stale, boolean mayHaveMoreCellsInRow)

    • create

      static Result create(ExtendedCell[] cells)

    • create

      static Result create(ExtendedCell[] cells, Boolean exists, boolean stale)

    • create

      static Result create(ExtendedCell[] cells, Boolean exists, boolean stale, boolean mayHaveMoreCellsInRow)

    • createCursorResult

      public static Result createCursorResult(Cursor cursor)

    • getRow

      public byte[] getRow()
      Method for retrieving the row key that corresponds to the row from which this Result was created.

    • rawCells

      public Cell[] rawCells()
      Return the array of Cells backing this Result instance. The array is sorted from smallest -> largest using the CellComparator. The array only contains what your Get or Scan specifies and no more. For example if you request column "A" 1 version you will have at most 1 Cell in the array. If you request column "A" with 2 version you will have at most 2 Cells, with the first one being the newer timestamp and the second being the older timestamp (this is the sort order defined by CellComparator). If columns don't exist, they won't be present in the result. Therefore if you ask for 1 version all columns, it is safe to iterate over this array and expect to see 1 Cell for each column and no more. This API is faster than using getFamilyMap() and getMap()
      Returns:
      array of Cells; can be null if nothing in the result

    • rawExtendedCells

      ExtendedCell[] rawExtendedCells()

    • listCells

      public List<Cell> listCells()
      Create a sorted list of the Cell's in this result. Since HBase 0.20.5 this is equivalent to raw().
      Returns:
      sorted List of Cells; can be null if no cells in the result

    • getColumnCells

      public List<Cell> getColumnCells(byte[] family, byte[] qualifier)
      Return the Cells for the specific column. The Cells are sorted in the CellComparator order. That implies the first entry in the list is the most recent column. If the query (Scan or Get) only requested 1 version the list will contain at most 1 entry. If the column did not exist in the result set (either the column does not exist or the column was not selected in the query) the list will be empty. Also see getColumnLatest which returns just a Cell
      Parameters:
      family - the family
      Returns:
      a list of Cells for this column or empty list if the column did not exist in the result set

    • notNullBytes

      private byte[] notNullBytes(byte[] bytes)

    • binarySearch

      private int binarySearch(Cell[] kvs, byte[] family, byte[] qualifier)

    • binarySearch

      private int binarySearch(Cell[] kvs, byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength)
      Searches for the latest value for the specified column.
      Parameters:
      kvs - the array to search
      family - family name
      foffset - family offset
      flength - family length
      qualifier - column qualifier
      qoffset - qualifier offset
      qlength - qualifier length
      Returns:
      the index where the value was found, or -1 otherwise

    • getColumnLatestCell

      public Cell getColumnLatestCell(byte[] family, byte[] qualifier)
      The Cell for the most recent timestamp for a given column.
      Returns:
      the Cell for the column, or null if no value exists in the row or none have been selected in the query (Get/Scan)

    • getColumnLatestCell

      public Cell getColumnLatestCell(byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength)
      The Cell for the most recent timestamp for a given column.
      Parameters:
      family - family name
      foffset - family offset
      flength - family length
      qualifier - column qualifier
      qoffset - qualifier offset
      qlength - qualifier length
      Returns:
      the Cell for the column, or null if no value exists in the row or none have been selected in the query (Get/Scan)

    • getValue

      public byte[] getValue(byte[] family, byte[] qualifier)
      Get the latest version of the specified column. Note: this call clones the value content of the hosting Cell. See getValueAsByteBuffer(byte[], byte[]), etc., or listCells() if you would avoid the cloning.
      Parameters:
      family - family name
      qualifier - column qualifier
      Returns:
      value of latest version of column, null if none found

    • getValueAsByteBuffer

      public ByteBuffer getValueAsByteBuffer(byte[] family, byte[] qualifier)
      Returns the value wrapped in a new ByteBuffer.
      Parameters:
      family - family name
      qualifier - column qualifier
      Returns:
      the latest version of the column, or null if none found

    • getValueAsByteBuffer

      public ByteBuffer getValueAsByteBuffer(byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength)
      Returns the value wrapped in a new ByteBuffer.
      Parameters:
      family - family name
      foffset - family offset
      flength - family length
      qualifier - column qualifier
      qoffset - qualifier offset
      qlength - qualifier length
      Returns:
      the latest version of the column, or null if none found

    • loadValue

      public boolean loadValue(byte[] family, byte[] qualifier, ByteBuffer dst) throws BufferOverflowException
      Loads the latest version of the specified column into the provided ByteBuffer.

      Does not clear or flip the buffer.

      Parameters:
      family - family name
      qualifier - column qualifier
      dst - the buffer where to write the value
      Returns:
      true if a value was found, false otherwise
      Throws:
      BufferOverflowException - there is insufficient space remaining in the buffer

    • loadValue

      public boolean loadValue(byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength, ByteBuffer dst) throws BufferOverflowException
      Loads the latest version of the specified column into the provided ByteBuffer.

      Does not clear or flip the buffer.

      Parameters:
      family - family name
      foffset - family offset
      flength - family length
      qualifier - column qualifier
      qoffset - qualifier offset
      qlength - qualifier length
      dst - the buffer where to write the value
      Returns:
      true if a value was found, false otherwise
      Throws:
      BufferOverflowException - there is insufficient space remaining in the buffer

    • containsNonEmptyColumn

      public boolean containsNonEmptyColumn(byte[] family, byte[] qualifier)
      Checks if the specified column contains a non-empty value (not a zero-length byte array).
      Parameters:
      family - family name
      qualifier - column qualifier
      Returns:
      whether or not a latest value exists and is not empty

    • containsNonEmptyColumn

      public boolean containsNonEmptyColumn(byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength)
      Checks if the specified column contains a non-empty value (not a zero-length byte array).
      Parameters:
      family - family name
      foffset - family offset
      flength - family length
      qualifier - column qualifier
      qoffset - qualifier offset
      qlength - qualifier length
      Returns:
      whether or not a latest value exists and is not empty

    • containsEmptyColumn

      public boolean containsEmptyColumn(byte[] family, byte[] qualifier)
      Checks if the specified column contains an empty value (a zero-length byte array).
      Parameters:
      family - family name
      qualifier - column qualifier
      Returns:
      whether or not a latest value exists and is empty

    • containsEmptyColumn

      public boolean containsEmptyColumn(byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength)
      Checks if the specified column contains an empty value (a zero-length byte array).
      Parameters:
      family - family name
      foffset - family offset
      flength - family length
      qualifier - column qualifier
      qoffset - qualifier offset
      qlength - qualifier length
      Returns:
      whether or not a latest value exists and is empty

    • containsColumn

      public boolean containsColumn(byte[] family, byte[] qualifier)
      Checks for existence of a value for the specified column (empty or not).
      Parameters:
      family - family name
      qualifier - column qualifier
      Returns:
      true if at least one value exists in the result, false if not

    • containsColumn

      public boolean containsColumn(byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength)
      Checks for existence of a value for the specified column (empty or not).
      Parameters:
      family - family name
      foffset - family offset
      flength - family length
      qualifier - column qualifier
      qoffset - qualifier offset
      qlength - qualifier length
      Returns:
      true if at least one value exists in the result, false if not

    • getMap

      public NavigableMap<byte[],NavigableMap<byte[],NavigableMap<Long,byte[]>>> getMap()
      Map of families to all versions of its qualifiers and values.

      Returns a three level Map of the form: Map&family,Map<qualifier,Map<timestamp,value>>>

      Note: All other map returning methods make use of this map internally.

      Returns:
      map from families to qualifiers to versions

    • getNoVersionMap

      public NavigableMap<byte[],NavigableMap<byte[],byte[]>> getNoVersionMap()
      Map of families to their most recent qualifiers and values.

      Returns a two level Map of the form: Map&family,Map<qualifier,value>>

      The most recent version of each qualifier will be used.

      Returns:
      map from families to qualifiers and value

    • getFamilyMap

      public NavigableMap<byte[],byte[]> getFamilyMap(byte[] family)
      Map of qualifiers to values.

      Returns a Map of the form: Map<qualifier,value>

      Parameters:
      family - column family to get
      Returns:
      map of qualifiers to values

    • value

      public byte[] value()
      Returns the value of the first column in the Result.
      Returns:
      value of the first column

    • isEmpty

      public boolean isEmpty()
      Check if the underlying Cell [] is empty or not
      Returns:
      true if empty

    • size

      public int size()
      Returns the size of the underlying Cell []

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • compareResults

      public static void compareResults(Result res1, Result res2) throws Exception
      Does a deep comparison of two Results, down to the byte arrays.
      Parameters:
      res1 - first result to compare
      res2 - second result to compare
      Throws:
      Exception - Every difference is throwing an exception

    • compareResults

      public static void compareResults(Result res1, Result res2, boolean verbose) throws Exception
      Does a deep comparison of two Results, down to the byte arrays.
      Parameters:
      res1 - first result to compare
      res2 - second result to compare
      verbose - includes string representation for all cells in the exception if true; otherwise include rowkey only
      Throws:
      Exception - Every difference is throwing an exception

    • createCompleteResult

      public static Result createCompleteResult(Iterable<Result> partialResults) throws IOException
      Forms a single result from the partial results in the partialResults list. This method is useful for reconstructing partial results on the client side.
      Parameters:
      partialResults - list of partial results
      Returns:
      The complete result that is formed by combining all of the partial results together
      Throws:
      IOException - A complete result cannot be formed because the results in the partial list come from different rows

    • getTotalSizeOfCells

      public static long getTotalSizeOfCells(Result result)
      Get total size of raw cells
      Returns:
      Total size.

    • copyFrom

      public void copyFrom(Result other)
      Copy another Result into this one. Needed for the old Mapred framework
      Throws:
      UnsupportedOperationException - if invoked on instance of EMPTY_RESULT (which is supposed to be immutable).

    • cellScanner

      public ExtendedCellScanner cellScanner()
      For client users: You should only use the return value as a CellScanner, ExtendedCellScanner is marked as IA.Private which means there is no guarantee about its API stability.
      Specified by:
      cellScanner in interface CellScannable
      Specified by:
      cellScanner in interface ExtendedCellScannable

    • current

      public ExtendedCell current()
      For client users: You should only use the return value as a Cell, ExtendedCell is marked as IA.Private which means there is no guarantee about its API stability.
      Specified by:
      current in interface CellScanner
      Specified by:
      current in interface ExtendedCellScanner

    • advance

      public boolean advance()
      Description copied from interface: CellScanner
      Advance the scanner 1 cell.
      Specified by:
      advance in interface CellScanner
      Returns:
      true if the next cell is found and CellScanner.current() will return a valid Cell

    • getExists

      public Boolean getExists()

    • setExists

      public void setExists(Boolean exists)

    • isStale

      public boolean isStale()
      Whether or not the results are coming from possibly stale data. Stale results might be returned if Consistency is not STRONG for the query.
      Returns:
      Whether or not the results are coming from possibly stale data.

    • mayHaveMoreCellsInRow

      public boolean mayHaveMoreCellsInRow()
      For scanning large rows, the RS may choose to return the cells chunk by chunk to prevent OOM or timeout. This flag is used to tell you if the current Result is the last one of the current row. False means this Result is the last one. True means there MAY be more cells belonging to the current row. If you don't use Scan.setAllowPartialResults(boolean) or Scan.setBatch(int), this method will always return false because the Result must contains all cells in one Row.

    • setStatistics

      @Private public void setStatistics(RegionLoadStats loadStats)
      Set load information about the region to the information about the result
      Parameters:
      loadStats - statistics about the current region from which this was returned

    • getStats

      public RegionLoadStats getStats()
      Returns the associated statistics about the region from which this was returned. Can be null if stats are disabled.

    • checkReadonly

      private void checkReadonly()
      All methods modifying state of Result object must call this method to ensure that special purpose immutable Results can't be accidentally modified.

    • isCursor

      public boolean isCursor()
      Return true if this Result is a cursor to tell users where the server has scanned. In this Result the only meaningful method is getCursor(). while (r = scanner.next() && r != null) { if(r.isCursor()){ // scanning is not end, it is a cursor, save its row key and close scanner if you want, or // just continue the loop to call next(). } else { // just like before } } // scanning is end Scan.setNeedCursorResult(boolean) Cursor getCursor()

    • getCursor

      public Cursor getCursor()
      Return the cursor if this Result is a cursor result. Scan.setNeedCursorResult(boolean) Cursor isCursor()