public class KeyValue extends Object implements org.apache.hadoop.io.Writable, HeapSize, Cloneable
If being used client-side, the primary methods to access individual fields
are getRow()
, getFamily()
, getQualifier()
,
getTimestamp()
, and getValue()
. These methods allocate new
byte arrays and return copies. Avoid their use server-side.
Instances of this class are immutable. They do not implement Comparable
but Comparators are provided. Comparators change with context,
whether user table or a catalog table comparison. Its critical you use the
appropriate comparator. There are Comparators for KeyValue instances and
then for just the Key portion of a KeyValue used mostly by HFile
.
KeyValue wraps a byte array and takes offsets and lengths into passed
array at where to start interpreting the content as KeyValue. The KeyValue
format inside a byte array is:
<keylength> <valuelength> <key> <value>
Key is further decomposed as:
<rowlength> <row> <columnfamilylength> <columnfamily> <columnqualifier> <timestamp> <keytype>
The rowlength
maximum is Short.MAX_SIZE
,
column family length maximum is
Byte.MAX_SIZE
, and column qualifier + key length must
be < Integer.MAX_SIZE
.
The column does not contain the family/qualifier delimiter, COLUMN_FAMILY_DELIMITER
Modifier and Type | Class and Description |
---|---|
static class |
KeyValue.KeyComparator
Compare key portion of a
KeyValue . |
static class |
KeyValue.KVComparator
Compare KeyValues.
|
static class |
KeyValue.MetaComparator
|
static class |
KeyValue.MetaKeyComparator
Compare key portion of a
KeyValue for keys in .META.
table. |
static class |
KeyValue.RootComparator
|
static class |
KeyValue.RootKeyComparator
Compare key portion of a
KeyValue for keys in -ROOT- |
static class |
KeyValue.RowComparator
Comparator that compares row component only of a KeyValue.
|
static interface |
KeyValue.SamePrefixComparator<T>
Avoids redundant comparisons for better performance.
|
static class |
KeyValue.SplitKeyValue
Utility class that splits a KeyValue buffer into separate byte arrays.
|
static class |
KeyValue.Type
Key type.
|
Modifier and Type | Field and Description |
---|---|
static byte[] |
COLUMN_FAMILY_DELIM_ARRAY |
static char |
COLUMN_FAMILY_DELIMITER
Colon character in UTF-8
|
static KeyValue.KVComparator |
COMPARATOR
Comparator for plain key/values; i.e.
|
static int |
FAMILY_LENGTH_SIZE
Size of the family length field in bytes
|
static KeyValue.KeyComparator |
KEY_COMPARATOR
Comparator for plain key; i.e.
|
static int |
KEY_INFRASTRUCTURE_SIZE |
static int |
KEY_LENGTH_SIZE
Size of the key length field in bytes
|
static int |
KEYVALUE_INFRASTRUCTURE_SIZE |
static KeyValue |
LOWESTKEY
Lowest possible key.
|
static KeyValue.KVComparator |
META_COMPARATOR
|
static KeyValue.KeyComparator |
META_KEY_COMPARATOR
|
static KeyValue.KVComparator |
ROOT_COMPARATOR
|
static KeyValue.KeyComparator |
ROOT_KEY_COMPARATOR
|
static int |
ROW_LENGTH_SIZE
Size of the row length field in bytes
|
static int |
ROW_OFFSET |
static int |
TIMESTAMP_SIZE
Size of the timestamp field in bytes
|
static int |
TIMESTAMP_TYPE_SIZE |
static int |
TYPE_SIZE
Size of the key type field in bytes
|
Constructor and Description |
---|
KeyValue()
Writable Constructor -- DO NOT USE
|
KeyValue(byte[] bytes)
Creates a KeyValue from the start of the specified byte array.
|
KeyValue(byte[] row,
byte[] family,
byte[] qualifier)
Constructs KeyValue structure filled with null value.
|
KeyValue(byte[] row,
byte[] family,
byte[] qualifier,
byte[] value)
Constructs KeyValue structure filled with null value.
|
KeyValue(byte[] row,
byte[] family,
byte[] qualifier,
int qoffset,
int qlength,
long timestamp,
KeyValue.Type type,
byte[] value,
int voffset,
int vlength)
Constructs KeyValue structure filled with specified values.
|
KeyValue(byte[] row,
byte[] family,
byte[] qualifier,
long timestamp,
byte[] value)
Constructs KeyValue structure filled with specified values.
|
KeyValue(byte[] row,
byte[] family,
byte[] qualifier,
long timestamp,
KeyValue.Type type)
Constructs KeyValue structure filled with specified values.
|
KeyValue(byte[] row,
byte[] family,
byte[] qualifier,
long timestamp,
KeyValue.Type type,
byte[] value)
Constructs KeyValue structure filled with specified values.
|
KeyValue(byte[] bytes,
int offset)
Creates a KeyValue from the specified byte array and offset.
|
KeyValue(byte[] bytes,
int offset,
int length)
Creates a KeyValue from the specified byte array, starting at offset, and
for length
length . |
KeyValue(byte[] row,
int roffset,
int rlength,
byte[] family,
int foffset,
int flength,
byte[] qualifier,
int qoffset,
int qlength,
long timestamp,
KeyValue.Type type,
byte[] value,
int voffset,
int vlength)
Constructs KeyValue structure filled with specified values.
|
KeyValue(byte[] row,
long timestamp)
Constructs KeyValue structure filled with null value.
|
KeyValue(byte[] row,
long timestamp,
KeyValue.Type type)
Constructs KeyValue structure filled with null value.
|
KeyValue(int rlength,
int flength,
int qlength,
long timestamp,
KeyValue.Type type,
int vlength)
Constructs an empty KeyValue structure, with specified sizes.
|
Modifier and Type | Method and Description |
---|---|
KeyValue |
clone()
Clones a KeyValue.
|
static KeyValue |
createFirstDeleteFamilyOnRow(byte[] row,
byte[] family)
Create a Delete Family KeyValue for the specified row and family that would
be smaller than all other possible Delete Family KeyValues that have the
same row and family.
|
static KeyValue |
createFirstOnRow(byte[] row)
Create a KeyValue that is smaller than all other possible KeyValues
for the given row.
|
static KeyValue |
createFirstOnRow(byte[] row,
byte[] family,
byte[] qualifier)
Create a KeyValue for the specified row, family and qualifier that would be
smaller than all other possible KeyValues that have the same row,family,qualifier.
|
static KeyValue |
createFirstOnRow(byte[] row,
byte[] f,
byte[] q,
long ts) |
static KeyValue |
createFirstOnRow(byte[] row,
int roffset,
int rlength,
byte[] family,
int foffset,
int flength,
byte[] qualifier,
int qoffset,
int qlength)
Create a KeyValue for the specified row, family and qualifier that would be
smaller than all other possible KeyValues that have the same row,
family, qualifier.
|
static KeyValue |
createFirstOnRow(byte[] row,
int roffset,
short rlength)
Create a KeyValue that is smaller than all other possible KeyValues
for the given row.
|
static KeyValue |
createFirstOnRow(byte[] row,
long ts)
Creates a KeyValue that is smaller than all other KeyValues that
are older than the passed timestamp.
|
KeyValue |
createFirstOnRowColTS(long ts)
Creates the first KV with the row/family/qualifier of this KV and the
given timestamp.
|
KeyValue |
createKeyOnly(boolean lenAsVal)
Creates a new KeyValue that only contains the key portion (the value is
set to be null).
|
static KeyValue |
createKeyValueFromKey(byte[] b) |
static KeyValue |
createKeyValueFromKey(byte[] b,
int o,
int l) |
static KeyValue |
createKeyValueFromKey(ByteBuffer bb) |
static KeyValue |
createLastOnRow(byte[] row)
Creates a KeyValue that is last on the specified row id.
|
static KeyValue |
createLastOnRow(byte[] row,
int roffset,
int rlength,
byte[] family,
int foffset,
int flength,
byte[] qualifier,
int qoffset,
int qlength)
Create a KeyValue for the specified row, family and qualifier that would be
larger than or equal to all other possible KeyValues that have the same
row, family, qualifier.
|
KeyValue |
createLastOnRowCol()
Similar to
createLastOnRow(byte[], int, int, byte[], int, int,
byte[], int, int) but creates the last key on the row/column of this KV
(the value part of the returned KV is always empty). |
KeyValue |
deepCopy()
Creates a deep copy of this KeyValue, re-allocating the buffer.
|
boolean |
equals(Object other) |
byte[] |
getBuffer() |
static int |
getDelimiter(byte[] b,
int offset,
int length,
int delimiter) |
static int |
getDelimiterInReverse(byte[] b,
int offset,
int length,
int delimiter)
Find index of passed delimiter walking from end of buffer backwards.
|
byte[] |
getFamily()
Primarily for use client-side.
|
static int |
getFamilyDelimiterIndex(byte[] b,
int offset,
int length) |
byte |
getFamilyLength() |
byte |
getFamilyLength(int foffset) |
int |
getFamilyOffset() |
int |
getFamilyOffset(int rlength) |
byte[] |
getKey()
Do not use unless you have to.
|
int |
getKeyLength() |
int |
getKeyOffset() |
String |
getKeyString() |
int |
getLength() |
long |
getMemstoreTS()
Here be dragons
|
int |
getOffset() |
byte[] |
getQualifier()
Primarily for use client-side.
|
int |
getQualifierLength() |
int |
getQualifierLength(int rlength,
int flength) |
int |
getQualifierOffset() |
int |
getQualifierOffset(int foffset) |
byte[] |
getRow()
Primarily for use client-side.
|
static KeyValue.KeyComparator |
getRowComparator(byte[] tableName)
Get the appropriate row comparator for the specified table.
|
short |
getRowLength() |
int |
getRowOffset() |
long |
getTimestamp() |
int |
getTimestampOffset() |
int |
getTimestampOffset(int keylength) |
int |
getTotalColumnLength() |
int |
getTotalColumnLength(int rlength,
int foffset) |
byte |
getType() |
byte[] |
getValue()
Returns value in a new byte array.
|
int |
getValueLength() |
int |
getValueOffset() |
int |
hashCode() |
long |
heapSize() |
static String |
humanReadableTimestamp(long timestamp) |
boolean |
isDelete() |
static boolean |
isDelete(byte t) |
boolean |
isDeleteColumnOrFamily() |
boolean |
isDeleteFamily() |
boolean |
isDeleteType() |
boolean |
isEmptyColumn() |
boolean |
isInternal() |
boolean |
isLatestTimestamp() |
static String |
keyToString(byte[] k) |
static String |
keyToString(byte[] b,
int o,
int l) |
static byte[] |
makeColumn(byte[] family,
byte[] qualifier)
Makes a column in family:qualifier form from separate byte arrays.
|
boolean |
matchingColumn(byte[] family,
byte[] qualifier) |
boolean |
matchingColumnNoDelimiter(byte[] column) |
boolean |
matchingFamily(byte[] family) |
boolean |
matchingFamily(byte[] family,
int offset,
int length) |
boolean |
matchingFamily(KeyValue other) |
boolean |
matchingQualifier(byte[] qualifier) |
boolean |
matchingQualifier(byte[] qualifier,
int offset,
int length) |
boolean |
matchingQualifier(KeyValue other) |
boolean |
matchingRow(byte[] row) |
boolean |
matchingRow(byte[] row,
int offset,
int length) |
boolean |
matchingRow(KeyValue other) |
boolean |
nonNullRowAndColumn() |
static byte[][] |
parseColumn(byte[] c)
Splits a column in family:qualifier form into separate byte arrays.
|
void |
readFields(DataInput in) |
void |
readFields(int length,
DataInput in) |
void |
setMemstoreTS(long memstoreTS) |
KeyValue |
shallowCopy()
Creates a shallow copy of this KeyValue, reusing the data byte buffer.
|
KeyValue.SplitKeyValue |
split() |
String |
toString() |
Map<String,Object> |
toStringMap()
Produces a string map for this key/value pair.
|
boolean |
updateLatestStamp(byte[] now) |
void |
write(DataOutput out) |
public static final char COLUMN_FAMILY_DELIMITER
public static final byte[] COLUMN_FAMILY_DELIM_ARRAY
public static KeyValue.KVComparator COMPARATOR
public static KeyValue.KeyComparator KEY_COMPARATOR
public static KeyValue.KVComparator META_COMPARATOR
public static KeyValue.KeyComparator META_KEY_COMPARATOR
public static KeyValue.KVComparator ROOT_COMPARATOR
public static KeyValue.KeyComparator ROOT_KEY_COMPARATOR
public static final int KEY_LENGTH_SIZE
public static final int TYPE_SIZE
public static final int ROW_LENGTH_SIZE
public static final int FAMILY_LENGTH_SIZE
public static final int TIMESTAMP_SIZE
public static final int TIMESTAMP_TYPE_SIZE
public static final int KEY_INFRASTRUCTURE_SIZE
public static final int ROW_OFFSET
public static final int KEYVALUE_INFRASTRUCTURE_SIZE
public static final KeyValue LOWESTKEY
public KeyValue()
public KeyValue(byte[] bytes)
bytes
content is formatted as a KeyValue blob.bytes
- byte arraypublic KeyValue(byte[] bytes, int offset)
bytes
content starting at offset
is
formatted as a KeyValue blob.bytes
- byte arrayoffset
- offset to start of KeyValuepublic KeyValue(byte[] bytes, int offset, int length)
length
.bytes
- byte arrayoffset
- offset to start of the KeyValuelength
- length of the KeyValuepublic KeyValue(byte[] row, long timestamp)
KeyValue.Type.Maximum
row
- - row key (arbitrary byte array)timestamp
- public KeyValue(byte[] row, long timestamp, KeyValue.Type type)
row
- - row key (arbitrary byte array)timestamp
- public KeyValue(byte[] row, byte[] family, byte[] qualifier)
KeyValue.Type.Maximum
row
- - row key (arbitrary byte array)family
- family namequalifier
- column qualifierpublic KeyValue(byte[] row, byte[] family, byte[] qualifier, byte[] value)
row
- - row key (arbitrary byte array)family
- family namequalifier
- column qualifierpublic KeyValue(byte[] row, byte[] family, byte[] qualifier, long timestamp, KeyValue.Type type)
row
- row keyfamily
- family namequalifier
- column qualifiertimestamp
- version timestamptype
- key typeIllegalArgumentException
public KeyValue(byte[] row, byte[] family, byte[] qualifier, long timestamp, byte[] value)
row
- row keyfamily
- family namequalifier
- column qualifiertimestamp
- version timestampvalue
- column valueIllegalArgumentException
public KeyValue(byte[] row, byte[] family, byte[] qualifier, long timestamp, KeyValue.Type type, byte[] value)
row
- row keyfamily
- family namequalifier
- column qualifiertimestamp
- version timestamptype
- key typevalue
- column valueIllegalArgumentException
public KeyValue(byte[] row, byte[] family, byte[] qualifier, int qoffset, int qlength, long timestamp, KeyValue.Type type, byte[] value, int voffset, int vlength)
row
- row keyfamily
- family namequalifier
- column qualifierqoffset
- qualifier offsetqlength
- qualifier lengthtimestamp
- version timestamptype
- key typevalue
- column valuevoffset
- value offsetvlength
- value lengthIllegalArgumentException
public KeyValue(byte[] row, int roffset, int rlength, byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength, long timestamp, KeyValue.Type type, byte[] value, int voffset, int vlength)
Column is split into two fields, family and qualifier.
row
- row keyroffset
- row offsetrlength
- row lengthfamily
- family namefoffset
- family offsetflength
- family lengthqualifier
- column qualifierqoffset
- qualifier offsetqlength
- qualifier lengthtimestamp
- version timestamptype
- key typevalue
- column valuevoffset
- value offsetvlength
- value lengthIllegalArgumentException
public KeyValue(int rlength, int flength, int qlength, long timestamp, KeyValue.Type type, int vlength)
Column is split into two fields, family and qualifier.
rlength
- row lengthflength
- family lengthqlength
- qualifier lengthtimestamp
- version timestamptype
- key typevlength
- value lengthIllegalArgumentException
public static KeyValue.KeyComparator getRowComparator(byte[] tableName)
tableName
- The table name.public static boolean isDelete(byte t)
KeyValue.Type.Delete
or
a {KeyValue.Type#DeleteFamily} or a KeyValue.Type.DeleteColumn
KeyValue type.public long getMemstoreTS()
public void setMemstoreTS(long memstoreTS)
public KeyValue clone()
public KeyValue deepCopy()
clone()
. Added for clarity vs shallowCopy()public KeyValue shallowCopy()
public static String keyToString(byte[] k)
k
- Key portion of a KeyValue.public Map<String,Object> toStringMap()
public static String keyToString(byte[] b, int o, int l)
public static String humanReadableTimestamp(long timestamp)
public byte[] getBuffer()
public int getOffset()
getBuffer()
at which this KeyValue starts.public int getLength()
getBuffer()
.public int getKeyOffset()
public String getKeyString()
public int getKeyLength()
public int getValueOffset()
public int getValueLength()
public int getRowOffset()
public short getRowLength()
public int getFamilyOffset()
public int getFamilyOffset(int rlength)
public byte getFamilyLength()
public byte getFamilyLength(int foffset)
public int getQualifierOffset()
public int getQualifierOffset(int foffset)
public int getQualifierLength()
public int getQualifierLength(int rlength, int flength)
public int getTotalColumnLength()
public int getTotalColumnLength(int rlength, int foffset)
public int getTimestampOffset()
public int getTimestampOffset(int keylength)
keylength
- Pass if you have it to save on a int creation.public boolean isLatestTimestamp()
public boolean isInternal()
public boolean updateLatestStamp(byte[] now)
now
- Time to set into this
IFF timestamp ==
HConstants.LATEST_TIMESTAMP
(else, its a noop).public byte[] getKey()
getRow()
, getFamily()
, getQualifier()
, and
getValue()
if accessing a KeyValue client-side.public byte[] getValue()
getBuffer()
with appropriate offsets and lengths instead to
save on allocations.public byte[] getRow()
If server-side, use getBuffer()
with appropriate offsets and
lengths instead.
public long getTimestamp()
public byte getType()
public boolean isDelete()
KeyValue.Type.Delete
or
a {KeyValue.Type#DeleteFamily} or a KeyValue.Type.DeleteColumn
KeyValue type.public boolean isDeleteType()
KeyValue.Type.Delete
type.public boolean isDeleteFamily()
public boolean isDeleteColumnOrFamily()
public byte[] getFamily()
If server-side, use getBuffer()
with appropriate offsets and
lengths instead.
public byte[] getQualifier()
If server-side, use getBuffer()
with appropriate offsets and
lengths instead.
Use getBuffer()
with appropriate offsets and lengths instead.
public KeyValue.SplitKeyValue split()
public boolean matchingFamily(byte[] family)
family
- public boolean matchingFamily(byte[] family, int offset, int length)
public boolean matchingFamily(KeyValue other)
public boolean matchingQualifier(byte[] qualifier)
qualifier
- public boolean matchingQualifier(byte[] qualifier, int offset, int length)
public boolean matchingQualifier(KeyValue other)
public boolean matchingRow(byte[] row)
public boolean matchingRow(byte[] row, int offset, int length)
public boolean matchingRow(KeyValue other)
public boolean matchingColumnNoDelimiter(byte[] column)
column
- Column minus its delimiterpublic boolean matchingColumn(byte[] family, byte[] qualifier)
family
- column familyqualifier
- column qualifierpublic boolean nonNullRowAndColumn()
public boolean isEmptyColumn()
public KeyValue createKeyOnly(boolean lenAsVal)
lenAsVal
- replace value with the actual value length (false=empty)public static byte[][] parseColumn(byte[] c)
Not recommend to be used as this is old-style API.
c
- The column.public static byte[] makeColumn(byte[] family, byte[] qualifier)
Not recommended for usage as this is old-style API.
family
- qualifier
- public static int getFamilyDelimiterIndex(byte[] b, int offset, int length)
b
- public static int getDelimiter(byte[] b, int offset, int length, int delimiter)
b
- delimiter
- b
moving rightward.public static int getDelimiterInReverse(byte[] b, int offset, int length, int delimiter)
b
- delimiter
- public static KeyValue createLastOnRow(byte[] row)
row
- row keyrow
public static KeyValue createFirstOnRow(byte[] row)
row
- - row key (arbitrary byte array)row
public static KeyValue createFirstOnRow(byte[] row, int roffset, short rlength)
row
- - row key (arbitrary byte array)row
public static KeyValue createFirstOnRow(byte[] row, long ts)
row
- - row key (arbitrary byte array)ts
- - timestamprow
and timestamp.public static KeyValue createFirstOnRow(byte[] row, byte[] family, byte[] qualifier)
row
- - row key (arbitrary byte array)family
- - family namequalifier
- - column qualifierrow
, and column.public static KeyValue createFirstDeleteFamilyOnRow(byte[] row, byte[] family)
row
- - row key (arbitrary byte array)family
- - family namerow
.public static KeyValue createFirstOnRow(byte[] row, byte[] f, byte[] q, long ts)
row
- - row key (arbitrary byte array)f
- - family nameq
- - column qualifierts
- - timestamprow
, column and timestamppublic static KeyValue createFirstOnRow(byte[] row, int roffset, int rlength, byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength)
row
- row keyroffset
- row offsetrlength
- row lengthfamily
- family namefoffset
- family offsetflength
- family lengthqualifier
- column qualifierqoffset
- qualifier offsetqlength
- qualifier lengthpublic static KeyValue createLastOnRow(byte[] row, int roffset, int rlength, byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, int qlength)
row
- row keyroffset
- row offsetrlength
- row lengthfamily
- family namefoffset
- family offsetflength
- family lengthqualifier
- column qualifierqoffset
- qualifier offsetqlength
- qualifier lengthpublic KeyValue createLastOnRowCol()
createLastOnRow(byte[], int, int, byte[], int, int,
byte[], int, int)
but creates the last key on the row/column of this KV
(the value part of the returned KV is always empty). Used in creating
"fake keys" for the multi-column Bloom filter optimization to skip the
row/column we already know is not in the file.public KeyValue createFirstOnRowColTS(long ts)
public static KeyValue createKeyValueFromKey(byte[] b)
b
- public static KeyValue createKeyValueFromKey(ByteBuffer bb)
bb
- public static KeyValue createKeyValueFromKey(byte[] b, int o, int l)
b
- o
- l
- public long heapSize()
public void readFields(int length, DataInput in) throws IOException
IOException
public void readFields(DataInput in) throws IOException
readFields
in interface org.apache.hadoop.io.Writable
IOException
public void write(DataOutput out) throws IOException
write
in interface org.apache.hadoop.io.Writable
IOException
Copyright © 2014 The Apache Software Foundation. All Rights Reserved.