From 325dcdf2e54aaaad9ca44938deb2729142e670dc Mon Sep 17 00:00:00 2001 From: Changyu Bi Date: Fri, 28 Mar 2025 14:49:28 -0700 Subject: [PATCH] Deprecate `ReadOptions::ignore_range_deletions` and `experimental::PromoteL0()` (#13500) Summary: based on the option comment, `ignore_range_deletions` was added due to the overhead of range deletions in read path when a DB does not use DeleteRange(). The current implementation should not have a noticeable performance difference in this case. `experimental::PromoteL0()` can be replaced by doing a manual compaction with proper CompactRangeOptions. There are some internal use of these option and API so we will remove them later after the usages are updated. Pull Request resolved: https://github.com/facebook/rocksdb/pull/13500 Test Plan: comment change only. Performance: benchmark the performance difference with `ignore_range_deletions` and without (borrowed flag `universal_incremental` for this purpose), ran at the same time on the same machine. - random point get: - ignore_range_deletions=false: 343078 ops/sec - ignore_range_deletions=true: 340219 ops/sec (0.8% slower) ``` (for I in $(seq 1 1); do TEST_TMPDIR=/dev/shm/t1 /data/users/changyubi/vscode-root/rocksdb/db_bench --benchmarks=fillseq,waitforcompaction,readrandom --write_buffer_size=67108864 --writes=1000000 --num=2000000 --reads=1000000 --seed=1723056275 --universal_incremental=false 2>&1 | grep "readrandom"; done;) | awk '{ t += $5; c++; print } END { print 1.0 * t / c }'; ``` - sequential scan: - ignore_range_deletions=false: 5378104 ops/sec - ignore_range_deletions=true: 5393809 ops/sec (0.3% faster) ``` (for I in $(seq 1 10); do TEST_TMPDIR=/dev/shm/t1 /data/users/changyubi/vscode-root/rocksdb/db_bench --benchmarks=fillseq,waitforcompaction,readseq[-X10] --write_buffer_size=67108864 --writes=1000000 --num=2000000 --universal_incremental=true --seed=1723056275 2>1 | grep "\[AVG 10 runs\]"; done;) | awk '{ t += $6; c++; print; } END { printf "%.0f\n", 1.0 * t / c }'; ``` The difference in ops/sec for the two benchmarks is likely noise. Reviewed By: hx235 Differential Revision: D72069223 Pulled By: cbi42 fbshipit-source-id: ad82a051aa4682790d2178cd4fb2d1467397fbb5 --- include/rocksdb/experimental.h | 5 +++++ include/rocksdb/options.h | 4 ++++ java/src/main/java/org/rocksdb/ReadOptions.java | 6 ++++++ java/src/main/java/org/rocksdb/RocksDB.java | 13 +++++++++---- .../deprecate-ignore-range-del.md | 1 + .../public_api_changes/deprecate-promote-l0.md | 1 + 6 files changed, 26 insertions(+), 4 deletions(-) create mode 100644 unreleased_history/public_api_changes/deprecate-ignore-range-del.md create mode 100644 unreleased_history/public_api_changes/deprecate-promote-l0.md diff --git a/include/rocksdb/experimental.h b/include/rocksdb/experimental.h index 349d05f9b4..d6a34c0257 100644 --- a/include/rocksdb/experimental.h +++ b/include/rocksdb/experimental.h @@ -21,6 +21,11 @@ Status SuggestCompactRange(DB* db, ColumnFamilyHandle* column_family, const Slice* begin, const Slice* end); Status SuggestCompactRange(DB* db, const Slice* begin, const Slice* end); +// DEPRECATED: this API may be removed in a future release. +// This operation can be done through CompactRange() by setting +// CompactRangeOptions::bottommost_level_compaction set to +// BottommostLevelCompaction::kSkip and setting target level. +// // Move all L0 files to target_level skipping compaction. // This operation succeeds only if the files in L0 have disjoint ranges; this // is guaranteed to happen, for instance, if keys are inserted in sorted diff --git a/include/rocksdb/options.h b/include/rocksdb/options.h index 6b66976aa3..181e7781b6 100644 --- a/include/rocksdb/options.h +++ b/include/rocksdb/options.h @@ -1784,6 +1784,10 @@ struct ReadOptions { // block cache. bool fill_cache = true; + // DEPRECATED: This option might be removed in a future release. + // There should be no noticeable performance difference whether this option + // is turned on or off when a DB does not use DeleteRange(). + // // If true, range tombstones handling will be skipped in key lookup paths. // For DB instances that don't use DeleteRange() calls, this setting can // be used to optimize the read performance. diff --git a/java/src/main/java/org/rocksdb/ReadOptions.java b/java/src/main/java/org/rocksdb/ReadOptions.java index 5ce4a8656d..8cc9883d23 100644 --- a/java/src/main/java/org/rocksdb/ReadOptions.java +++ b/java/src/main/java/org/rocksdb/ReadOptions.java @@ -398,7 +398,10 @@ public class ReadOptions extends RocksObject { * Default: false * * @return true if keys deleted using the DeleteRange() API will be visible + * + * @deprecated This option may be remove in a future release. */ + @Deprecated public boolean ignoreRangeDeletions() { assert(isOwningHandle()); return ignoreRangeDeletions(nativeHandle_); @@ -414,7 +417,10 @@ public class ReadOptions extends RocksObject { * @param ignoreRangeDeletions true if keys deleted using the DeleteRange() * API should be visible * @return the reference to the current ReadOptions. + * + * @deprecated This option may be remove in a future release. */ + @Deprecated public ReadOptions setIgnoreRangeDeletions(final boolean ignoreRangeDeletions) { assert(isOwningHandle()); setIgnoreRangeDeletions(nativeHandle_, ignoreRangeDeletions); diff --git a/java/src/main/java/org/rocksdb/RocksDB.java b/java/src/main/java/org/rocksdb/RocksDB.java index 1ffb44b6a1..d01b98f48a 100644 --- a/java/src/main/java/org/rocksdb/RocksDB.java +++ b/java/src/main/java/org/rocksdb/RocksDB.java @@ -4633,10 +4633,13 @@ public class RocksDB extends RocksObject { * @param targetLevel the target level for L0 * * @throws RocksDBException if an error occurs whilst promoting L0 + * + * @deprecated this API may be removed in a future release. */ + @Deprecated public void promoteL0( - /* @Nullable */final ColumnFamilyHandle columnFamilyHandle, - final int targetLevel) throws RocksDBException { + /* @Nullable */ final ColumnFamilyHandle columnFamilyHandle, final int targetLevel) + throws RocksDBException { promoteL0(nativeHandle_, columnFamilyHandle == null ? 0 : columnFamilyHandle.nativeHandle_, targetLevel); @@ -4648,9 +4651,11 @@ public class RocksDB extends RocksObject { * @param targetLevel the target level for L0 * * @throws RocksDBException if an error occurs whilst promoting L0 + * + * @deprecated this API may be removed in a future release. */ - public void promoteL0(final int targetLevel) - throws RocksDBException { + @Deprecated + public void promoteL0(final int targetLevel) throws RocksDBException { promoteL0(null, targetLevel); } diff --git a/unreleased_history/public_api_changes/deprecate-ignore-range-del.md b/unreleased_history/public_api_changes/deprecate-ignore-range-del.md new file mode 100644 index 0000000000..d4e09e6ec2 --- /dev/null +++ b/unreleased_history/public_api_changes/deprecate-ignore-range-del.md @@ -0,0 +1 @@ +* Deprecated `ReadOptions::ignore_range_deletions`. diff --git a/unreleased_history/public_api_changes/deprecate-promote-l0.md b/unreleased_history/public_api_changes/deprecate-promote-l0.md new file mode 100644 index 0000000000..bcc3129829 --- /dev/null +++ b/unreleased_history/public_api_changes/deprecate-promote-l0.md @@ -0,0 +1 @@ +* Deprecated API `experimental::PromoteL0()`.