HBASE-29585 Add row-level cache for the get operation

hbase-client/src/main/java/org/apache/hadoop/hbase/client/TableDescriptor.java

@@ -316,4 +316,11 @@ default boolean matchReplicationScope(boolean enabled) {
     }
     return !enabled;
   }
+
+  /**
+   * Checks whether row caching is enabled for this table. Note that row caching applies only at the
+   * entire row level, not at the column family level.
+   * @return {@code true} if row cache is enabled, otherwise {@code false}
+   */
+  boolean isRowCacheEnabled();
 }

hbase-client/src/main/java/org/apache/hadoop/hbase/client/TableDescriptorBuilder.java

@@ -227,6 +227,15 @@ public class TableDescriptorBuilder {
   private final static Map<String, String> DEFAULT_VALUES = new HashMap<>();
   private final static Set<Bytes> RESERVED_KEYWORDS = new HashSet<>();
 
+  /**
+   * Used by HBase Shell interface to access this metadata attribute which denotes if the row cache
+   * is enabled.
+   */
+  @InterfaceAudience.Private
+  public static final String ROW_CACHE_ENABLED = "ROW_CACHE_ENABLED";
+  private static final Bytes ROW_CACHE_ENABLED_KEY = new Bytes(Bytes.toBytes(ROW_CACHE_ENABLED));
+  private static final boolean DEFAULT_ROW_CACHE_ENABLED = false;
+
   static {
     DEFAULT_VALUES.put(MAX_FILESIZE, String.valueOf(HConstants.DEFAULT_MAX_FILE_SIZE));
     DEFAULT_VALUES.put(READONLY, String.valueOf(DEFAULT_READONLY));
@@ -565,6 +574,11 @@ public TableDescriptor build() {
     return new ModifyableTableDescriptor(desc);
   }
 
+  public TableDescriptorBuilder setRowCacheEnabled(boolean rowCacheEnabled) {
+    desc.setRowCacheEnabled(rowCacheEnabled);
+    return this;
+  }
+
   private static final class ModifyableTableDescriptor
     implements TableDescriptor, Comparable<ModifyableTableDescriptor> {
 
@@ -1510,6 +1524,15 @@ public Optional<String> getRegionServerGroup() {
         return Optional.empty();
       }
     }
+
+    @Override
+    public boolean isRowCacheEnabled() {
+      return getOrDefault(ROW_CACHE_ENABLED_KEY, Boolean::valueOf, DEFAULT_ROW_CACHE_ENABLED);
+    }
+
+    public ModifyableTableDescriptor setRowCacheEnabled(boolean enabled) {
+      return setValue(ROW_CACHE_ENABLED_KEY, Boolean.toString(enabled));
+    }
   }
 
   /**

hbase-common/src/main/java/org/apache/hadoop/hbase/HConstants.java

@@ -1017,6 +1017,12 @@ public enum OperationStatusCode {
 
   public static final float HFILE_BLOCK_CACHE_SIZE_DEFAULT = 0.4f;
 
+  /**
+   * Configuration key for the size of the row cache
+   */
+  public static final String ROW_CACHE_SIZE_KEY = "row.cache.size";
+  public static final float ROW_CACHE_SIZE_DEFAULT = 0.0f;
+
   /**
    * Configuration key for the memory size of the block cache
    */

hbase-common/src/main/java/org/apache/hadoop/hbase/io/encoding/BufferedDataBlockEncoder.java

@@ -547,8 +547,8 @@ public void setTimestamp(byte[] ts) throws IOException {
 
     @Override
     public ExtendedCell deepClone() {
-      // This is not used in actual flow. Throwing UnsupportedOperationException
-      throw new UnsupportedOperationException();
+      // To garbage collect the objects referenced by this cell, we need to deep clone it
+      return ExtendedCell.super.deepClone();
     }
   }
 

hbase-common/src/main/resources/hbase-default.xml

@@ -1027,6 +1027,12 @@ possible configurations would overwhelm and obscure the important.
       This configuration allows setting an absolute memory size instead of a percentage of the maximum heap.
       Takes precedence over hfile.block.cache.size if both are specified.</description>
   </property>
+  <property>
+    <name>row.cache.size</name>
+    <value>0.0</value>
+    <description>Percentage of maximum heap (-Xmx setting) to allocate to row cache.
+      Default of 0.0; it means the row cache is disabled.</description>
+  </property>
   <property>
       <name>hfile.block.index.cacheonwrite</name>
       <value>false</value>

hbase-hadoop-compat/src/main/java/org/apache/hadoop/hbase/regionserver/MetricsRegionServerSource.java

@@ -430,6 +430,13 @@ public interface MetricsRegionServerSource extends BaseSource, JvmPauseMonitorSo
   String L2_CACHE_HIT_RATIO_DESC = "L2 cache hit ratio.";
   String L2_CACHE_MISS_RATIO = "l2CacheMissRatio";
   String L2_CACHE_MISS_RATIO_DESC = "L2 cache miss ratio.";
+
+  String ROW_CACHE_HIT_COUNT = "rowCacheHitCount";
+  String ROW_CACHE_MISS_COUNT = "rowCacheMissCount";
+  String ROW_CACHE_EVICTED_ROW_COUNT = "rowCacheEvictedRowCount";
+  String ROW_CACHE_SIZE = "rowCacheSize";
+  String ROW_CACHE_COUNT = "rowCacheCount";
+
   String RS_START_TIME_NAME = "regionServerStartTime";
   String ZOOKEEPER_QUORUM_NAME = "zookeeperQuorum";
   String SERVER_NAME_NAME = "serverName";

hbase-hadoop-compat/src/main/java/org/apache/hadoop/hbase/regionserver/MetricsRegionServerSourceImpl.java

@@ -452,6 +452,12 @@ public void getMetrics(MetricsCollector metricsCollector, boolean all) {
         .addCounter(Interns.info(BLOCK_CACHE_DELETE_FAMILY_BLOOM_HIT_COUNT, ""),
           rsWrap.getDeleteFamilyBloomHitCount())
         .addCounter(Interns.info(BLOCK_CACHE_TRAILER_HIT_COUNT, ""), rsWrap.getTrailerHitCount())
+        .addCounter(Interns.info(ROW_CACHE_HIT_COUNT, ""), rsWrap.getRowCacheHitCount())
+        .addCounter(Interns.info(ROW_CACHE_MISS_COUNT, ""), rsWrap.getRowCacheMissCount())
+        .addCounter(Interns.info(ROW_CACHE_EVICTED_ROW_COUNT, ""),
+          rsWrap.getRowCacheEvictedRowCount())
+        .addGauge(Interns.info(ROW_CACHE_SIZE, ""), rsWrap.getRowCacheSize())
+        .addGauge(Interns.info(ROW_CACHE_COUNT, ""), rsWrap.getRowCacheCount())
         .addCounter(Interns.info(UPDATES_BLOCKED_TIME, UPDATES_BLOCKED_DESC),
           rsWrap.getUpdatesBlockedTime())
         .addCounter(Interns.info(FLUSHED_CELLS, FLUSHED_CELLS_DESC), rsWrap.getFlushedCellsCount())

hbase-hadoop-compat/src/main/java/org/apache/hadoop/hbase/regionserver/MetricsRegionServerWrapper.java

@@ -635,6 +635,16 @@ public interface MetricsRegionServerWrapper {
 
   long getTrailerHitCount();
 
+  long getRowCacheHitCount();
+
+  long getRowCacheMissCount();
+
+  long getRowCacheSize();
+
+  long getRowCacheCount();
+
+  long getRowCacheEvictedRowCount();
+
   long getTotalRowActionRequestCount();
 
   long getByteBuffAllocatorHeapAllocationBytes();

hbase-server/src/main/jamon/org/apache/hadoop/hbase/tmpl/regionserver/BlockCacheTmpl.jamon

@@ -21,6 +21,7 @@ Template for rendering Block Cache tabs in RegionServer Status page.
 CacheConfig cacheConfig;
 Configuration config;
 BlockCache bc;
+RowCache rowCache;
 </%args>
 <%java>
   String bcUrl = bc == null ? null : "http://hbase.apache.org/devapidocs/" + bc.getClass().getName().replaceAll("\\.", "/") + ".html";
@@ -42,15 +43,17 @@ org.apache.hadoop.hbase.io.hfile.bucket.BucketCacheStats;
 org.apache.hadoop.hbase.io.hfile.bucket.BucketCache;
 org.apache.hadoop.hbase.io.hfile.bucket.BucketAllocator;
 org.apache.hadoop.hbase.io.hfile.bucket.BucketAllocator.Bucket;
+org.apache.hadoop.hbase.regionserver.RowCache;
 org.apache.hadoop.util.StringUtils.TraditionalBinaryPrefix;
 </%import>
 <div class="tabbable">
     <ul class="nav nav-pills" role="tablist">
         <li class="nav-item"><a class="nav-link active" href="#tab_bc_baseInfo" data-bs-toggle="tab" role="tab">Base Info</a></li>
         <li class="nav-item"><a class="nav-link" href="#tab_bc_config" data-bs-toggle="tab" role="tab">Config</a></li>
-        <li class="nav-item"><a class="nav-link" href="#tab_bc_stats" data-bs-toggle="tab" role="tab">Stats</a></li>
-        <li class="nav-item"><a class="nav-link" href="#tab_bc_l1" data-bs-toggle="tab" role="tab">L1</a></li>
-        <li class="nav-item"><a class="nav-link" href="#tab_bc_l2" data-bs-toggle="tab" role="tab">L2</a></li>
+        <li class="nav-item"><a class="nav-link" href="#tab_bc_stats" data-bs-toggle="tab" role="tab">Block Cache Stats</a></li>
+        <li class="nav-item"><a class="nav-link" href="#tab_bc_l1" data-bs-toggle="tab" role="tab">Block Cache L1</a></li>
+        <li class="nav-item"><a class="nav-link" href="#tab_bc_l2" data-bs-toggle="tab" role="tab">Block Cache L2</a></li>
+        <li class="nav-item"><a class="nav-link" href="#tab_row_cache" data-bs-toggle="tab" role="tab">Row Cache</a></li>
     </ul>
     <div class="tab-content">
         <div class="tab-pane active" id="tab_bc_baseInfo" role="tabpanel">
@@ -68,6 +71,9 @@ org.apache.hadoop.util.StringUtils.TraditionalBinaryPrefix;
         <div class="tab-pane" id="tab_bc_l2" role="tabpanel">
             <& bc_l; bc = bcs == null? null: bcs.length <= 1? null: bcs[1]; name = "L2"; evictions = evictions; &>
         </div>
+        <div class="tab-pane" id="tab_row_cache" role="tabpanel">
+            <& row_cache_stats; rowCache = rowCache &>
+        </div>
     </div>
 </div>
 
@@ -562,3 +568,55 @@ Increase that value to get a complete picture.
 </p>
 </%def>
 
+<%def row_cache_stats>
+<%args>
+    RowCache rowCache;
+</%args>
+<%if rowCache == null %>
+<p>RowCache is disabled</p>
+<%else>
+<table class="table table-striped">
+    <tr>
+        <th>Attribute</th>
+        <th>Value</th>
+        <th>Description</th>
+    </tr>
+    <tr>
+        <td>Size</td>
+        <td><% TraditionalBinaryPrefix.long2String(rowCache.getSize(), "B", 1) %></td>
+        <td>Current size of row cache in use</td>
+    </tr>
+    <tr>
+        <td>Free</td>
+        <td><% TraditionalBinaryPrefix.long2String(rowCache.getMaxSize() - rowCache.getSize(), "B", 1) %></td>
+        <td>The total free memory currently available to store more cache entries</td>
+    </tr>
+    <tr>
+        <td>Count</td>
+        <td><% String.format("%,d", rowCache.getCount()) %></td>
+        <td>The number of rows in row cache</td>
+    </tr>
+    <tr>
+        <td>Evicted Rows</td>
+        <td><% String.format("%,d", rowCache.getEvictedRowCount()) %></td>
+        <td>The total number of rows evicted</td>
+    </tr>
+    <tr>
+        <td>Hits</td>
+        <td><% String.format("%,d", rowCache.getHitCount()) %></td>
+        <td>The number requests that were cache hits</td>
+    </tr>
+    <tr>
+        <td>Misses</td>
+        <td><% String.format("%,d", rowCache.getMissCount()) %></td>
+        <td>The number requests that were cache misses</td>
+    </tr>
+    <tr>
+        <td>All Time Hit Ratio</td>
+        <td><% String.format("%,.2f", rowCache.getHitCount() * 100.0 / (rowCache.getMissCount() + rowCache.getHitCount())) %><% "%" %></td>
+        <td>Hit Count divided by total requests count</td>
+    </tr>
+</table>
+<p>RowCache is a separate cache distinct from BlockCache.</p>
+</%if>
+</%def>

hbase-server/src/main/jamon/org/apache/hadoop/hbase/tmpl/regionserver/RSStatusTmpl.jamon

@@ -26,10 +26,12 @@ String bcv = "";
 <%import>
 java.util.*;
 org.apache.hadoop.hbase.regionserver.HRegionServer;
+org.apache.hadoop.hbase.regionserver.RowCacheService;
 org.apache.hadoop.hbase.client.RegionInfo;
 org.apache.hadoop.hbase.ServerName;
 org.apache.hadoop.hbase.HBaseConfiguration;
 org.apache.hadoop.hbase.io.hfile.CacheConfig;
+org.apache.hadoop.hbase.regionserver.RowCache;
 org.apache.hadoop.hbase.shaded.protobuf.ProtobufUtil;
 org.apache.hadoop.hbase.shaded.protobuf.generated.AdminProtos.ServerInfo;
 org.apache.hadoop.hbase.util.JvmVersion;
@@ -51,6 +53,8 @@ org.apache.hadoop.hbase.zookeeper.MasterAddressTracker;
   ServerName masterServerName = masterAddressTracker == null ? null
     : masterAddressTracker.getMasterAddress();
   int infoPort = masterAddressTracker == null ? 0 : masterAddressTracker.getMasterInfoPort();
+  RowCacheService rowCacheService = regionServer.getRSRpcServices().getRowCacheService();
+  RowCache rowCache = rowCacheService == null ? null : rowCacheService.getRowCache();
 </%java>
 
 <%class>
@@ -148,8 +152,8 @@ org.apache.hadoop.hbase.zookeeper.MasterAddressTracker;
     </section>
 
     <section>
-    <h2>Block Cache</h2>
-    <& BlockCacheTmpl; cacheConfig = new CacheConfig(regionServer.getConfiguration()); config = regionServer.getConfiguration(); bc = regionServer.getBlockCache().orElse(null) &>
+    <h2>Cache</h2>
+    <& BlockCacheTmpl; cacheConfig = new CacheConfig(regionServer.getConfiguration()); config = regionServer.getConfiguration(); bc = regionServer.getBlockCache().orElse(null); rowCache = rowCache &>
     </section>
 
     <section>

hbase-server/src/main/java/org/apache/hadoop/hbase/io/util/MemorySizeUtil.java

@@ -93,25 +93,29 @@ public static void validateRegionServerHeapMemoryAllocation(Configuration conf)
     }
     float memStoreFraction = getGlobalMemStoreHeapPercent(conf, false);
     float blockCacheFraction = getBlockCacheHeapPercent(conf);
+    float rowCacheFraction =
+      conf.getFloat(HConstants.ROW_CACHE_SIZE_KEY, HConstants.ROW_CACHE_SIZE_DEFAULT);
     float minFreeHeapFraction = getRegionServerMinFreeHeapFraction(conf);
 
     int memStorePercent = (int) (memStoreFraction * 100);
     int blockCachePercent = (int) (blockCacheFraction * 100);
+    int rowCachePercent = (int) (rowCacheFraction * 100);
     int minFreeHeapPercent = (int) (minFreeHeapFraction * 100);
-    int usedPercent = memStorePercent + blockCachePercent;
+    int usedPercent = memStorePercent + blockCachePercent + rowCachePercent;
     int maxAllowedUsed = 100 - minFreeHeapPercent;
 
     if (usedPercent > maxAllowedUsed) {
       throw new RuntimeException(String.format(
         "RegionServer heap memory allocation is invalid: total memory usage exceeds 100%% "
-          + "(memStore + blockCache + requiredFreeHeap). "
-          + "Check the following configuration values:%n" + "  - %s = %.2f%n" + "  - %s = %s%n"
-          + "  - %s = %s%n" + "  - %s = %s",
+          + "(memStore + blockCache + rowCache + requiredFreeHeap). "
+          + "Check the following configuration values:" + "%n  - %s = %.2f" + "%n  - %s = %s"
+          + "%n  - %s = %s" + "%n  - %s = %s" + "%n  - %s = %s",
         MEMSTORE_SIZE_KEY, memStoreFraction, HConstants.HFILE_BLOCK_CACHE_MEMORY_SIZE_KEY,
         conf.get(HConstants.HFILE_BLOCK_CACHE_MEMORY_SIZE_KEY),
         HConstants.HFILE_BLOCK_CACHE_SIZE_KEY, conf.get(HConstants.HFILE_BLOCK_CACHE_SIZE_KEY),
         HBASE_REGION_SERVER_FREE_HEAP_MIN_MEMORY_SIZE_KEY,
-        conf.get(HBASE_REGION_SERVER_FREE_HEAP_MIN_MEMORY_SIZE_KEY)));
+        conf.get(HBASE_REGION_SERVER_FREE_HEAP_MIN_MEMORY_SIZE_KEY), HConstants.ROW_CACHE_SIZE_KEY,
+        conf.get(HConstants.ROW_CACHE_SIZE_KEY)));
     }
   }
 
