#pragma once
+#include <memory>
#include <string>
+#include "rocksdb/customizable.h"
#include "rocksdb/rocksdb_namespace.h"
namespace ROCKSDB_NAMESPACE {
class Slice;
+struct ConfigOptions;
-/*
- * A SliceTransform is a generic pluggable way of transforming one string
- * to another. Its primary use-case is in configuring rocksdb
- * to store prefix blooms by setting prefix_extractor in
- * ColumnFamilyOptions.
- */
-class SliceTransform {
+// A SliceTransform is a generic pluggable way of transforming one string
+// to another. Its primary use-case is in configuring RocksDB prefix Bloom
+// filters, by setting prefix_extractor in ColumnFamilyOptions.
+//
+// Exceptions MUST NOT propagate out of overridden functions into RocksDB,
+// because RocksDB is not exception-safe. This could cause undefined behavior
+// including data loss, unreported corruption, deadlocks, and more.
+class SliceTransform : public Customizable {
public:
virtual ~SliceTransform(){};
// Return the name of this transformation.
- virtual const char* Name() const = 0;
-
- // Extract a prefix from a specified key. This method is called when
- // a key is inserted into the db, and the returned slice is used to
- // create a bloom filter.
+ virtual const char* Name() const override = 0;
+ static const char* Type() { return "SliceTransform"; }
+
+ // Creates and configures a new SliceTransform from the input options and id.
+ static Status CreateFromString(const ConfigOptions& config_options,
+ const std::string& id,
+ std::shared_ptr<const SliceTransform>* result);
+
+ // Returns a string representation of this SliceTransform, representing the ID
+ // and any additional properties.
+ std::string AsString() const;
+
+ // Extract a prefix from a specified key, partial key, iterator upper bound,
+ // etc. This is normally used for building and checking prefix Bloom filters
+ // but should accept any string for which InDomain() returns true.
+ // See ColumnFamilyOptions::prefix_extractor for specific properties that
+ // must be satisfied by prefix extractors.
virtual Slice Transform(const Slice& key) const = 0;
// Determine whether the specified key is compatible with the logic
- // specified in the Transform method. This method is invoked for every
- // key that is inserted into the db. If this method returns true,
- // then Transform is called to translate the key to its prefix and
- // that returned prefix is inserted into the bloom filter. If this
- // method returns false, then the call to Transform is skipped and
- // no prefix is inserted into the bloom filters.
+ // specified in the Transform method. Keys for which InDomain returns
+ // false will not be added to or queried against prefix Bloom filters.
//
- // For example, if the Transform method operates on a fixed length
+ // For example, if the Transform method returns a fixed length
// prefix of size 4, then an invocation to InDomain("abc") returns
// false because the specified key length(3) is shorter than the
// prefix size of 4.
//
// Wiki documentation here:
- // https://github.com/facebook/rocksdb/wiki/Prefix-Seek-API-Changes
+ // https://github.com/facebook/rocksdb/wiki/Prefix-Seek
//
virtual bool InDomain(const Slice& key) const = 0;
- // This is currently not used and remains here for backward compatibility.
+ // DEPRECATED: This is currently not used and remains here for backward
+ // compatibility.
virtual bool InRange(const Slice& /*dst*/) const { return false; }
- // Some SliceTransform will have a full length which can be used to
- // determine if two keys are consecuitive. Can be disabled by always
- // returning 0
+ // Returns information on maximum prefix length, if there is one.
+ // If Transform(x).size() == n for some keys and otherwise < n,
+ // should return true and set *len = n. Returning false is safe but
+ // currently disables some auto_prefix_mode filtering.
+ // Specifically, if the iterate_upper_bound is the immediate successor (see
+ // Comparator::IsSameLengthImmediateSuccessor) of the seek key's prefix,
+ // we require this function return true and iterate_upper_bound.size() == n
+ // to recognize and optimize the prefix seek.
+ // Otherwise (including FullLengthEnabled returns false, or prefix length is
+ // less than maximum), Seek with auto_prefix_mode is only optimized if the
+ // iterate_upper_bound and seek key have the same prefix.
+ // BUG: Despite all these conditions and even with the extra condition on
+ // IsSameLengthImmediateSuccessor (see it's "BUG" section), it is not
+ // sufficient to ensure auto_prefix_mode returns all entries that
+ // total_order_seek would return. See auto_prefix_mode "BUG" section.
virtual bool FullLengthEnabled(size_t* /*len*/) const { return false; }
// Transform(s)=Transform(`prefix`) for any s with `prefix` as a prefix.
// by setting ReadOptions.total_order_seek = true.
//
// Here is an example: Suppose we implement a slice transform that returns
- // the first part of the string after splitting it using delimiter ",":
+ // the first part of the string up to and including first ",":
// 1. SameResultWhenAppended("abc,") should return true. If applying prefix
- // bloom filter using it, all slices matching "abc:.*" will be extracted
+ // bloom filter using it, all slices matching "abc,.*" will be extracted
// to "abc,", so any SST file or memtable containing any of those key
// will not be filtered out.
- // 2. SameResultWhenAppended("abc") should return false. A user will not
- // guaranteed to see all the keys matching "abc.*" if a user seek to "abc"
- // against a DB with the same setting. If one SST file only contains
- // "abcd,e", the file can be filtered out and the key will be invisible.
+ // 2. SameResultWhenAppended("abc") should return false. A user will not be
+ // guaranteed to see all the keys matching "abc.*" if a user prefix
+ // seeks to "abc" against a DB with the same setting. If one SST file
+ // only contains "abcd,e", the file can be filtered out and the key will
+ // be invisible, because the prefix according to the configured extractor
+ // is "abcd,".
//
// i.e., an implementation always returning false is safe.
virtual bool SameResultWhenAppended(const Slice& /*prefix*/) const {
}
};
+// The prefix is the first `prefix_len` bytes of the key, and keys shorter
+// then `prefix_len` are not InDomain.
extern const SliceTransform* NewFixedPrefixTransform(size_t prefix_len);
+// The prefix is the first min(length(key),`cap_len`) bytes of the key, and
+// all keys are InDomain.
extern const SliceTransform* NewCappedPrefixTransform(size_t cap_len);
+// Prefix is equal to key. All keys are InDomain.
extern const SliceTransform* NewNoopTransform();
} // namespace ROCKSDB_NAMESPACE
projects / ceph.git / blobdiff