The very first method you may want to know about is one that lets you store data in HBase. Here is the call that lets you do that:

void put(Put put) throws IOException

It expects one or a list of Put objects that, in turn, are created with one of these constructors:

Put(byte[] row)
Put(byte[] row, RowLock rowLock)
Put(byte[] row, long ts)
Put(byte[] row, long ts, RowLock rowLock)

You need to supply a row to create a Put instance. A row in HBase is identified by a unique row key and—as is the case with most values in HBase—this is a Java byte[] array. You are free to choose any row key you like, but please also note that Chapter 9 provides a whole section on row key design (see Key Design). For now, we assume this can be anything, and often it represents a fact from the physical world—for example, a username or an order ID. These can be simple numbers but also UUIDs^[50] and so on.

HBase is kind enough to provide us with a helper class that has many static methods to convert Java types into byte[] arrays. Example 3-1 provides a short list of what it offers.

static byte[] toBytes(ByteBuffer bb)
static byte[] toBytes(String s)
static byte[] toBytes(boolean b)
static byte[] toBytes(long val)
static byte[] toBytes(float f)
static byte[] toBytes(int val)
...

Once you have created the Put instance you can add data to it. This is done using these methods:

Put add(byte[] family, byte[] qualifier, byte[] value)
Put add(byte[] family, byte[] qualifier, long ts, byte[] value)
Put add(KeyValue kv) throws IOException

Each call to add() specifies exactly one column, or, in combination with an optional timestamp, one single cell. Note that if you do not specify the timestamp with the add() call, the Put instance will use the optional timestamp parameter from the constructor (also called ts) and you should leave it to the region server to set it.

The variant that takes an existing KeyValue instance is for advanced users that have learned how to retrieve, or create, this internal class. It represents a single, unique cell; like a coordination system used with maps it is addressed by the row key, column family, column qualifier, and timestamp, pointing to one value in a three-dimensional, cube-like system—where time is the third dimension.

One way to come across the internal KeyValue type is by using the reverse methods to add(), aptly named get():

List<KeyValue> get(byte[] family, byte[] qualifier)
Map<byte[], List<KeyValue>> getFamilyMap()

These two calls retrieve what you have added earlier, while having converted the unique cells into KeyValue instances. You can retrieve all cells for either an entire column family, a specific column within a family, or everything. The latter is the getFamilyMap() call, which you can then iterate over to check the details contained in each available KeyValue.

Instead of having to iterate to check for the existence of specific cells, you can use the following set of methods:

boolean has(byte[] family, byte[] qualifier)
boolean has(byte[] family, byte[] qualifier, long ts)
boolean has(byte[] family, byte[] qualifier, byte[] value)
boolean has(byte[] family, byte[] qualifier, long ts, byte[] value)

They increasingly ask for more specific details and return true if a match can be found. The first method simply checks for the presence of a column. The others add the option to check for a timestamp, a given value, or both.

There are more methods provided by the Put class, summarized in Table 3-1.

Example 3-2 shows how all this is put together (no pun intended) into a basic application.

import org.apache.hadoop.conf.Configuration;
import org.apache.hadoop.hbase.HBaseConfiguration;
import org.apache.hadoop.hbase.client.HTable;
import org.apache.hadoop.hbase.client.Put;
import org.apache.hadoop.hbase.util.Bytes;

import java.io.IOException;

public class PutExample {

  public static void main(String[] args) throws IOException {
    Configuration conf = HBaseConfiguration.create(); 

    HTable table = new HTable(conf, "testtable"); 

    Put put = new Put(Bytes.toBytes("row1")); 

    put.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val1")); 
    put.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual2"),
      Bytes.toBytes("val2")); 

    table.put(put); 
  }
}

This is a (nearly) full representation of the code used and every line is explained. The following examples will omit more and more of the boilerplate code so that you can focus on the important parts.

static Configuration create()
static Configuration create(Configuration that)

Configuration config = HBaseConfiguration.create();
config.set("hbase.zookeeper.quorum", "zk1.foo.com,zk2.foo.com");

You can, once again, make use of the command-line shell (see Quick-Start Guide) to verify that our insert has succeeded:

hbase(main):001:0> list
TABLE
testtable
1 row(s) in 0.0400 seconds

hbase(main):002:0> scan 'testtable'
ROW              COLUMN+CELL
row1             column=colfam1:qual1, timestamp=1294065304642, value=val1
1 row(s) in 0.2050 seconds

Another optional parameter while creating a Put instance is called ts, or timestamp. It allows you to store a value at a particular version in the HBase table.

hbase(main):001:0> create 'test', 'cf1'             
0 row(s) in 0.9810 seconds

hbase(main):002:0> put 'test', 'row1', 'cf1', 'val1'
0 row(s) in 0.0720 seconds

hbase(main):003:0> put 'test', 'row1', 'cf1', 'val2'
0 row(s) in 0.0520 seconds

hbase(main):004:0> scan 'test'                      
ROW              COLUMN+CELL
 row1            column=cf1:, timestamp=1297853125623, value=val2
1 row(s) in 0.0790 seconds

hbase(main):005:0> scan 'test', { VERSIONS => 3 }   
ROW              COLUMN+CELL
 row1            column=cf1:, timestamp=1297853125623, value=val2
 row1            column=cf1:, timestamp=1297853122412, value=val1
1 row(s) in 0.0640 seconds

When you do not specify that parameter, it is implicitly set to the current time of the RegionServer responsible for the given row at the moment it is added to the underlying storage.

The constructors of the Put class have another optional parameter, called rowLock. It gives you the ability to hand in an external row lock, something discussed in Row Locks. Suffice it to say for now that you can create your own RowLock instance that can be used to prevent other clients from accessing specific rows while you are modifying it repeatedly.

From your code you may have to deal with KeyValue instances directly. As you may recall from our discussion earlier in this book, these instances contain the data as well as the coordinates of one specific cell. The coordinates are the row key, name of the column family, column qualifier, and timestamp. The class provides a plethora of constructors that allow you to combine all of these in many variations. The fully specified constructor looks like this:

KeyValue(byte[] row, int roffset, int rlength,
  byte[] family, int foffset, int flength, byte[] qualifier, int qoffset, 
  int qlength, long timestamp, Type type, byte[] value, int voffset, 
  int vlength)

