org.apache.hadoop.hbase.client

Class Result

java.lang.Object

org.apache.hadoop.hbase.client.Result

All Implemented Interfaces:

CellScannable, CellScanner

@InterfaceAudience.Public
 @InterfaceStability.Stable
public class Result
extends Object
implements CellScannable, CellScanner

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 Summary

Fields

Modifier and Type	Field and Description
static Result	EMPTY_RESULT

Constructor Summary

Constructors

Constructor and Description
Result() Creates an empty Result w/ no KeyValue payload; returns null if you call rawCells().
Result(KeyValue[] cells) Deprecated. Use create(List) instead.
Result(List<KeyValue> kvs) Deprecated. Use create(List) instead.

Method Summary

Modifier and Type	Method and Description
void	addResults(ClientProtos.RegionLoadStats loadStats) Deprecated. use setStatistics(ClientProtos.RegionLoadStats) instead
boolean	advance() Advance the scanner 1 cell.
protected int	binarySearch(Cell[] kvs, byte[] family, byte[] qualifier)
protected 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.
CellScanner	cellScanner()
static void	compareResults(Result res1, Result res2) Does a deep comparison of two Results, down to the byte arrays.
boolean	containsColumn(byte[] family, byte[] qualifier) Checks for existence of a value for the specified column (empty or not).
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).
boolean	containsEmptyColumn(byte[] family, byte[] qualifier) Checks if the specified column contains an empty value (a zero-length byte array).
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).
boolean	containsNonEmptyColumn(byte[] family, byte[] qualifier) Checks if the specified column contains a non-empty value (not a zero-length byte array).
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).
void	copyFrom(Result other) Copy another Result into this one.
static Result	create(Cell[] cells) Instantiate a Result with the specified array of KeyValues.
static Result	create(Cell[] cells, Boolean exists, boolean stale)
static Result	create(Cell[] cells, Boolean exists, boolean stale, boolean partial)
static Result	create(List<Cell> cells) Instantiate a Result with the specified List of KeyValues.
static Result	create(List<Cell> cells, Boolean exists)
static Result	create(List<Cell> cells, Boolean exists, boolean stale)
static Result	create(List<Cell> cells, Boolean exists, boolean stale, boolean partial)
static Result	createCompleteResult(List<Result> partialResults) Forms a single result from the partial results in the partialResults list.
Cell	current()
List<KeyValue>	getColumn(byte[] family, byte[] qualifier) Deprecated. Use getColumnCells(byte[], byte[]) instead.
List<Cell>	getColumnCells(byte[] family, byte[] qualifier) Return the Cells for the specific column.
KeyValue	getColumnLatest(byte[] family, byte[] qualifier) Deprecated. Use getColumnLatestCell(byte[], byte[]) instead.
KeyValue	getColumnLatest(byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength) Deprecated. Use getColumnLatestCell(byte[], int, int, byte[], int, int) instead.
Cell	getColumnLatestCell(byte[] family, byte[] qualifier) The Cell for the most recent timestamp for a given column.
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.
Boolean	getExists()
NavigableMap<byte[],byte[]>	getFamilyMap(byte[] family) Map of qualifiers to values.
NavigableMap<byte[],NavigableMap<byte[],NavigableMap<Long,byte[]>>>	getMap() Map of families to all versions of its qualifiers and values.
NavigableMap<byte[],NavigableMap<byte[],byte[]>>	getNoVersionMap() Map of families to their most recent qualifiers and values.
byte[]	getRow() Method for retrieving the row key that corresponds to the row from which this Result was created.
ClientProtos.RegionLoadStats	getStats()
static long	getTotalSizeOfCells(Result result) Get total size of raw cells
byte[]	getValue(byte[] family, byte[] qualifier) Get the latest version of the specified column.
ByteBuffer	getValueAsByteBuffer(byte[] family, byte[] qualifier) Returns the value wrapped in a new ByteBuffer.
ByteBuffer	getValueAsByteBuffer(byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength) Returns the value wrapped in a new ByteBuffer.
boolean	isEmpty() Check if the underlying Cell [] is empty or not
boolean	isPartial() Whether or not the result is a partial result.
boolean	isStale() Whether or not the results are coming from possibly stale data.
List<KeyValue>	list() Deprecated. as of 0.96, use listCells()
List<Cell>	listCells() Create a sorted list of the Cell's in this result.
boolean	loadValue(byte[] family, byte[] qualifier, ByteBuffer dst) Loads the latest version of the specified column into the provided ByteBuffer.
boolean	loadValue(byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength, ByteBuffer dst) Loads the latest version of the specified column into the provided ByteBuffer.
KeyValue[]	raw() Deprecated. as of 0.96, use rawCells()
Cell[]	rawCells() Return the array of Cells backing this Result instance.
void	setExists(Boolean exists)
void	setStatistics(ClientProtos.RegionLoadStats loadStats) Set load information about the region to the information about the result
int	size()
String	toString()
byte[]	value() Returns the value of the first column in the Result.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_RESULT

