org.apache.hadoop.hbase.client
Class Result

java.lang.Object
  extended by org.apache.hadoop.hbase.client.Result
All Implemented Interfaces:
WritableWithSize, org.apache.hadoop.io.Writable

public class Result
extends Object
implements org.apache.hadoop.io.Writable, WritableWithSize

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 KeyValue objects, each representing an HBase cell defined by the row, family, qualifier, timestamp, and value.

The underlying KeyValue objects can be accessed through the methods sorted() and list(). Each KeyValue can then be accessed through KeyValue.getRow(), KeyValue.getFamily(), KeyValue.getQualifier(), KeyValue.getTimestamp(), and KeyValue.getValue().


Constructor Summary
Result()
          Constructor used for Writable.
Result(ImmutableBytesWritable bytes)
          Instantiate a Result from the specified raw binary format.
Result(KeyValue[] kvs)
          Instantiate a Result with the specified array of KeyValues.
Result(List<KeyValue> kvs)
          Instantiate a Result with the specified List of KeyValues.
 
Method Summary
protected  int binarySearch(KeyValue[] kvs, byte[] family, byte[] qualifier)
           
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 the specified column.
 ImmutableBytesWritable getBytes()
          Returns the raw binary encoding of this Result.
 List<KeyValue> getColumn(byte[] family, byte[] qualifier)
          Return the KeyValues for the specific column.
 KeyValue getColumnLatest(byte[] family, byte[] qualifier)
          The KeyValue for the most recent for a given column.
 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 that this result is for
 byte[] getValue(byte[] family, byte[] qualifier)
          Get the latest version of the specified column.
 long getWritableSize()
          Provide a size hint to the caller.
static long getWriteArraySize(Result[] results)
           
 boolean isEmpty()
          Check if the underlying KeyValue [] is empty or not
 List<KeyValue> list()
          Create a sorted list of the KeyValue's in this result.
 KeyValue[] raw()
          Return the array of KeyValues backing this Result instance.
static Result[] readArray(DataInput in)
           
 void readFields(DataInput in)
           
 int size()
           
 KeyValue[] sorted()
          Deprecated.  
 String toString()
           
 byte[] value()
          Returns the value of the first column in the Result.
 void write(DataOutput out)
           
static void writeArray(DataOutput out, Result[] results)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Result

public Result()
Constructor used for Writable.


Result

public Result(KeyValue[] kvs)
Instantiate a Result with the specified array of KeyValues.

Parameters:
kvs - array of KeyValues

Result

public Result(List<KeyValue> kvs)
Instantiate a Result with the specified List of KeyValues.

Parameters:
kvs - List of KeyValues

Result

public Result(ImmutableBytesWritable bytes)
Instantiate a Result from the specified raw binary format.

Parameters:
bytes - raw binary format of Result
Method Detail

getRow

public byte[] getRow()
Method for retrieving the row that this result is for

Returns:
row

raw

public KeyValue[] raw()
Return the array of KeyValues 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 KeyValue in the array. If you request column "A" with 2 version you will have at most 2 KeyValues, 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 KeyValue for each column and no more. This API is faster than using getFamilyMap() and getMap()

Returns:
array of KeyValues

list

public List<KeyValue> list()
Create a sorted list of the KeyValue's in this result. Since HBase 0.20.5 this is equivalent to raw().

Returns:
The sorted list of KeyValue's.

sorted

public KeyValue[] sorted()
Deprecated. 

Returns a sorted array of KeyValues in this Result.

Since HBase 0.20.5 this is equivalent to raw(). Use raw() instead.

Returns:
sorted array of KeyValues

getColumn

public List<KeyValue> getColumn(byte[] family,
                                byte[] qualifier)
Return the KeyValues for the specific column. The KeyValues 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 KeyValue

Parameters:
family - the family
qualifier -
Returns:
a list of KeyValues for this column or empty list if the column did not exist in the result set

binarySearch

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

getColumnLatest

public KeyValue getColumnLatest(byte[] family,
                                byte[] qualifier)
The KeyValue for the most recent for a given column. If the column does not exist in the result set - if it wasn't selected in the query (Get/Scan) or just does not exist in the row the return value is null.

Parameters:
family -
qualifier -
Returns:
KeyValue for the column or null

getValue

public byte[] getValue(byte[] family,
                       byte[] qualifier)
Get the latest version of the specified column.

Parameters:
family - family name
qualifier - column qualifier
Returns:
value of latest version of column, null if none found

containsColumn

public boolean containsColumn(byte[] family,
                              byte[] qualifier)
Checks for existence of the specified column.

Parameters:
family - family name
qualifier - column qualifier
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

getBytes

public ImmutableBytesWritable getBytes()
Returns the raw binary encoding of this Result.

Please note, there may be an offset into the underlying byte array of the returned ImmutableBytesWritable. Be sure to use both ImmutableBytesWritable.get() and ImmutableBytesWritable.getOffset()

Returns:
pointer to raw binary of Result

isEmpty

public boolean isEmpty()
Check if the underlying KeyValue [] is empty or not

Returns:
true if empty

size

public int size()
Returns:
the size of the underlying KeyValue []

toString

public String toString()
Overrides:
toString in class Object
Returns:
String

readFields

public void readFields(DataInput in)
                throws IOException
Specified by:
readFields in interface org.apache.hadoop.io.Writable
Throws:
IOException

getWritableSize

public long getWritableSize()
Description copied from interface: WritableWithSize
Provide a size hint to the caller. write() should ideally not go beyond this if at all possible. You can return 0 if there is no size hint.

Specified by:
getWritableSize in interface WritableWithSize
Returns:
the size of the writable

write

public void write(DataOutput out)
           throws IOException
Specified by:
write in interface org.apache.hadoop.io.Writable
Throws:
IOException

getWriteArraySize

public static long getWriteArraySize(Result[] results)

writeArray

public static void writeArray(DataOutput out,
                              Result[] results)
                       throws IOException
Throws:
IOException

readArray

public static Result[] readArray(DataInput in)
                          throws IOException
Throws:
IOException

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


Copyright © 2011 The Apache Software Foundation. All Rights Reserved.