Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 36 ยท Architecture and Data Model

Cells, Timestamps and Versions

Learn how HBase cells keep several timestamped versions, how MAX_VERSIONS and TTL work, how deletes use tombstones, and how time-based reads behave.

In a relational database an UPDATE replaces the old value. HBase does not replace anything. Every write adds a new version of a cell, labelled with a timestamp, and the old versions stay until they are removed by a rule or by a compaction. This makes history cheap, but it also has traps, especially around deletes.

This lesson covers the cell coordinate, version limits, TTL, reads at a point in time, and tombstones. It builds on the structure from Tables, Rows, Column Families and Qualifiers.

The cell coordinate

A cell is addressed by four coordinates:

TEXT
(row key, column family, column qualifier, timestamp)  ->  value

The timestamp is a 64-bit number of milliseconds since the Unix epoch. By default the RegionServer fills it with its clock when the write arrives, but a client may supply its own. Cells are stored sorted with the newest timestamp first, so the latest version is the first one a read meets.

Versions

Each column family has a VERSIONS setting (called MAX_VERSIONS in the Java API) that says how many versions of each cell to keep. In HBase 2.x the default is 1, which means only the newest value survives compaction. If you want history, raise it when you create the family.

Terminal
create 'prices', {NAME => 'p', VERSIONS => 5}

A plain get returns the newest version only. To see more you ask for VERSIONS => n (shell) or readVersions(n) (Java). Older versions beyond the limit are removed lazily: they may still be visible until a flush or a major compaction runs. The limit is not an instantaneous guarantee.

Time-to-live (TTL)

A family can also have a TTL in seconds. Cells older than the TTL are treated as deleted and dropped at compaction. TTL is how you keep only "the last 30 days" without running a cleanup job:

Terminal
create 'metrics', {NAME => 'm', TTL => 2592000}

TTL compares the cell timestamp to the current time. So if you write your own old timestamps, they may expire immediately.

The stand-in below implements versions, a MAX_VERSIONS limit and TTL for a single column. Run it and watch the newest-first order and the cleanup step.

Java Stand-in: versions, max-versions and TTL

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.

Reading at a point in time

Because versions carry timestamps, you can ask for the data "as it was". A Get or Scan can be restricted with a time range [min, max) (minimum inclusive, maximum exclusive) or a single timestamp. HBase returns the newest version inside the range. In the Java client this is get.setTimeRange(min, max); in the shell it is TIMERANGE => [min, max].

Java
Get get = new Get(Bytes.toBytes("sku-42"));
get.addColumn(Bytes.toBytes("p"), Bytes.toBytes("price"));
get.setTimeRange(0L, 1_700_000_000_000L);   // value as of that instant
Result result = table.get(get);

The listing is read-only: it needs a running cluster. The following stand-in shows the logic, an "as of" query on a version list.

Java Stand-in: reading as of a timestamp

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.

Deletes are tombstones

HDFS files are never edited, so HBase cannot erase a cell from an existing HFile. A delete writes a tombstone marker. Reads then skip anything the marker covers. The data is physically removed only when a major compaction rewrites the files. There are four kinds of marker:

  • Delete a specific version of a cell (exact timestamp).
  • Delete column: all versions of one qualifier up to a timestamp.
  • Delete family: everything in a family up to a timestamp.
  • Delete family version: only the cells of a family at exactly one timestamp.

Two traps follow. First, a delete marker hides everything older than its timestamp, even future writes with older timestamps. If you write a cell with timestamp 100 after deleting up to 200, the new cell stays invisible until the tombstone is compacted away. Second, a table with many deletes and no major compaction becomes slow because scans must wade through tombstones.

Java Stand-in: a tombstone hides older 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.

Practical guidance

  • Leave VERSIONS at 1 unless you truly need history; every extra version costs space and scan time.
  • Do not use timestamps as a general-purpose second key. If you need many values per entity over time, put the time into the row key or the qualifier (see the Schema Design chapter of the HBase track).
  • Let the server assign timestamps unless you have a reason; mixing client clocks breaks ordering.
  • Plan major compactions (or rely on the periodic ones) when you delete heavily.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

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

    Writes never modify files in place. They add a newer version, and old ones are removed by limits and compaction.
  2. 2. In HBase 2.x, what is the default number of versions kept per cell?

    The default is 1. Increase VERSIONS on the family if you need history.
  3. 3. Why can a cell written after a delete still be invisible?

    A delete marker hides every cell at or below its timestamp, including those written later with older timestamps.
  4. 4. When are tombstones and expired cells physically removed?

    Files are immutable, so cleanup happens when compaction rewrites them.

Summary

  • A cell is (row, family, qualifier, timestamp) to value; newest versions sort first.
  • VERSIONS and TTL are family settings enforced lazily at compaction.
  • Gets and scans can filter by time range to read data as of a moment.
  • Deletes write tombstones that hide older cells until a major compaction.
  • Keep versions low and avoid abusing timestamps as keys.

Next: The Master and RegionServers