The data as well as the coordinates are stored as a Java byte[], that is, as a byte array. The design behind this type of low-level storage is to allow for arbitrary data, but also to be able to efficiently store only the required bytes, keeping the overhead of internal data structures to a minimum. This is also the reason that there is an offset and length parameter for each byte array paremeter. They allow you to pass in existing byte arrays while doing very fast byte-level operations.

For every member of the coordinates, there is a getter that can retrieve the byte arrays and their given offset and length. This also can be accessed at the topmost level, that is, the underlying byte buffer:

byte[] getBuffer()
int getOffset()
int getLength()

They return the full byte array details backing the current KeyValue instance. There will be few occasions where you will ever have to go that far. But it is available and you can make use of it—if need be.

Two very interesting methods to know are:

byte [] getRow()
byte [] getKey()

The question you may ask yourself is: what is the difference between a row and a key? While you will learn about the difference in Storage, for now just remember that the row is what we have been referring to alternatively as the row key, that is, the row parameter of the Put constructor, and the key is what was previously introduced as the coordinates of a cell—in their raw, byte array format. In practice, you hardly ever have to use getKey() but will be more likely to use getRow().

The KeyValue class also provides a large list of internal classes implementing the Comparator interface. They can be used in your own code to do the same comparisons as done inside HBase. This is useful when retrieving KeyValue instances using the API and further sorting or processing them in order. They are listed in Table 3-2.

The KeyValue class exports most of these comparators as a static instance for each class. For example, there is a public field named KEY_COMPARATOR, giving access to a KeyComparator instance. The COMPARATOR field is pointing to an instance of the more frequently used KVComparator class. So instead of creating your own instances, you could use a provided one—for example, when creating a set holding KeyValue instances that should be sorted in the same order that HBase is using internally:

TreeSet<KeyValue> set = 
  new TreeSet<KeyValue>(KeyValue.COMPARATOR)

There is one more field per KeyValue instance that is representing an additional dimension for its unique coordinates: the type. Table 3-3 lists the possible values.

You can see the type of an existing KeyValue instance by, for example, using another provided call:

String toString()

This prints out the meta information of the current KeyValue instance, and has the following format:

<row-key>/<family>:<qualifier>/<version>/<type>/<value-length>

This is used by some of the example code for this book to check if data has been set or retrieved, and what the meta information is.

The class has many more convenience methods that allow you to compare parts of the stored data, as well as check what type it is, get its computed heap size, clone or copy it, and more. There are static methods to create special instances of KeyValue that can be used for comparisons, or when manipulating data on that low of a level within HBase. You should consult the provided Java documentation to learn more about them.^[52] Also see Storage for a detailed explanation of the raw, binary format.

Each put operation is effectively an RPC^[53] that is transferring data from the client to the server and back. This is OK for a low number of operations, but not for applications that need to store thousands of values per second into a table.

The HBase API comes with a built-in client-side write buffer that collects put operations so that they are sent in one RPC call to the server(s). The global switch to control if it is used or not is represented by the following methods:

void setAutoFlush(boolean autoFlush)
boolean isAutoFlush()

By default, the client-side buffer is not enabled. You activate the buffer by setting auto-flush to false, by invoking:

table.setAutoFlush(false)

This will enable the client-side buffering mechanism, and you can check the state of the flag respectively with the isAutoFlush() method. It will return true when you initially create the HTable instance. Otherwise, it will obviously return the current state as set by your code.

Once you have activated the buffer, you can store data into HBase as shown in Single Puts. You do not cause any RPCs to occur, though, because the Put instances you stored are kept in memory in your client process. When you want to force the data to be written, you can call another API function:

void flushCommits() throws IOException

The flushCommits() method ships all the modifications to the remote server(s). The buffered Put instances can span many different rows. The client is smart enough to batch these updates accordingly and send them to the appropriate region server(s). Just as with the single put() call, you do not have to worry about where data resides, as this is handled transparently for you by the HBase client. Figure 3-1 shows how the operations are sorted and grouped before they are shipped over the network, with one single RPC per region server.

Figure 3-1. The client-side puts sorted and grouped by region server

While you can force a flush of the buffer, this is usually not necessary, as the API tracks how much data you are buffering by counting the required heap size of every instance you have added. This tracks the entire overhead of your data, also including necessary internal data structures. Once you go over a specific limit, the client will call the flush command for you implicitly. You can control the configured maximum allowed client-side write buffer size with these calls:

long getWriteBufferSize()
void setWriteBufferSize(long writeBufferSize) throws IOException

The default size is a moderate 2 MB (or 2,097,152 bytes) and assumes you are inserting reasonably small records into HBase, that is, each a fraction of that buffer size. If you were to store larger data, you may want to consider increasing this value to allow your client to efficiently group together a certain number of records per RPC.

<property>
  <name>hbase.client.write.buffer</name>
  <value>20971520</value>
</property>

The buffer is only ever flushed on two occasions:

Example 3-3 shows how the write buffer is controlled from the client API.

    HTable table = new HTable(conf, "testtable");
    System.out.println("Auto flush: " + table.isAutoFlush());  

    table.setAutoFlush(false); 

    Put put1 = new Put(Bytes.toBytes("row1"));
    put1.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val1"));
    table.put(put1); 

    Put put2 = new Put(Bytes.toBytes("row2"));
    put2.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val2"));
    table.put(put2);

    Put put3 = new Put(Bytes.toBytes("row3"));
    put3.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val3"));
    table.put(put3);

    Get get = new Get(Bytes.toBytes("row1"));
    Result res1 = table.get(get);
    System.out.println("Result: " + res1); 

    table.flushCommits(); 

    Result res2 = table.get(get);
    System.out.println("Result: " + res2); 

This example also shows a specific behavior of the buffer that you may not anticipate. Let’s see what it prints out when executed:

Auto flush: true
Result: keyvalues=NONE
Result: keyvalues={row1/colfam1:qual1/1300267114099/Put/vlen=4}

While you have not seen the get() operation yet, you should still be able to correctly infer what it does, that is, reading data back from the servers. But for the first get() in the example, the API returns a NONE value—what does that mean? It is caused by the fact that the client write buffer is an in-memory structure that is literally holding back any unflushed records. Nothing was sent to the servers yet, and therefore you cannot access it.

The client API has the ability to insert single Put instances as shown earlier, but it also has the advanced feature of batching operations together. This comes in the form of the following call:

void put(List<Put> puts) throws IOException