@@ -313,4 +317,15 @@ public static long getBucketCacheSize(final Configuration conf) {
     }
     return (long) (bucketCacheSize * 1024 * 1024);
   }
+
+  public static long getRowCacheSize(Configuration conf) {
+    long max = -1L;
+    final MemoryUsage usage = safeGetHeapMemoryUsage();
+    if (usage != null) {
+      max = usage.getMax();
+    }
+    float globalRowCachePercent =
+      conf.getFloat(HConstants.ROW_CACHE_SIZE_KEY, HConstants.ROW_CACHE_SIZE_DEFAULT);
+    return ((long) (max * globalRowCachePercent));
+  }
 }

hbase-server/src/main/java/org/apache/hadoop/hbase/regionserver/HRegion.java

@@ -65,6 +65,7 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicLong;
 import java.util.concurrent.atomic.LongAdder;
 import java.util.concurrent.locks.Lock;
 import java.util.concurrent.locks.ReadWriteLock;
@@ -433,6 +434,11 @@ public MetricsTableRequests getMetricsTableRequests() {
    */
   private long openSeqNum = HConstants.NO_SEQNUM;
 
+  /**
+   * Basically the same as openSeqNum, but it is updated when bulk load is done.
+   */
+  private final AtomicLong rowCacheSeqNum = new AtomicLong(HConstants.NO_SEQNUM);
+
   /**
    * The default setting for whether to enable on-demand CF loading for scan requests to this
    * region. Requests can override it.
@@ -7868,6 +7874,7 @@ private HRegion openHRegion(final CancelableProgressable reporter) throws IOExce
       LOG.debug("checking classloading for " + this.getRegionInfo().getEncodedName());
       TableDescriptorChecker.checkClassLoading(cConfig, htableDescriptor);
       this.openSeqNum = initialize(reporter);
+      this.rowCacheSeqNum.set(this.openSeqNum);
       this.mvcc.advanceTo(openSeqNum);
       // The openSeqNum must be increased every time when a region is assigned, as we rely on it to
       // determine whether a region has been successfully reopened. So here we always write open
@@ -8696,6 +8703,17 @@ public long getOpenSeqNum() {
     return this.openSeqNum;
   }
 
+  public long getRowCacheSeqNum() {
+    return this.rowCacheSeqNum.get();
+  }
+
+  /**
+   * This is used to invalidate the entire row cache after bulk loading.
+   */
+  public void increaseRowCacheSeqNum() {
+    this.rowCacheSeqNum.incrementAndGet();
+  }
+
   @Override
   public Map<byte[], Long> getMaxStoreSeqId() {
     return this.maxSeqIdInStores;