Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 36 ยท Projects and Practice

Project: A Messaging Inbox

Design an HBase schema for a chat and inbox system: row keys, reversed timestamps, unread counters, paging and an index table, built and tested on a Java stand-in.

Messaging was one of the first big HBase workloads: billions of messages, each read and written by key, with strict latency needs. In this project you design the schema for an inbox like a mail or chat service, then run it against a small in-memory stand-in of an HBase table written in Java.

HBase cannot run in the live editors. The stand-in below (MiniTable) implements just the parts we need: put, get, delete, range scan in key order and atomic increment. The real HBase 2.x client calls that correspond to each step are shown read-only. The design is what you would take to a real cluster.

Requirements

  1. A user opens the inbox and sees the newest 20 messages, paged ("older" loads the next 20).
  2. Open a conversation with another user: messages in time order.
  3. Show the unread count per user quickly.
  4. Mark a message as read; delete a message.
  5. Scale: 100 million users, avg. 5,000 messages each; hot users and bots exist.

Design from the queries

Following Schema Patterns we derive one table per access pattern.

Table inbox (query 1, 3, 4): one tall table; key = salt | userId | reversedTs | messageId.

  • userId first so one user's messages are contiguous: a prefix scan reads the inbox.
  • reversedTs = Long.MAX_VALUE - timestamp, so the newest message sorts first (Row Key Design).
  • messageId makes the key unique when two messages share a timestamp.
  • Salt is a single byte from hash(userId) % 16, so heavy users do not all land in one region (hotspotting); every query for one user knows its salt, so no fan-out is needed.
  • Family m (short name), qualifiers from, subject, body, read; VERSIONS => 1.

Table conversation (query 2): key = salt | userA | userB | ts where userA < userB (sorted so both sides use the same key), in time order.

Counters (query 3): row salt | userId in table counters, family c, qualifier unread, updated with atomic Increment.

flowchart LR
  S["Send message"] --> I1["inbox: recipient row"]
  S --> I2["inbox: sender 'sent' row"]
  S --> C["conversation row"]
  S --> N["counters: unread +1"]

One logical send is four writes: this is the price of single-read queries.

Build the stand-in

Java MiniTable and the inbox (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.

Check the output: page 1 shows messages 7, 6, 5 (newest first), page 2 shows 4, 3, 2, and the unread counter goes from 7 to 6 after marking one message read, even though markRead ran twice.

The real client calls (read-only)

Writing a message (one Put per row, Increment for the counter):

Java
byte[] key = Bytes.add(salt(to), Bytes.toBytes(to), Bytes.toBytes(Long.MAX_VALUE - ts), Bytes.toBytes(id));
Put put = new Put(key)
    .addColumn(M, FROM, Bytes.toBytes(from))
    .addColumn(M, SUBJECT, Bytes.toBytes(subject))
    .addColumn(M, READ, Bytes.toBytes(0));
inbox.put(put);
counters.incrementColumnValue(counterKey, C, UNREAD, 1L);

Reading a page:

Java
Scan scan = new Scan().withStartRow(startAfter, false)       // exclusive start = "after the last key"
                      .withStopRow(prefixStop)
                      .setLimit(20)
                      .setCaching(20);

Extend the design

Work through these on paper or in the stand-in:

  1. Atomicity: a crash after the inbox write and before the counter increment leaves the counter wrong. Add a nightly repair job, or recompute the counter by scanning when it looks suspicious. Could you use a single-row design to make the update atomic? (Row-level atomic mutations exist: RowMutations and checkAndMutate, but only within one row.)
  2. Search by sender: add an index table inbox_by_sender with key salt | user | sender | revTs | id and no payload, written alongside the inbox row.
  3. Large bodies: put big attachments in an object store or a separate family a with IS_MOB (medium objects) so scans of m do not read them.
  4. Retention: add a TTL on the family (TTL => 31536000) for messages that expire; tombstones from user deletes are purged at major compaction (Compactions and Flushes).
  5. Hot users: a bot receiving millions of messages makes one huge prefix. Bucket its key by month (user|month|revTs|id) so the scan crosses a small number of ranges.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is the timestamp stored reversed in the inbox key?

    Long.MAX_VALUE minus the time makes newer messages sort first within a user's prefix.
  2. 2. How is the next page fetched?

    HBase has no offset; the last returned key is the cursor for the next scan.
  3. 3. Why does the design write several rows for one message?

    Without joins or secondary indexes, each access pattern needs its own table or index rows.
  4. 4. What is the risk of updating the inbox row and the counter separately?

    Cross-row and cross-table operations are not atomic in HBase, so design for repair or tolerance.

Summary

  • Derive tables from the queries: inbox, conversation and counters.
  • Salt plus user prefix plus reversed timestamp gives newest-first pages without hotspots.
  • Page by cursor key, never by offset.
  • Multi-row updates are not atomic: plan repair jobs and idempotent operations.

Next: Project: Time-Series Metrics Store