You will have to create a list of Put instances and hand it to this call. Example 3-4 updates the previous example by creating a list to hold the mutations and eventually calling the list-based put() method.

    List<Put> puts = new ArrayList<Put>(); 

    Put put1 = new Put(Bytes.toBytes("row1"));
    put1.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val1"));
    puts.add(put1); 

    Put put2 = new Put(Bytes.toBytes("row2"));
    put2.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val2"));
    puts.add(put2); 

    Put put3 = new Put(Bytes.toBytes("row2"));
    put3.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual2"),
      Bytes.toBytes("val3"));
    puts.add(put3); 

    table.put(puts); 

A quick check with the HBase Shell reveals that the rows were stored as expected. Note that the example actually modified three columns, but in two rows only. It added two columns into the row with the key row2, using two separate qualifiers, qual1 and qual2, creating two uniquely named columns in the same row.

hbase(main):001:0> scan 'testtable'
ROW              COLUMN+CELL
 row1            column=colfam1:qual1, timestamp=1300108258094, value=val1
 row2            column=colfam1:qual1, timestamp=1300108258094, value=val2
 row2            column=colfam1:qual2, timestamp=1300108258098, value=val3
2 row(s) in 0.1590 seconds

Since you are issuing a list of row mutations to possibly many different rows, there is a chance that not all of them will succeed. This could be due to a few reasons—for example, when there is an issue with one of the region servers and the client-side retry mechanism needs to give up because the number of retries has exceeded the configured maximum. If there is problem with any of the put calls on the remote servers, the error is reported back to you subsequently in the form of an IOException.

