Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Schema Design

Row Key Design

Learn how to design HBase row keys: byte ordering, fixed-width numbers, composite keys, reversed timestamps and key length, with runnable Java stand-ins.

In HBase the row key is the only index you get for free. Every table is stored sorted by row key, every read is a lookup or a range scan over row keys, and every region is a contiguous slice of that sorted key space. A good row key makes your most important queries cheap. A bad one forces full-table scans or piles all your traffic onto one server.

This lesson covers the rules that decide what a row key should look like. The next lessons build on them: hotspotting and salting, column families and versions and schema patterns.

Apache HBase cannot run in the live editors on this site (it needs HDFS or a local filesystem, ZooKeeper and a JVM cluster). Real HBase client code is shown in read-only blocks. The runnable Java blocks are labelled stand-ins: a sorted in-memory map that behaves like an HBase table for ordering questions.

Rule 1: rows are sorted as raw bytes

HBase stores row keys as byte arrays and compares them lexicographically, byte by byte, as unsigned values. There is no notion of "number" or "date" at the storage layer. The key "10" is the two bytes 0x31 0x30, and it sorts before "9" (0x39) because 0x31 is smaller than 0x39.

That is why numbers stored as decimal text surprise newcomers. If you must keep numbers in a key, either use a fixed width with zero padding ("0009", "0010") or use Bytes.toBytes(long), which writes eight big-endian bytes and sorts correctly for non-negative values.

Java Byte order of keys (stand-in)

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.

The first listing puts row 10, row 100, row 11 before row 2. The padded and long listings are in numeric order. The last listing shows the catch with signed numbers: -1 is 0xFF...FF, which sorts after every positive number. If you need negative values, flip the sign bit before encoding.

Rule 2: put the most selective, most-queried prefix first

Because only a prefix of the key can be used to narrow a scan, order the key parts by how you query. For an order-history table, the question "show the orders of customer 42" means the key should start with the customer id:

TEXT
customerId | orderDate | orderId

A scan from customerId=42 to customerId=43 (exclusive) returns exactly that customer's orders, already sorted by date. The reverse order, orderDate | customerId, would force a scan across the whole table for one customer.

Real client code for that prefix scan looks like this (read-only, HBase 2.x client API):

Java
byte[] start = Bytes.add(Bytes.toBytes(42L), Bytes.toBytes(0L));
Scan scan = new Scan()
    .withStartRow(Bytes.toBytes(42L))       // inclusive
    .withStopRow(Bytes.toBytes(43L));       // exclusive
try (ResultScanner scanner = table.getScanner(scan)) {
    for (Result r : scanner) { /* one order per row */ }
}

Rule 3: composite keys need unambiguous separators

When you join several parts, the parts must not bleed into each other. A key "ab" + "c" and "a" + "bc" both become "abc". Two safe options:

  • Fixed-width parts (ids of known length, fixed-width numbers).
  • A separator byte such as 0x00 that cannot occur inside the parts.

Remember that a variable-length part makes the sort order depend on the separator. With a 0x00 separator, "a" + 0x00 + ... sorts before "ab" + 0x00 + ..., which is what you want.

Rule 4: use reversed timestamps for "latest first"

Rows sort ascending, so a plain timestamp puts the oldest event first. To read the newest events with a short scan, store Long.MAX_VALUE - timestamp in the key. The newest event then has the smallest number and sorts first.

Java Newest first with a reversed timestamp (stand-in)

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.

The output lists events #5, #4, #3 for ana, newest first, and never touches bob's rows. The start and stop keys are the prefix ana plus the separator byte and the separator plus one.

Rule 5: keep keys short

The row key is repeated in every cell of every row: once for each column, each version, in every HFile, in the WAL and in memory. A 100-byte key on a table with ten columns costs a kilobyte per row before any value is stored. Prefer compact binary encodings (an 8-byte long instead of a 19-character string), short surrogate ids and compression, but not at the cost of unreadable data you cannot debug.

flowchart LR
  K["Row key: 42 | reversed-ts | order-id"] --> C1["cf:status = shipped"]
  K --> C2["cf:total = 99.50"]
  K --> C3["cf:items = 3"]
  note1["The key is stored with EVERY cell"]
  K -.-> note1

A long key is paid for once per cell, not once per row.

Common mistakes

  • Starting the key with a monotonically increasing value (timestamp, auto-increment id). All new writes land on one region; see hotspotting.
  • Hashing the whole key and then being unable to scan ranges. Hashing is a tradeoff, not a default.
  • Storing business data that changes in the key. A row key cannot be updated: a "rename" is a delete plus a put.
  • Using a key so generic that one row grows without bound (one row per user with millions of columns).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does HBase compare two row keys?

    Row keys are byte arrays sorted lexicographically as unsigned bytes. HBase knows nothing about numbers or dates in keys.
  2. 2. Why does the decimal text key "10" sort before "9"?

    The first byte of "10" is 0x31 and "9" is 0x39, so the comparison is decided on the first byte.
  3. 3. You want the newest events of a user first. What key part helps?

    A reversed timestamp makes newer events get smaller numbers, so they sort first within the user prefix.
  4. 4. Why should row keys be short?

    Each cell carries its full row key, so key length multiplies across columns, versions and files.

Summary

  • Rows sort as unsigned bytes; only a key prefix can narrow a scan.
  • Zero-pad or binary-encode numbers; flip the sign bit for negatives.
  • Order composite key parts by how you query, and separate variable parts safely.
  • Use Long.MAX_VALUE - ts for newest-first reads.
  • Keep keys short; the key is repeated in every cell.

Next: Hotspotting, Salting and Hashing