Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 36 ยท Shell and Basic Operations

Shell: Put, Get and Delete

Write, read and remove data with the HBase shell: put with timestamps, get with columns, versions and time ranges, delete and deleteall, counters with incr, and append.

Once a table exists, three commands do most of the daily work: put writes a cell, get reads one row, and delete removes data. This lesson covers each with its options, plus the lesser known incr, append and deleteall. Everything here is read-only listings of the real shell, paired with a runnable Java stand-in that follows the same semantics (versions, newest-first reads, tombstones).

The examples use a table created like this:

Terminal
create 'users', {NAME => 'info', VERSIONS => 3}, 'stats'

put

The pattern is put 'table', 'row key', 'family:qualifier', 'value':

Terminal
put 'users', 'u001', 'info:name', 'Jon Snow'
put 'users', 'u001', 'info:city', 'Oslo'
put 'users', 'u002', 'info:name', 'Aisha'

Each put writes one cell. If the cell exists, a new version is added with the current time as its timestamp. You may pass your own timestamp (milliseconds) as a fifth argument:

Terminal
put 'users', 'u001', 'info:city', 'Bergen', 1700000000000

Quoted values are sent as UTF-8 strings. An unquoted Ruby integer is sent as an 8-byte number instead, which is how counters are stored (see incr below), so quote every value that is meant to be text.

get

get reads one row and returns its newest cells:

Terminal
get 'users', 'u001'

The result is a table with columns COLUMN and CELL; each cell line shows the timestamp and the value (value=Oslo). Binary values are escaped as \x00-style bytes. To narrow the result:

Terminal
get 'users', 'u001', 'info:name'                                   # one column
get 'users', 'u001', {COLUMN => ['info:name', 'info:city']}        # several columns
get 'users', 'u001', {COLUMN => 'info', VERSIONS => 3}             # up to 3 versions, whole family
get 'users', 'u001', {TIMERANGE => [1699999999000, 1700000001000]} # only cells inside the range
get 'users', 'u001', {TIMESTAMP => 1700000000000}                  # exactly that timestamp
get 'users', 'u001', {FILTER => "ValueFilter(=, 'substring:Os')"}  # server-side filter

A time range is half-open: the lower bound is included, the upper bound is not. Asking for more VERSIONS than the family keeps returns only what exists.

Here is the logic of those options in Java. The stand-in keeps versions newest-first per cell and implements VERSIONS, TIMERANGE and exact TIMESTAMP reads.

Java Stand-in: put and get with versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

delete and deleteall

A delete never removes bytes immediately: it writes a tombstone (see Cells, Timestamps and Versions).

Terminal
delete 'users', 'u001', 'info:city'            # hide the column (marker at the current time)
delete 'users', 'u001', 'info:city', 1700000000000   # hide versions at or before this timestamp
deleteall 'users', 'u001', 'info:city'         # all versions of the column
deleteall 'users', 'u001'                      # the whole row, every family

In the shell, a column delete writes a tombstone with the timestamp you pass (the current time if you omit it), and that tombstone hides the column's versions at or before that timestamp. If a command's effect is unclear, run get with VERSIONS before and after.

The marker is also the reason for a classic surprise: a put with a timestamp older than a delete marker is silently hidden until a major compaction removes the marker.

Counters: incr and get_counter

HBase can increment a numeric cell atomically on the server, which makes counters safe under concurrency without a read-modify-write race:

Terminal
incr 'users', 'u001', 'stats:logins'          # adds 1 (creates the cell at 1 if absent)
incr 'users', 'u001', 'stats:logins', 5       # adds 5
get_counter 'users', 'u001', 'stats:logins'   # reads the counter as a number

A counter is stored as an 8-byte long, so a normal get shows it as binary escapes like \x00\x00\x00\x00\x00\x00\x00\x06. Use get_counter to see the number. Do not put a string into a counter cell and then incr it: the cell would not be 8 bytes and the increment fails.

The stand-in below shows why atomic increments matter. Ten threads each add 1000 times. With a plain read-modify-write, updates get lost; with an atomic increment they do not. The result of the first case varies between runs, so only the safe total is printed as expected.

Java Stand-in: atomic increments vs lost updates

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

append

append adds bytes to the end of an existing value, atomically, on the server:

Terminal
append 'users', 'u001', 'info:notes', ' | called'

It is rarely the best choice (the value keeps growing), but it avoids a client-side read-modify-write for log-like cells.

Checking and conditional writes

The shell has no check-and-put command, but the Java API does (checkAndMutate). The shell is for exploration; applications use the API in the Java API chapter.

Common mistakes

  • Forgetting quotes. put users, u001, ... is a Ruby error; every name is a quoted string.
  • Wrong separator. Columns are family:qualifier; the family must exist, or you get NoSuchColumnFamilyException.
  • Reading deleted data back. A tombstone hides it; use scan with RAW => true to see markers (next lesson).
  • Counting on string compare for numbers. Values are bytes; '9' > '10' as text.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does put do when the cell already has a value?

    Writes are appended as new versions; old versions are cleaned up by limits and compaction.
  2. 2. How do you read the three newest versions of info:city for a row?

    VERSIONS is an option hash key on get. It returns up to that many versions the family still stores.
  3. 3. Why use incr instead of get, add, put for a counter?

    A client-side read-modify-write can overwrite concurrent increments; incr avoids that.
  4. 4. What does deleteall 'users','u001' remove?

    deleteall with only a row key writes a delete-family tombstone for every family, hiding the whole row.
  5. 5. Why might a put with an old explicit timestamp not show up after a delete?

    Delete markers cover everything at or below their timestamp.

Summary

  • put table, row, family:qualifier, value [, ts] adds a new version; values are bytes.
  • get returns the newest cells of a row; use COLUMN, VERSIONS, TIMERANGE, TIMESTAMP and FILTER to narrow.
  • delete, deleteall write tombstones; data disappears physically at major compaction.
  • incr and get_counter give atomic server-side counters; append adds bytes to a value.
  • Quote every name and value, and use the Java API for conditional writes.

Next: Shell: Scan and Count