Example 3-5 uses a bogus column family name to insert a column. Since the client is not aware of the structure of the remote table—it could have been altered since it was created—this check is done on the server side.

    Put put1 = new Put(Bytes.toBytes("row1"));
    put1.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val1"));
    puts.add(put1);
    Put put2 = new Put(Bytes.toBytes("row2"));
    put2.add(Bytes.toBytes("BOGUS"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val2")); 
    puts.add(put2);
    Put put3 = new Put(Bytes.toBytes("row2"));
    put3.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual2"),
      Bytes.toBytes("val3"));
    puts.add(put3);

    table.put(puts); 

The call to put() fails with the following (or similar) error message:

org.apache.hadoop.hbase.client.RetriesExhaustedWithDetailsException:
 Failed 1 action: NoSuchColumnFamilyException: 1 time, 
 servers with issues: 10.0.0.57:51640,

You may wonder what happened to the other, nonfaulty puts in the list. Using the shell again you should see that the two correct puts have been applied:

hbase(main):001:0> scan 'testtable'
ROW              COLUMN+CELL
 row1            column=colfam1:qual1, timestamp=1300108925848, value=val1
 row2            column=colfam1:qual2, timestamp=1300108925848, value=val3
2 row(s) in 0.0640 seconds

The servers iterate over all operations and try to apply them. The failed ones are returned and the client reports the remote error using the RetriesExhaustedWithDetailsException, giving you insight into how many operations have failed, with what error, and how many times it has retried to apply the erroneous modification. It is interesting to note that, for the bogus column family, the retry is automatically set to 1 (see the NoSuchColumnFamilyException: 1 time), as this is an error from which HBase cannot recover.

Those Put instances that have failed on the server side are kept in the local write buffer. They will be retried the next time the buffer is flushed. You can also access them using the getWriteBuffer() method of HTable and take, for example, evasive actions.

Some checks are done on the client side, though—for example, to ensure that the put has a column specified or that it is completely empty. In that event, the client is throwing an exception that leaves the operations preceding the faulty one in the client buffer.

You could catch the exception and flush the write buffer manually to apply those modifications. Example 3-6 shows one approach to handle this.

    Put put1 = new Put(Bytes.toBytes("row1"));
    put1.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val1"));
    puts.add(put1);
    Put put2 = new Put(Bytes.toBytes("row2"));
    put2.add(Bytes.toBytes("BOGUS"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val2"));
    puts.add(put2);
    Put put3 = new Put(Bytes.toBytes("row2"));
    put3.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual2"),
      Bytes.toBytes("val3"));
    puts.add(put3);
    Put put4 = new Put(Bytes.toBytes("row2"));
    puts.add(put4); 

    try {
      table.put(puts);
    } catch (Exception e) {
      System.err.println("Error: " + e);
      table.flushCommits(); 
    }

The example code this time should give you two errors, similar to:

Error: java.lang.IllegalArgumentException: No columns to insert
Exception in thread "main" 
 org.apache.hadoop.hbase.client.RetriesExhaustedWithDetailsException: 
 Failed 1 action: NoSuchColumnFamilyException: 1 time, 
 servers with issues: 10.0.0.57:51640,

The first Error is the client-side check, while the second is the remote exception that now is caused by calling

table.flushCommits()

in the try/catch block.

You need to watch out for a peculiarity using the list-based put call: you cannot control the order in which the puts are applied on the server side, which implies that the order in which the servers are called is also not under your control. Use this call with caution if you have to guarantee a specific order—in the worst case, you need to create smaller batches and explicitly flush the client-side write cache to enforce that they are sent to the remote servers.

There is a special variation of the put calls that warrants its own section: check and put. The method signature is:

boolean checkAndPut(byte[] row, byte[] family, byte[] qualifier,
  byte[] value, Put put) throws IOException

This call allows you to issue atomic, server-side mutations that are guarded by an accompanying check. If the check passes successfully, the put operation is executed; otherwise, it aborts the operation completely. It can be used to update data based on current, possibly related, values.

Such guarded operations are often used in systems that handle, for example, account balances, state transitions, or data processing. The basic principle is that you read data at one point in time and process it. Once you are ready to write back the result, you want to make sure that no other client has done the same already. You use the atomic check to compare that the value is not modified and therefore apply your value.

The call returns a boolean result value, indicating whether the Put has been applied or not, returning true or false, respectively. Example 3-7 shows the interactions between the client and the server, returning the expected results.

    Put put1 = new Put(Bytes.toBytes("row1"));
    put1.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val1")); 

    boolean res1 = table.checkAndPut(Bytes.toBytes("row1"),
      Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"), null, put1); 
    System.out.println("Put applied: " + res1); 

    boolean res2 = table.checkAndPut(Bytes.toBytes("row1"),
      Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"), null, put1); 
    System.out.println("Put applied: " + res2); 

    Put put2 = new Put(Bytes.toBytes("row1"));
    put2.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual2"),
      Bytes.toBytes("val2")); 

    boolean res3 = table.checkAndPut(Bytes.toBytes("row1"),
      Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"), 
      Bytes.toBytes("val1"), put2);
    System.out.println("Put applied: " + res3); 

    Put put3 = new Put(Bytes.toBytes("row2"));
    put3.add(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"),
      Bytes.toBytes("val3")); 

    boolean res4 = table.checkAndPut(Bytes.toBytes("row1"),
      Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"), 
      Bytes.toBytes("val1"), put3);
    System.out.println("Put applied: " + res4); 

The last call in the example will throw the following error:

Exception in thread "main" org.apache.hadoop.hbase.DoNotRetryIOException: 
 Action's getRow must match the passed row

Compare-and-set (CAS) operations are very powerful, especially in distributed systems, with even more decoupled client processes. In providing these calls, HBase sets itself apart from other architectures that give no means to reason about concurrent updates performed by multiple, independent clients.

First, the method that is used to retrieve specific values from an HBase table:

Result get(Get get) throws IOException

Similar to the Put class for the put() call, there is a matching Get class used by the aforementioned get() function. As another similarity, you will have to provide a row key when creating an instance of Get, using one of these constructors:

Get(byte[] row)
Get(byte[] row, RowLock rowLock)

Each constructor takes a row parameter specifying the row you want to access, while the second constructor adds an optional rowLock parameter, allowing you to hand in your own locks. And, similar to the put operations, you have methods to specify rather broad criteria to find what you are looking for—or to specify everything down to exact coordinates for a single cell:

Get addFamily(byte[] family)
Get addColumn(byte[] family, byte[] qualifier)
Get setTimeRange(long minStamp, long maxStamp) throws IOException
Get setTimeStamp(long timestamp)
Get setMaxVersions()
Get setMaxVersions(int maxVersions) throws IOException

The addFamily() call narrows the request down to the given column family. It can be called multiple times to add more than one family. The same is true for the addColumn() call. Here you can add an even narrower address space: the specific column. Then there are methods that let you set the exact timestamp you are looking for—or a time range to match those cells that fall inside it.

Lastly, there are methods that allow you to specify how many versions you want to retrieve, given that you have not set an exact timestamp. By default, this is set to 1, meaning that the get() call returns the most current match only. If you are in doubt, use getMaxVersions() to check what it is set to. The setMaxVersions() without a parameter sets the number of versions to return to Integer.MAX_VALUE—which is also the maximum number of versions you can configure in the column family descriptor, and therefore tells the API to return every available version of all matching cells (in other words, up to what is set at the column family level).

The Get class provides additional calls, which are listed in Table 3-4 for your perusal.

As mentioned earlier, HBase provides us with a helper class named Bytes that has many static methods to convert Java types into byte[] arrays. It also can do the same in reverse: as you are retrieving data from HBase—for example, one of the rows stored previously—you can make use of these helper functions to convert the byte[] data back into Java types. Here is a short list of what it offers, continued from the earlier discussion:

static String toString(byte[] b)
static boolean toBoolean(byte[] b)
static long toLong(byte[] bytes)
static float toFloat(byte[] bytes)
static int toInt(byte[] bytes)
...

Example 3-8 shows how this is all put together.

    Configuration conf = HBaseConfiguration.create(); 
    HTable table = new HTable(conf, "testtable"); 
    Get get = new Get(Bytes.toBytes("row1")); 
    get.addColumn(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1")); 
    Result result = table.get(get); 
    byte[] val = result.getValue(Bytes.toBytes("colfam1"),
      Bytes.toBytes("qual1")); 
    System.out.println("Value: " + Bytes.toString(val)); 

If you are running this example after, say Example 3-2, you should get this as the output:

Value: val1

The output is not very spectacular, but it shows that the basic operation works. The example also only adds the specific column to retrieve, relying on the default for maximum versions being returned set to 1. The call to get() returns an instance of the Result class, which you will learn about next.

When you retrieve data using the get() calls, you receive an instance of the Result class that contains all the matching cells. It provides you with the means to access everything that was returned from the server for the given row and matching the specified query, such as column family, column qualifier, timestamp, and so on.

There are utility methods you can use to ask for specific results—just as Example 3-8 used earlier—using more concrete dimensions. If you have, for example, asked the server to return all columns of one specific column family, you can now ask for specific columns within that family. In other words, you need to call get() with just enough concrete information to be able to process the matching data on the client side. The functions provided are:

byte[] getValue(byte[] family, byte[] qualifier)
byte[] value()
byte[] getRow()
int size()
boolean isEmpty()
KeyValue[] raw()
List<KeyValue> list()

The getValue() call allows you to get the data for a specific cell stored in HBase. As you cannot specify what timestamp—in other words, version—you want, you get the newest one. The value() call makes this even easier by returning the data for the newest cell in the first column found. Since columns are also sorted lexicographically on the server, this would return the value of the column with the column name (including family and qualifier) sorted first.

You saw getRow() before: it returns the row key, as specified when creating the current instance of the Get class. size() is returning the number of KeyValue instances the server has returned. You may use this call—or isEmpty(), which checks if size() returns a number greater than zero—to check in your own client code if the retrieval call returned any matches.

Access to the raw, low-level KeyValue instances is provided by the raw() method, returning the array of KeyValue instances backing the current Result instance. The list() call simply converts the array returned by raw() into a List instance, giving you convenience by providing iterator access, for example. The created list is backed by the original array of KeyValue instances.

Another set of accessors is provided which are more column-oriented:

List<KeyValue> getColumn(byte[] family, byte[] qualifier)
KeyValue getColumnLatest(byte[] family, byte[] qualifier)
boolean containsColumn(byte[] family, byte[] qualifier)

Here you ask for multiple values of a specific column, which solves the issue pointed out earlier, that is, how to get multiple versions of a given column. The number returned obviously is bound to the maximum number of versions you have specified when configuring the Get instance, before the call to get(), with the default being set to 1. In other words, the returned list contains zero (in case the column has no value for the given row) or one entry, which is the newest version of the value. If you have specified a value greater than the default of 1 version to be returned, it could be any number, up to the specified maximum.

The getColumnLatest() method is returning the newest cell of the specified column, but in contrast to getValue(), it does not return the raw byte array of the value but the full KeyValue instance instead. This may be useful when you need more than just the data. The containsColumn() is a convenience method to check if there was any cell returned in the specified column.

There is a third set of methods that provide access to the returned data from the get request. These are map-oriented and look like this:

NavigableMap<byte[], NavigableMap<byte[], 
  NavigableMap<Long, byte[]>>> getMap()
NavigableMap<byte[], 
  NavigableMap<byte[], byte[]>> getNoVersionMap()
NavigableMap<byte[], byte[]> getFamilyMap(byte[] family)

The most generic call, named getMap(), returns the entire result set in a Java Map class instance that you can iterate over to access all the values. The getNoVersionMap() does the same while only including the latest cell for each column. Finally, the getFamilyMap() lets you select the KeyValue instances for a specific column family only—but including all versions, if specified.

Use whichever access method of Result matches your access pattern; the data has already been moved across the network from the server to your client process, so it is not incurring any other performance or resource penalties.

keyvalues={row-2/colfam1:col-5/1300802024293/Put/vlen=7, 
           row-2/colfam2:col-33/1300802024325/Put/vlen=8}

keyvalues=NONE

Another similarity to the put() calls is that you can ask for more than one row using a single request. This allows you to quickly and efficiently retrieve related—but also completely random, if required—data from the remote servers.

The method provided by the API has the following signature:

Result[] get(List<Get> gets) throws IOException

Using this call is straightforward, with the same approach as seen earlier: you need to create a list that holds all instances of the Get class you have prepared. This list is handed into the call and you will be returned an array of equal size holding the matching Result instances. Example 3-9 brings this together, showing two different approaches to accessing the data.

    byte[] cf1 = Bytes.toBytes("colfam1");
    byte[] qf1 = Bytes.toBytes("qual1");
    byte[] qf2 = Bytes.toBytes("qual2"); 
    byte[] row1 = Bytes.toBytes("row1");
    byte[] row2 = Bytes.toBytes("row2");

    List<Get> gets = new ArrayList<Get>();  

    Get get1 = new Get(row1);
    get1.addColumn(cf1, qf1);
    gets.add(get1);

    Get get2 = new Get(row2);
    get2.addColumn(cf1, qf1); 
    gets.add(get2);

    Get get3 = new Get(row2);
    get3.addColumn(cf1, qf2);
    gets.add(get3);

    Result[] results = table.get(gets); 

    System.out.println("First iteration...");
    for (Result result : results) {
      String row = Bytes.toString(result.getRow());
      System.out.print("Row: " + row + " ");
      byte[] val = null;
      if (result.containsColumn(cf1, qf1)) { 
        val = result.getValue(cf1, qf1);
        System.out.println("Value: " + Bytes.toString(val));
      }
      if (result.containsColumn(cf1, qf2)) {
        val = result.getValue(cf1, qf2);
        System.out.println("Value: " + Bytes.toString(val));
      }
    }

    System.out.println("Second iteration...");
    for (Result result : results) {
      for (KeyValue kv : result.raw()) {
        System.out.println("Row: " + Bytes.toString(kv.getRow()) + 
          " Value: " + Bytes.toString(kv.getValue()));
      }
    }

Assuming that you execute Example 3-4 just before you run Example 3-9, you should see something like this on the command line:

First iteration...
Row: row1 Value: val1
Row: row2 Value: val2
Row: row2 Value: val3
Second iteration...
Row: row1 Value: val1
Row: row2 Value: val2
Row: row2 Value: val3

Both iterations return the same values, showing that you have a number of choices on how to access them, once you have received the results. What you have not yet seen is how errors are reported back to you. This differs from what you learned in List of Puts. The get() call either returns the said array, matching the same size as the given list by the gets parameter, or throws an exception. Example 3-10 showcases this behavior.

    List<Get> gets = new ArrayList<Get>();

    Get get1 = new Get(row1);
    get1.addColumn(cf1, qf1);
    gets.add(get1);

    Get get2 = new Get(row2);
    get2.addColumn(cf1, qf1); 
    gets.add(get2);

    Get get3 = new Get(row2);
    get3.addColumn(cf1, qf2);
    gets.add(get3);

    Get get4 = new Get(row2);
    get4.addColumn(Bytes.toBytes("BOGUS"), qf2);
    gets.add(get4); 

    Result[] results = table.get(gets); 

    System.out.println("Result count: " + results.length); 

Executing this example will abort the entire get() operation, throwing the following (or similar) error, and not returning a result at all:

org.apache.hadoop.hbase.client.RetriesExhaustedWithDetailsException: 
 Failed 1 action: NoSuchColumnFamilyException: 1 time, 
 servers with issues: 10.0.0.57:51640,

One way to have more control over how the API handles partial faults is to use the batch() operations discussed in Batch Operations.

There are a few more calls that you can use from your code to retrieve or check your stored data. The first is:

boolean exists(Get get) throws IOException

You can set up a Get instance, just like you do when using the get() calls of HTable. Instead of having to retrieve the data from the remote servers, using an RPC, to verify that it actually exists, you can employ this call because it only returns a boolean flag indicating that same fact.

Sometimes it might be necessary to find a specific row, or the one just before the requested row, when retrieving data. The following call can help you find a row using these semantics:

Result getRowOrBefore(byte[] row, byte[] family) throws IOException

You need to specify the row you are looking for, and a column family. The latter is required because, in HBase, which is a column-oriented database, there is no row if there are no columns. Specifying a family name tells the servers to check if the row searched for has any values in a column contained in the given family.

The returned instance of the Result class can be used to retrieve the found row key. This should be either the exact row you were asking for, or the one preceding it. If there is no match at all, the call returns null. Example 3-11 uses the call to find the rows you created using the put examples earlier.

    Result result1 = table.getRowOrBefore(Bytes.toBytes("row1"), 
      Bytes.toBytes("colfam1"));
    System.out.println("Found: " + Bytes.toString(result1.getRow())); 

    Result result2 = table.getRowOrBefore(Bytes.toBytes("row99"), 
      Bytes.toBytes("colfam1"));
    System.out.println("Found: " + Bytes.toString(result2.getRow())); 

    for (KeyValue kv : result2.raw()) {
      System.out.println("  Col: " + Bytes.toString(kv.getFamily()) + 
        "/" + Bytes.toString(kv.getQualifier()) +
        ", Value: " + Bytes.toString(kv.getValue()));
    }

    Result result3 = table.getRowOrBefore(Bytes.toBytes("abc"), 
      Bytes.toBytes("colfam1"));
    System.out.println("Found: " + result3); 

Assuming you ran Example 3-4 just before this code, you should see output similar or equal to the following:

Found: row1
Found: row2
  Col: colfam1/qual1, Value: val2
  Col: colfam1/qual2, Value: val3
Found: null

The first call tries to find a matching row and succeeds. The second call uses a large number postfix to find the last stored row, starting with the prefix row-. It did find row-2 accordingly. Lastly, the example tries to find row abc, which sorts before the rows the put example added, using the row- prefix, and therefore does not exist, nor matches any previous row keys. The returned result is then null and indicates the missed lookup.

What is interesting is the loop to print out the data that was returned along with the matching row. You can see from the preceding code that all columns of the specified column family were returned, including their latest values. You could use this call to quickly retrieve all the latest values from an entire column family—in other words, all columns contained in the given column family—based on a specific sorting pattern. For example, assume our put() example, which is using row- as the prefix for all keys. Calling getRowOrBefore() with a row set to row-999999999 will always return the row that is, based on the lexicographical sorting, placed at the end of the table.

The variant of the delete() call that takes a single Delete instance is:

void delete(Delete delete) throws IOException

Just as with the get() and put() calls you saw already, you will have to create a Delete instance and then add details about the data you want to remove. The constructors are:

Delete(byte[] row)
Delete(byte[] row, long timestamp, RowLock rowLock)

You need to provide the row you want to modify, and optionally provide a rowLock, an instance of RowLock to specify your own lock details, in case you want to modify the same row more than once subsequently. Otherwise, you would be wise to narrow down what you want to remove from the given row, using one of the following methods:

Delete deleteFamily(byte[] family)
Delete deleteFamily(byte[] family, long timestamp)
Delete deleteColumns(byte[] family, byte[] qualifier)
Delete deleteColumns(byte[] family, byte[] qualifier, long timestamp)
Delete deleteColumn(byte[] family, byte[] qualifier)
Delete deleteColumn(byte[] family, byte[] qualifier, long timestamp)
void setTimestamp(long timestamp)

You do have a choice to narrow in on what to remove using four types of calls. First you can use the deleteFamily() methods to remove an entire column family, including all contained columns. You have the option to specify a timestamp that triggers more specific filtering of cell versions. If specified, the timestamp matches the same and all older versions of all columns.

The next type is deleteColumns(), which operates on exactly one column and deletes either all versions of that cell when no timestamp is given, or all matching and older versions when a timestamp is specified.

The third type is similar, using deleteColumn(). It also operates on a specific, given column only, but deletes either the most current or the specified version, that is, the one with the matching timestamp.

Finally, there is setTimestamp(), which is not considered when using any of the other three types of calls. But if you do not specify either a family or a column, this call can make the difference between deleting the entire row or just all contained columns, in all column families, that match or have an older timestamp compared to the given one. Table 3-5 shows the functionality in a matrix to make the semantics more readable.

The Delete class provides additional calls, which are listed in Table 3-6 for your reference.

Example 3-12 shows how to use the single delete() call from client code.

    Delete delete = new Delete(Bytes.toBytes("row1")); 

    delete.setTimestamp(1); 


    delete.deleteColumn(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"), 1); 

    delete.deleteColumns(Bytes.toBytes("colfam2"), Bytes.toBytes("qual1")); 
    delete.deleteColumns(Bytes.toBytes("colfam2"), Bytes.toBytes("qual3"), 15); 

    delete.deleteFamily(Bytes.toBytes("colfam3")); 
    delete.deleteFamily(Bytes.toBytes("colfam3"), 3); 

    table.delete(delete); 

    table.close();

The example lists all the different calls you can use to parameterize the delete() operation. It does not make too much sense to call them all one after another like this. Feel free to comment out the various delete calls to see what is printed on the console.

Setting the timestamp for the deletes has the effect of only matching the exact cell, that is, the matching column and value with the exact timestamp. On the other hand, not setting the timestamp forces the server to retrieve the latest timestamp on the server side on your behalf. This is slower than performing a delete with an explicit timestamp.

If you attempt to delete a cell with a timestamp that does not exist, nothing happens. For example, given that you have two versions of a column, one at version 10 and one at version 20, deleting from this column with version 15 will not affect either existing version.

Another note to be made about the example is that it showcases custom versioning. Instead of relying on timestamps, implicit or explicit ones, it uses sequential numbers, starting with 1. This is perfectly valid, although you are forced to always set the version yourself, since the servers do not know about your schema and would use epoch-based timestamps instead.

Another example of using custom versioning can be found in Search Integration.

The list-based delete() call works very similarly to the list-based put(). You need to create a list of Delete instances, configure them, and call the following method:

void delete(List<Delete> deletes) throws IOException

Example 3-13 shows where three different rows are affected during the operation, deleting various details they contain. When you run this example, you will see a printout of the before and after states of the delete. The output is printing the raw KeyValue instances, using KeyValue.toString().

    List<Delete> deletes = new ArrayList<Delete>(); 

    Delete delete1 = new Delete(Bytes.toBytes("row1"));
    delete1.setTimestamp(4); 
    deletes.add(delete1);

    Delete delete2 = new Delete(Bytes.toBytes("row2"));
    delete2.deleteColumn(Bytes.toBytes("colfam1"), Bytes.toBytes("qual1")); 
    delete2.deleteColumns(Bytes.toBytes("colfam2"), Bytes.toBytes("qual3"), 5); 
    deletes.add(delete2);

    Delete delete3 = new Delete(Bytes.toBytes("row3"));
    delete3.deleteFamily(Bytes.toBytes("colfam1")); 
    delete3.deleteFamily(Bytes.toBytes("colfam2"), 3); 
    deletes.add(delete3);

    table.delete(deletes); 

    table.close();

The output you should see is:^[54]

Before delete call...
KV: row1/colfam1:qual1/2/Put/vlen=4, Value: val2
KV: row1/colfam1:qual1/1/Put/vlen=4, Value: val1
KV: row1/colfam1:qual2/4/Put/vlen=4, Value: val4
KV: row1/colfam1:qual2/3/Put/vlen=4, Value: val3
KV: row1/colfam1:qual3/6/Put/vlen=4, Value: val6
KV: row1/colfam1:qual3/5/Put/vlen=4, Value: val5

KV: row1/colfam2:qual1/2/Put/vlen=4, Value: val2
KV: row1/colfam2:qual1/1/Put/vlen=4, Value: val1
KV: row1/colfam2:qual2/4/Put/vlen=4, Value: val4
KV: row1/colfam2:qual2/3/Put/vlen=4, Value: val3
KV: row1/colfam2:qual3/6/Put/vlen=4, Value: val6
KV: row1/colfam2:qual3/5/Put/vlen=4, Value: val5

KV: row2/colfam1:qual1/2/Put/vlen=4, Value: val2
KV: row2/colfam1:qual1/1/Put/vlen=4, Value: val1
KV: row2/colfam1:qual2/4/Put/vlen=4, Value: val4
KV: row2/colfam1:qual2/3/Put/vlen=4, Value: val3
KV: row2/colfam1:qual3/6/Put/vlen=4, Value: val6
KV: row2/colfam1:qual3/5/Put/vlen=4, Value: val5

KV: row2/colfam2:qual1/2/Put/vlen=4, Value: val2
KV: row2/colfam2:qual1/1/Put/vlen=4, Value: val1
KV: row2/colfam2:qual2/4/Put/vlen=4, Value: val4
KV: row2/colfam2:qual2/3/Put/vlen=4, Value: val3
KV: row2/colfam2:qual3/6/Put/vlen=4, Value: val6
KV: row2/colfam2:qual3/5/Put/vlen=4, Value: val5

KV: row3/colfam1:qual1/2/Put/vlen=4, Value: val2
KV: row3/colfam1:qual1/1/Put/vlen=4, Value: val1
KV: row3/colfam1:qual2/4/Put/vlen=4, Value: val4
KV: row3/colfam1:qual2/3/Put/vlen=4, Value: val3
KV: row3/colfam1:qual3/6/Put/vlen=4, Value: val6
KV: row3/colfam1:qual3/5/Put/vlen=4, Value: val5

KV: row3/colfam2:qual1/2/Put/vlen=4, Value: val2
KV: row3/colfam2:qual1/1/Put/vlen=4, Value: val1
KV: row3/colfam2:qual2/4/Put/vlen=4, Value: val4
KV: row3/colfam2:qual2/3/Put/vlen=4, Value: val3
KV: row3/colfam2:qual3/6/Put/vlen=4, Value: val6
KV: row3/colfam2:qual3/5/Put/vlen=4, Value: val5

After delete call...
KV: row1/colfam1:qual3/6/Put/vlen=4, Value: val6
KV: row1/colfam1:qual3/5/Put/vlen=4, Value: val5

KV: row1/colfam2:qual3/6/Put/vlen=4, Value: val6
KV: row1/colfam2:qual3/5/Put/vlen=4, Value: val5

KV: row2/colfam1:qual1/1/Put/vlen=4, Value: val1
KV: row2/colfam1:qual2/4/Put/vlen=4, Value: val4
KV: row2/colfam1:qual2/3/Put/vlen=4, Value: val3
KV: row2/colfam1:qual3/6/Put/vlen=4, Value: val6
KV: row2/colfam1:qual3/5/Put/vlen=4, Value: val5

KV: row2/colfam2:qual1/2/Put/vlen=4, Value: val2
KV: row2/colfam2:qual1/1/Put/vlen=4, Value: val1
KV: row2/colfam2:qual2/4/Put/vlen=4, Value: val4
KV: row2/colfam2:qual2/3/Put/vlen=4, Value: val3
KV: row2/colfam2:qual3/6/Put/vlen=4, Value: val6

KV: row3/colfam2:qual2/4/Put/vlen=4, Value: val4
KV: row3/colfam2:qual3/6/Put/vlen=4, Value: val6
KV: row3/colfam2:qual3/5/Put/vlen=4, Value: val5

The deleted original data is highlighted in the Before delete call... block. All three rows contain the same data, composed of two column families, three columns in each family, and two versions for each column.

The example code first deletes, from the entire row, everything up to version 4. This leaves the columns with versions 5 and 6 as the remainder of the row content.

It then goes about and uses the two different column-related delete calls on row2 to remove the newest cell in the column named colfam1:qual1, and subsequently every cell with a version of 5 and older—in other words, those with a lower version number—from colfam1:qual3. Here you have only one matching cell, which is removed as expected in due course.

Lastly, operating on row-3, the code removes the entire column family colfam1, and then everything with a version of 3 or less from colfam2. During the execution of the example code, you will see the printed KeyValue details, using something like this:

System.out.println("KV: " + kv.toString() +
          ", Value: " + Bytes.toString(kv.getValue()))

By now you are familiar with the usage of the Bytes class, which is used to print out the value of the KeyValue instance, as returned by the getValue() method. This is necessary because the KeyValue.toString() output (as explained in The KeyValue class) is not printing out the actual value, but rather the key part only. The toString() does not print the value since it could be very large.

Here, the example code inserts the column values, and therefore knows that these are short and human-readable; hence it is safe to print them out on the console as shown. You could use the same mechanism in your own code for debugging purposes.

Please refer to the entire example code in the accompanying source code repository for this book. You will see how the data is inserted and retrieved to generate the discussed output.

What is left to talk about is the error handling of the list-based delete() call. The handed-in deletes parameter, that is, the list of Delete instances, is modified to only contain the failed delete instances when the call returns. In other words, when everything has succeeded, the list will be empty. The call also throws the exception—if there was one—reported from the remote servers. You will have to guard the call using a try/catch, for example, and react accordingly. Example 3-14 may serve as a starting point.

    Delete delete4 = new Delete(Bytes.toBytes("row2"));
    delete4.deleteColumn(Bytes.toBytes("BOGUS"), Bytes.toBytes("qual1")); 
    deletes.add(delete4);

    try {
      table.delete(deletes); 
    } catch (Exception e) {
      System.err.println("Error: " + e); 
    }
    table.close();

    System.out.println("Deletes length: " + deletes.size()); 
    for (Delete delete : deletes) {
      System.out.println(delete); 
    }

Example 3-14 modifies Example 3-13 but adds an erroneous delete detail: it inserts a BOGUS column family name. The output is the same as that for Example 3-13, but has some additional details printed out in the middle part:

Before delete call...
KV: row1/colfam1:qual1/2/Put/vlen=4, Value: val2
KV: row1/colfam1:qual1/1/Put/vlen=4, Value: val1
...
KV: row3/colfam2:qual3/6/Put/vlen=4, Value: val6
KV: row3/colfam2:qual3/5/Put/vlen=4, Value: val5

Error: org.apache.hadoop.hbase.client.RetriesExhaustedWithDetailsException: 
  Failed 1 action: NoSuchColumnFamilyException: 1 time, 
  servers with issues: 10.0.0.43:59057, 
Deletes length: 1
row=row2, ts=9223372036854775807, families={(family=BOGUS, keyvalues= 
  (row2/BOGUS:qual1/9223372036854775807/Delete/vlen=0)}

After delete call...
KV: row1/colfam1:qual3/6/Put/vlen=4, Value: val6
KV: row1/colfam1:qual3/5/Put/vlen=4, Value: val5
...
KV: row3/colfam2:qual3/6/Put/vlen=4, Value: val6
KV: row3/colfam2:qual3/5/Put/vlen=4, Value: val5

As expected, the list contains one remaining Delete instance: the one with the bogus column family. Printing out the instance—Java uses the implicit toString() method when printing an object—reveals the internal details of the failed delete. The important part is the family name being the obvious reason for the failure. You can use this technique in your own code to check why an operation has failed. Often the reasons are rather obvious indeed.

Finally, note the exception that was caught and printed out in the catch statement of the example. It is the same RetriesExhaustedWithDetailsException you saw twice already. It reports the number of failed actions plus how often it did retry to apply them, and on which server. An advanced task that you will learn about in later chapters is how to verify and monitor servers so that the given server address could be useful to find the root cause of the failure.

You saw in Atomic compare-and-set how to use an atomic, conditional operation to insert data into a table. There is an equivalent call for deletes that gives you access to server-side, read-and-modify functionality:

boolean checkAndDelete(byte[] row, byte[] family, byte[] qualifier,
  byte[] value, Delete delete) throws IOException

You need to specify the row key, column family, qualifier, and value to check before the actual delete operation is performed. Should the test fail, nothing is deleted and the call returns a false. If the check is successful, the delete is applied and true is returned. Example 3-15 shows this in context.

    Delete delete1 = new Delete(Bytes.toBytes("row1"));
    delete1.deleteColumns(Bytes.toBytes("colfam1"), Bytes.toBytes("qual3")); 

    boolean res1 = table.checkAndDelete(Bytes.toBytes("row1"),
      Bytes.toBytes("colfam2"), Bytes.toBytes("qual3"), null, delete1); 
    System.out.println("Delete successful: " + res1); 

    Delete delete2 = new Delete(Bytes.toBytes("row1"));
    delete2.deleteColumns(Bytes.toBytes("colfam2"), Bytes.toBytes("qual3")); 
    table.delete(delete2);

    boolean res2 = table.checkAndDelete(Bytes.toBytes("row1"),
      Bytes.toBytes("colfam2"), Bytes.toBytes("qual3"), null, delete1); 
    System.out.println("Delete successful: " + res2); 

    Delete delete3 = new Delete(Bytes.toBytes("row2"));
    delete3.deleteFamily(Bytes.toBytes("colfam1")); 

    try{
      boolean res4 = table.checkAndDelete(Bytes.toBytes("row1"),
        Bytes.toBytes("colfam1"), Bytes.toBytes("qual1"), 
        Bytes.toBytes("val1"), delete3);
      System.out.println("Delete successful: " + res4); 
    } catch (Exception e) {
      System.err.println("Error: " + e);
    }

The entire output of the example should look like this:

Before delete call...
KV: row1/colfam1:qual1/2/Put/vlen=4, Value: val2
KV: row1/colfam1:qual1/1/Put/vlen=4, Value: val1
KV: row1/colfam1:qual2/4/Put/vlen=4, Value: val4
KV: row1/colfam1:qual2/3/Put/vlen=4, Value: val3
KV: row1/colfam1:qual3/6/Put/vlen=4, Value: val6
KV: row1/colfam1:qual3/5/Put/vlen=4, Value: val5
KV: row1/colfam2:qual1/2/Put/vlen=4, Value: val2
KV: row1/colfam2:qual1/1/Put/vlen=4, Value: val1
KV: row1/colfam2:qual2/4/Put/vlen=4, Value: val4
KV: row1/colfam2:qual2/3/Put/vlen=4, Value: val3
KV: row1/colfam2:qual3/6/Put/vlen=4, Value: val6
KV: row1/colfam2:qual3/5/Put/vlen=4, Value: val5
Delete successful: false
Delete successful: true
After delete call...
KV: row1/colfam1:qual1/2/Put/vlen=4, Value: val2
KV: row1/colfam1:qual1/1/Put/vlen=4, Value: val1
KV: row1/colfam1:qual2/4/Put/vlen=4, Value: val4
KV: row1/colfam1:qual2/3/Put/vlen=4, Value: val3
KV: row1/colfam2:qual1/2/Put/vlen=4, Value: val2
KV: row1/colfam2:qual1/1/Put/vlen=4, Value: val1
KV: row1/colfam2:qual2/4/Put/vlen=4, Value: val4
KV: row1/colfam2:qual2/3/Put/vlen=4, Value: val3
Error: org.apache.hadoop.hbase.DoNotRetryIOException: 
  org.apache.hadoop.hbase.DoNotRetryIOException: 
    Action's getRow must match the passed row
...

Using null as the value parameter triggers the nonexistence test, that is, the check is successful if the column specified does not exist. Since the example code inserts the checked column before the check is performed, the test will initially fail, returning false and aborting the delete operation.

The column is then deleted by hand and the check-and-modify call is run again. This time the check succeeds and the delete is applied, returning true as the overall result.

Just as with the put-related CAS call, you can only perform the check-and-modify on the same row. The example attempts to check on one row key while the supplied instance of Delete points to another. An exception is thrown accordingly, once the check is performed. It is allowed, though, to check across column families—for example, to have one set of columns control how the filtering is done for another set of columns.

This example cannot justify the importance of the check-and-delete operation. In distributed systems, it is inherently difficult to perform such operations reliably, and without incurring performance penalties caused by external locking approaches, that is, where the atomicity is guaranteed by the client taking out exclusive locks on the entire row. When the client goes away during the locked phase the server has to rely on lease recovery mechanisms ensuring that these rows are eventually unlocked again. They also cause additional RPCs to occur, which will be slower than a single, server-side operation.