Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 36 ยท Integration and Patterns

Bulk Loading HFiles

Load huge datasets into HBase fast by writing HFiles directly: the bulk load flow, ImportTsv, HFileOutputFormat2, region boundaries and pitfalls, with a Java model.

Putting a billion rows into HBase with the normal Put API works, but it pushes every cell through the write path: RPC, WAL, MemStore, flush, then compactions that rewrite the data again. It is slow, it loads the region servers and it can trigger write stalls. Bulk loading skips all of that. A batch job prepares the data as finished HFiles, sorted exactly as HBase stores them, and HBase simply adopts the files into the regions. No WAL, no MemStore, almost no load on the region servers.

HBase cannot run in the live editors. The commands and job code are read-only. The Java blocks are runnable models: they partition sorted data by region boundaries and show why the order matters.

The bulk load flow

flowchart LR
  A["Source data<br/>(CSV, Parquet, ...)"] --> B["Batch job (MapReduce or Spark)"]
  B -->|"sort by row key, partition by region"| C["HFiles on HDFS<br/>one dir per column family"]
  C -->|"completebulkload"| D["Region servers adopt files"]

Data never passes through the WAL or MemStore.

  1. Create the table, pre-split to the key distribution you expect (see hotspotting). The number of regions sets how many reducers write HFiles in parallel.
  2. Run a job that outputs HFiles. HFileOutputFormat2.configureIncrementalLoad reads the table's region boundaries and configures a TotalOrderPartitioner, so each reducer gets exactly one region's key range, in sorted order.
  3. Load the files with LoadIncrementalHFiles (older name) or BulkLoadHFiles (HBase 2.2+). It asks each region server to move the files into the region directories. If a file straddles a region boundary (because a region split meanwhile), the tool splits it and retries.

ImportTsv: the no-code route

For delimited text, HBase includes ImportTsv. It can write by Put or generate HFiles with -Dimporttsv.bulk.output:

TEXT
hbase org.apache.hadoop.hbase.mapreduce.ImportTsv \
  -Dimporttsv.separator=, \
  -Dimporttsv.columns=HBASE_ROW_KEY,d:status,d:ms \
  -Dimporttsv.bulk.output=/tmp/events-hfiles \
  events /data/events.csv

hbase org.apache.hadoop.hbase.tool.BulkLoadHFilesTool /tmp/events-hfiles events

importtsv.columns lists, in order, the CSV columns: one must be HBASE_ROW_KEY, the others are family:qualifier. The second command (completebulkload in older versions) hands the finished HFiles to the table.

A custom job (read-only)

Java
Job job = Job.getInstance(conf, "bulk-events");
job.setMapperClass(EventMapper.class);                 // emits (ImmutableBytesWritable rowKey, Put)
job.setMapOutputKeyClass(ImmutableBytesWritable.class);
job.setMapOutputValueClass(Put.class);

try (Connection c = ConnectionFactory.createConnection(conf);
     Table table = c.getTable(TableName.valueOf("events"));
     RegionLocator locator = c.getRegionLocator(TableName.valueOf("events"))) {
    HFileOutputFormat2.configureIncrementalLoad(job, table, locator);   // partitioner, reducers, sort
}
FileOutputFormat.setOutputPath(job, new Path("/tmp/events-hfiles"));
job.waitForCompletion(true);

BulkLoadHFiles.create(conf).bulkLoad(TableName.valueOf("events"), new Path("/tmp/events-hfiles"));

Spark can do the same: build (rowKey, cell) pairs, repartitionAndSortWithinPartitions with a partitioner that matches the region boundaries, and write with HFileOutputFormat2 through saveAsNewAPIHadoopFile. The HBase Spark connector wraps this as a bulkLoad helper.

Why sorting is mandatory

An HFile must contain cells in strict sorted order: row key, then family, qualifier and descending timestamp. A job that writes unsorted data produces a file HBase cannot use (the writer throws Added a key not lexically larger than previous). That is why the job ends with a total-order partition and a sort, which is also why a bulk load needs a reducer phase.

Java Partition and sort by region boundaries (model)

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.

If the HFile of a region held keys outside its range (for example because the table split after the job started), the load tool detects it, splits the file along the new boundaries and retries.

Gains and caveats

Bulk loads are far faster than Puts, often by an order of magnitude, and they avoid compaction storms because you write a few large files. Caveats:

  • No WAL: nothing to replay, but also no replication of those edits. A peer cluster will not receive bulk-loaded data unless the feature hbase.replication.bulkload.enabled is on (HBase 2.x), or you load into both clusters.
  • No coprocessor hooks (observers) run for the loaded rows, so a secondary index maintained by an observer misses them.
  • Timestamps: the job decides cell timestamps; use a consistent value (the job start time) so old data does not shadow newer writes.
  • Atomicity per file, not per load: a failure halfway leaves some regions loaded and others not. Make the load idempotent (same row keys) so rerunning is safe.
  • Disk space: the HFile directory is moved (renamed) into HBase when on the same filesystem; across filesystems the files are copied.
  • It suits initial loads, large backfills and periodic batch updates, not trickle writes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a bulk load bypass?

    Bulk loads write finished HFiles and add them to regions directly, skipping the WAL and MemStore.
  2. 2. Why does the job use region boundaries as the partitioner?

    HFiles must hold sorted keys that fall within one region's range.
  3. 3. Which is a known caveat of bulk loading?

    No WAL means no standard replication, and coprocessor hooks do not run for those rows.
  4. 4. What does ImportTsv's HBASE_ROW_KEY entry in importtsv.columns do?

    One column in the list must be HBASE_ROW_KEY; the rest are family:qualifier targets.

Summary

  • Bulk load = a batch job writes sorted HFiles per region, then HBase adopts them.
  • HFileOutputFormat2.configureIncrementalLoad sets up the partitioner from the table's region boundaries.
  • ImportTsv covers CSV loads without code.
  • Know the trade-offs: no WAL, no replication or observers by default, per-file atomicity.

Next: Project: A Messaging Inbox