2. (Optional) Configuring Off-heap Memory (BucketCache)

At this point, you have determined that you have enough physical memory on your servers to extend BlockCache beyond the JVM Heap. You have configured values for the JVM heap, LruBlockCache, and MemStore (shown in Figure 2, copied here for reference).

Next, configure and enable BucketCache. To do this, note the memory specifications and values in Configuring BlockCache, plus a few additional values shown in Figure 3 and in the following table.

Figure 3. Configuring BucketCache

In the following table, the first column refers to the elements in Figure 3. The second column describes each element and, if applicable, its associated variable or property name. The third column contains values and formulas.

The fourth column computes values based on the following sample configuration parameters:

  • 128 GB for the RegionServer process (there is additional memory available for other HDP processes)

  • Workload consists of 75% reads, 25% writes.

  • HBASE_HEAPSIZE = 20 GB (20480 MB)


Most of the following values are specified in megabytes; three are proportions.



Value or Formula



Total physical memory for RegionServer operations: on-heap plus off-heap ("direct") memory (MB)

(hardware dependent)



HBASE_HEAPSIZE (-Xmx) Maximum size of JVM heap (MB)

Recommendation: 20480



-XX:MaxDirectMemorySize Amount of off-heap ("direct") memory to allocate to HBase (MB)

A - B

131072 - 20480 = 110592


hfile.block.cache.size Proportion of maximum JVM heap size (HBASE_HEAPSIZE, -Xmx) to allocate to BlockCache. The sum of this value plus hbase.regionserver.global.memstore.size must not exceed 0.8.

(proportion of reads) * 0.8

0.75 * 0.8 = 0.6


Maximum amount of JVM heap to allocate to BlockCache (MB)

B * Dp

20480 * 0.6 = 12288


hbase.regionserver.global.memstore.size Proportion of maximum JVM heap size (HBASE_HEAPSIZE, -Xmx) to allocate to MemStore. The sum of this value plus hfile.block.cache.size must be less than or equal to 0.8.

0.8 - Dp

0.8 - 0.6 = 0.2


Amount of off-heap memory to reserve for other uses (DFSClient; MB)

Recommendation: 1024 to 2048



Amount of off-heap memory to allocate to BucketCache (MB)

C - F

110592 - 2048 = 108544

hbase.bucketcache.size Total amount of memory to allocate to BucketCache, on- and off-heap (MB)

Dm + G

12288 + 108544 = 120832

hbase.bucketcache.percentage.in.combinedcache The proportion of memory allocated to BucketCache (off-heap cache), relative to all BlockCache (on- and off-heap)

G / (Dm + G)

108544 / 120832 = 0.89830508474576

* Specified in Configuring BlockCache

After completing the steps in Configuring BlockCache, follow these steps to configure BucketCache.

  • In the hbase-env.sh file for each RegionServer, or in the hbase-env.sh file supplied to Ambari, set the -XX:MaxDirectMemorySize argument for HBASE_REGIONSERVER_OPTS to the amount of direct memory you wish to allocate to HBase. In the sample configuration, the value would be 110592m. (-XX:MaxDirectMemorySize accepts a number followed by a unit indicator; m indicates megabytes.)

    HBASE_OPTS="$HBASE_OPTS -XX:MaxDirectMemorySize=110592m"

  • In the hbase-site.xml file, specify BucketCache size and percentage. For the sample configuration, the values would be 120832 and 0.89830508474576, respectively. If you choose to round the proportion, round up. This will allocate space related to rounding error to the (larger) off-heap memory area.


  • In the hbase-site.xml file, set hbase.bucketcache.ioengine to offheap. This enables BucketCache.


  • Restart (or rolling restart) the cluster. It can take a minute or more to allocate BucketCache, depending on how much memory you are allocating. Check logs for error messages.