Extract IndexFactory as unified pluggable index abstraction

BUCK

@@ -202,6 +202,7 @@ cpp_library_wrapper(name="rocksdb_lib", srcs=[
         "table/block_based/block_cache.cc",
         "table/block_based/block_prefetcher.cc",
         "table/block_based/block_prefix_index.cc",
+        "table/block_based/builtin_index_factory.cc",
         "table/block_based/data_block_footer.cc",
         "table/block_based/data_block_hash_index.cc",
         "table/block_based/filter_block_reader_common.cc",
@@ -4598,6 +4599,12 @@ cpp_unittest_wrapper(name="bloom_test",
             extra_compiler_flags=[])
 
 
+cpp_unittest_wrapper(name="builtin_index_factory_test",
+            srcs=["table/block_based/builtin_index_factory_test.cc"],
+            deps=[":rocksdb_test_lib"],
+            extra_compiler_flags=[])
+
+
 cpp_unittest_wrapper(name="cache_reservation_manager_test",
             srcs=["cache/cache_reservation_manager_test.cc"],
             deps=[":rocksdb_test_lib"],

CMakeLists.txt

@@ -874,6 +874,7 @@ set(SOURCES
         table/block_based/filter_block_reader_common.cc
         table/block_based/filter_policy.cc
         table/block_based/flush_block_policy.cc
+        table/block_based/builtin_index_factory.cc
         table/block_based/full_filter_block.cc
         table/block_based/hash_index_reader.cc
         table/block_based/index_builder.cc
@@ -1511,6 +1512,7 @@ if(WITH_TESTS)
         options/options_test.cc
         table/block_based/block_based_table_reader_test.cc
         table/block_based/block_test.cc
+        table/block_based/builtin_index_factory_test.cc
         table/block_based/data_block_hash_index_test.cc
         table/block_based/full_filter_block_test.cc
         table/block_based/partitioned_filter_block_test.cc

Makefile

@@ -1775,6 +1775,9 @@ block_fetcher_test: table/block_fetcher_test.o $(TEST_LIBRARY) $(LIBRARY)
 block_test: $(OBJ_DIR)/table/block_based/block_test.o $(TEST_LIBRARY) $(LIBRARY)
 	$(AM_LINK)
 
+builtin_index_factory_test: $(OBJ_DIR)/table/block_based/builtin_index_factory_test.o $(TEST_LIBRARY) $(LIBRARY)
+	$(AM_LINK)
+
 data_block_hash_index_test: $(OBJ_DIR)/table/block_based/data_block_hash_index_test.o $(TEST_LIBRARY) $(LIBRARY)
 	$(AM_LINK)
 

db/wide/db_wide_blob_direct_write_test.cc

@@ -180,7 +180,7 @@ class DBWideBlobDirectWriteTest : public DBTestBase {
 
     trie_index::TrieIndexFactory trie_index_factory;
     if (scenario.use_trie_index) {
-      coalescing_ro.table_index_factory = &trie_index_factory;
+      coalescing_ro.read_index = ReadOptions::ReadIndex::kCustom;
     }
 
     ReadOptions control_ro = coalescing_ro;
@@ -714,7 +714,7 @@ TEST_F(DBWideBlobDirectWriteTest,
   read_options.snapshot = snapshot;
 
   trie_index::TrieIndexFactory trie_index_factory;
-  read_options.table_index_factory = &trie_index_factory;
+  read_options.read_index = ReadOptions::ReadIndex::kCustom;
 
   std::vector<ColumnFamilyHandle*> cfhs{handles_[1], handles_[0]};
   std::unique_ptr<Iterator> coalescing =
@@ -845,7 +845,7 @@ TEST_F(DBWideBlobDirectWriteTest,
 
     trie_index::TrieIndexFactory trie_index_factory;
     if (test_case.use_trie_index) {
-      read_options.table_index_factory = &trie_index_factory;
+      read_options.read_index = ReadOptions::ReadIndex::kCustom;
     }
 
     const auto verify_snapshot_reads = [&]() {

db_stress_tool/db_stress_common.h

@@ -184,7 +184,7 @@ DECLARE_int32(data_block_index_type);
 DECLARE_int32(index_block_search_type);
 DECLARE_double(uniform_cv_threshold);
 DECLARE_bool(use_trie_index);
-DECLARE_bool(use_udi_as_primary_index);
+DECLARE_int32(index_mode);
 DECLARE_bool(test_backward_scan);
 DECLARE_string(db);
 DECLARE_string(secondaries_base);

db_stress_tool/db_stress_gflags.cc

@@ -670,15 +670,13 @@ DEFINE_bool(use_trie_index, false,
             "Use trie-based user defined index (UDI) for SST files. "
             "Compatible with all operation types (Put, Delete, Merge, etc.) "
             "and all iteration directions (forward and reverse). "
-            "Combined with use_udi_as_primary_index to control whether the "
-            "UDI is the primary or secondary index.");
-
-DEFINE_bool(use_udi_as_primary_index, false,
-            "When use_trie_index is enabled, use the UDI as the primary "
-            "index. All reads automatically go through the UDI (both "
-            "the standard index and UDI are always built). When false, "
-            "the UDI is a secondary index and reads require "
-            "ReadOptions::table_index_factory to be set.");
+            "Combined with index_mode to control the UDI role.");
+
+DEFINE_int32(index_mode, 0,
+             "Controls how the custom IndexFactory interacts with the "
+             "built-in index. 0=kStandardOnly, 1=kStandardDefault, "
+             "2=kCustomDefault, 3=kCustomOnly. Requires use_trie_index "
+             "for modes >= 1.");
 
 DEFINE_bool(test_backward_scan, true,
             "Test backward iteration (Prev, SeekForPrev) in stress tests.");

db_stress_tool/db_stress_test_base.cc

@@ -1003,8 +1003,13 @@ void StressTest::OperateDb(ThreadState* thread) {
   read_opts.allow_unprepared_value = FLAGS_allow_unprepared_value;
   read_opts.auto_refresh_iterator_with_snapshot =
       FLAGS_auto_refresh_iterator_with_snapshot;
-  if (FLAGS_use_trie_index && !FLAGS_use_udi_as_primary_index && udi_factory_) {
-    read_opts.table_index_factory = udi_factory_.get();
+  if (FLAGS_use_trie_index && udi_factory_) {
+    if (FLAGS_index_mode == 1) {
+      // kStandardDefault: custom index is secondary, select explicitly per-read
+      read_opts.read_index = ReadOptions::ReadIndex::kCustom;
+    }
+    // kCustomDefault/kCustomOnly: custom index is default, no override needed
+    // kStandardOnly: custom index not built, don't select it
   }
   WriteOptions write_opts;
   if (FLAGS_rate_limit_auto_wal_flush) {
@@ -1054,8 +1059,8 @@ void StressTest::OperateDb(ThreadState* thread) {
       }
       // Commenting this out as we don't want to reset stats on each open.
       // thread->stats.Start();
-      if (FLAGS_use_trie_index && udi_factory_) {
-        read_opts.table_index_factory = udi_factory_.get();
+      if (FLAGS_use_trie_index && FLAGS_index_mode == 1 && udi_factory_) {
+        read_opts.read_index = ReadOptions::ReadIndex::kCustom;
       }
     }
 
@@ -2163,7 +2168,7 @@ void StressTest::DumpIteratorDivergenceDiagnostics(
           "selected_cf_count=%zu\n",
           seek_key.ToString(/*hex=*/true).c_str(), cmp_cfh->GetName().c_str(),
           static_cast<int>(options_.prefix_extractor != nullptr),
-          static_cast<int>(ro.table_index_factory != nullptr),
+          static_cast<int>(ro.read_index != ReadOptions::ReadIndex::kDefault),
           static_cast<int>(FLAGS_use_multi_cf_iterator),
           rand_column_families.size());
 
@@ -2224,13 +2229,13 @@ void StressTest::DumpIteratorDivergenceDiagnostics(
   };
 
   ReadOptions standard_ro = ro;
-  standard_ro.table_index_factory = nullptr;
+  standard_ro.read_index = ReadOptions::ReadIndex::kDefault;
   dump_debug_iter("Debug standard direct", standard_ro,
                   /*use_multi_cf_iter=*/false);
 
   if (udi_factory_) {
     ReadOptions trie_ro = ro;
-    trie_ro.table_index_factory = udi_factory_.get();
+    trie_ro.read_index = ReadOptions::ReadIndex::kCustom;
     dump_debug_iter("Debug trie direct", trie_ro,
                     /*use_multi_cf_iter=*/false);
   }
@@ -2240,7 +2245,7 @@ void StressTest::DumpIteratorDivergenceDiagnostics(
                     /*use_multi_cf_iter=*/true);
     if (udi_factory_) {
       ReadOptions trie_ro = ro;
-      trie_ro.table_index_factory = udi_factory_.get();
+      trie_ro.read_index = ReadOptions::ReadIndex::kCustom;
       dump_debug_iter("Debug trie coalescing", trie_ro,
                       /*use_multi_cf_iter=*/true);
     }
@@ -4431,8 +4436,7 @@ bool InitializeOptionsFromFile(Options& options) {
 void InitializeOptionsFromFlags(
     const std::shared_ptr<Cache>& cache,
     const std::shared_ptr<const FilterPolicy>& filter_policy,
-    const std::shared_ptr<UserDefinedIndexFactory>& udi_factory,
-    Options& options) {
+    const std::shared_ptr<IndexFactory>& udi_factory, Options& options) {
   BlockBasedTableOptions block_based_options;
   block_based_options.decouple_partitioned_filters =
       FLAGS_decouple_partitioned_filters;
@@ -4517,18 +4521,32 @@ void InitializeOptionsFromFlags(
       fLU64::FLAGS_super_block_alignment_space_overhead_ratio;
   if (udi_factory) {
     block_based_options.user_defined_index_factory = udi_factory;
-    if (FLAGS_use_udi_as_primary_index) {
-      block_based_options.use_udi_as_primary_index = true;
-    }
-    // Write fault injection can corrupt the UDI meta block during SST
-    // creation. In primary mode all reads route through the UDI, so a
-    // corrupted UDI block causes the reader to fail, making compaction
-    // read zero keys from the affected SST and triggering a false
-    // positive in record count verification. In secondary mode this is
-    // not an issue because reads fall back to the standard index.
-    if (FLAGS_use_udi_as_primary_index &&
-        (FLAGS_write_fault_one_in > 0 ||
-         FLAGS_metadata_write_fault_one_in > 0)) {
+    if (FLAGS_index_mode < 0 || FLAGS_index_mode > 3) {
+      fprintf(stderr, "Invalid --index_mode=%d (must be 0-3)\n",
+              FLAGS_index_mode);
+      abort();
+    }
+    block_based_options.index_mode =
+        static_cast<BlockBasedTableOptions::IndexMode>(FLAGS_index_mode);
+    // Disable compaction record count verification when write fault
+    // injection is active in custom index modes (kCustomDefault/kCustomOnly).
+    //
+    // The custom index is stored as a meta block in the SST. Write fault
+    // injection (metadata_write_fault_one_in, write_fault_one_in) can
+    // corrupt this meta block during SST creation. In kCustomOnly, a
+    // corrupted custom index causes the compaction iterator to read zero
+    // keys (no standard index fallback). In kCustomDefault, the SST open
+    // returns an error on corrupted custom index. Either way, the
+    // compaction record count check produces a false positive.
+    //
+    // Without fault injection, all modes (including kCustomOnly) pass
+    // the compaction record count check correctly.
+    //
+    // Non-UDI modes (kStandardOnly, kStandardDefault) are not affected
+    // because the standard index is written as a main block (not a
+    // meta block), so write faults do not corrupt it.
+    if (FLAGS_index_mode >= 2 && (FLAGS_write_fault_one_in > 0 ||
+                                  FLAGS_metadata_write_fault_one_in > 0)) {
       options.compaction_verify_record_count = false;
     }
   }

db_stress_tool/db_stress_test_base.h

@@ -434,7 +434,7 @@ class StressTest {
   std::vector<std::string> options_index_;
   std::atomic<bool> db_preload_finished_;
   std::shared_ptr<SstQueryFilterConfigsManager::Factory> sqfc_factory_;
-  std::shared_ptr<UserDefinedIndexFactory> udi_factory_;
+  std::shared_ptr<IndexFactory> udi_factory_;
 
   std::unique_ptr<DB> secondary_db_;
   std::vector<ColumnFamilyHandle*> secondary_cfhs_;
@@ -451,8 +451,7 @@ bool InitializeOptionsFromFile(Options& options);
 void InitializeOptionsFromFlags(
     const std::shared_ptr<Cache>& cache,
     const std::shared_ptr<const FilterPolicy>& filter_policy,
-    const std::shared_ptr<UserDefinedIndexFactory>& udi_factory,
-    Options& options);
+    const std::shared_ptr<IndexFactory>& udi_factory, Options& options);
 
 // Initialize `options` on which `InitializeOptionsFromFile()` and
 // `InitializeOptionsFromFlags()` have both been called already.

db_stress_tool/no_batched_ops_stress.cc

@@ -2571,7 +2571,7 @@ class NonBatchedOpsStressTest : public StressTest {
             static_cast<int>(ro.auto_refresh_iterator_with_snapshot),
             static_cast<int>(ro.snapshot != nullptr),
             static_cast<int>(FLAGS_use_multi_cf_iterator),
-            static_cast<int>(ro.table_index_factory != nullptr),
+            static_cast<int>(ro.read_index != ReadOptions::ReadIndex::kDefault),
             static_cast<int>(FLAGS_use_trie_index));
     fprintf(stderr, "Iterator value: %s\n",
             iter->value().ToString(true).c_str());
@@ -2628,7 +2628,7 @@ class NonBatchedOpsStressTest : public StressTest {
     };
 
     ReadOptions standard_ro = ro;
-    standard_ro.table_index_factory = nullptr;
+    standard_ro.read_index = ReadOptions::ReadIndex::kDefault;
     dump_debug_iter("Debug standard direct", standard_ro,
                     /*use_multi_cf_iter=*/false,
                     /*replay_from_mid=*/false);

include/rocksdb/compression_type.h

@@ -233,7 +233,7 @@ struct CompressionOptions {
   //
   // This option is valid only when BlockBasedTable is used and is disabled
   // (sanitized to 1) with any of these:
-  // * User-defined index (UserDefinedIndexFactory)
+  // * User-defined index (IndexFactory)
   // * partition_filters == true && decouple_partitioned_filters == false
   //
   // When parallel compression is enabled, SST size file sizes might be