public static final Result EMPTY_RESULT

Constructor Detail

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 oppposed to 'mapreduce' package MapReduce where you need to overwrite a Result instance with a copyFrom(Result) call.

Result

@Deprecated
public Result(KeyValue[] cells)

Deprecated. Use create(List) instead.

Result

@Deprecated
public Result(List<KeyValue> kvs)

Deprecated. Use create(List) instead.

Method Detail

create

public static Result create(List<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<Cell> cells,
                            Boolean exists)

create

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

create

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

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 partial)

getRow

public byte[] getRow()

Method for retrieving the row key that corresponds to the row from which this Result was created.

Returns:

row

rawCells

public Cell[] rawCells()

Return the array of Cells backing this Result instance. The array is sorted from smallest -> largest using the KeyValue.COMPARATOR. 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 KeyValue.COMPARATOR). 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

raw

@Deprecated
public KeyValue[] raw()

Deprecated. as of 0.96, use rawCells()

Return an cells of a Result as an array of KeyValues WARNING do not use, expensive. This does an arraycopy of the cell[]'s value. Added to ease transition from 0.94 -> 0.96.

Returns:

array of KeyValues, empty array if nothing in result.

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

list

@Deprecated
public List<KeyValue> list()

Deprecated. as of 0.96, use listCells()

Return an cells of a Result as an array of KeyValues WARNING do not use, expensive. This does an arraycopy of the cell[]'s value. Added to ease transition from 0.94 -> 0.96.

Returns:

all sorted List of KeyValues; can be null if no cells in the result

getColumn

@Deprecated
public List<KeyValue> getColumn(byte[] family,
                                            byte[] qualifier)

Deprecated. Use getColumnCells(byte[], byte[]) instead.

getColumnCells

public List<Cell> getColumnCells(byte[] family,
                                 byte[] qualifier)

Return the Cells for the specific column. The Cells are sorted in the KeyValue.COMPARATOR 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

qualifier -

Returns:

a list of Cells for this column or empty list if the column did not exist in the result set

binarySearch

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

binarySearch

protected 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

getColumnLatest

@Deprecated
public KeyValue getColumnLatest(byte[] family,
                                            byte[] qualifier)

Deprecated. Use getColumnLatestCell(byte[], byte[]) instead.

getColumnLatestCell

public Cell getColumnLatestCell(byte[] family,
                                byte[] qualifier)

The Cell for the most recent timestamp for a given column.

Parameters:

family -

qualifier -

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)

getColumnLatest

@Deprecated
public KeyValue getColumnLatest(byte[] family,
                                            int foffset,
                                            int flength,
                                            byte[] qualifier,
                                            int qoffset,
                                            int qlength)

Deprecated. Use getColumnLatestCell(byte[], int, int, byte[], int, int) instead.

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

Returns:

String

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

createCompleteResult

public static Result createCompleteResult(List<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

Parameters:

result -

Returns:

Total size.

copyFrom

public void copyFrom(Result other)

Copy another Result into this one. Needed for the old Mapred framework

Parameters:

other -

Throws:

UnsupportedOperationException - if invoked on instance of EMPTY_RESULT (which is supposed to be immutable).

cellScanner

public CellScanner cellScanner()

Specified by:

cellScanner in interface CellScannable

Returns:

A CellScanner over the contained Cells

current

public Cell current()

Specified by:

current in interface CellScanner

Returns:

the current Cell which may be mutable

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.

isPartial

public boolean isPartial()

Whether or not the result is a partial result. Partial results contain a subset of the cells for a row and should be combined with a result representing the remaining cells in that row to form a complete (non-partial) result.

Returns:

Whether or not the result is a partial result

addResults

@InterfaceAudience.Private
 @Deprecated
public void addResults(ClientProtos.RegionLoadStats loadStats)

Deprecated. use setStatistics(ClientProtos.RegionLoadStats) instead

Add load information about the region to the information about the result

Parameters:

loadStats - statistics about the current region from which this was returned

Throws:

UnsupportedOperationException - if invoked on instance of EMPTY_RESULT (which is supposed to be immutable).

setStatistics

@InterfaceAudience.Private
public void setStatistics(ClientProtos.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 ClientProtos.RegionLoadStats getStats()

Returns:

the associated statistics about the region from which this was returned. Can be null if stats are disabled.