It deletes the most recent version of a key, and whether older versions of the key will come back to life is undefined.

Basic Usage

SingleDelete is a new database operation. In contrast to the conventional Delete() operation, the deletion entry is removed along with the value when the two are lined up in a compaction. Therefore, similar to Delete() method, SingleDelete() removes the database entry for a key, but has the prerequisites that the key exists and was not overwritten. Returns OK on success, and a non-OK status on error. It is not an error if key did not exist in the database. If a key is overwritten (by calling Put() multiple times), then the result of calling SingleDelete() on this key is undefined. SingleDelete() only behaves correctly if there has been only one Put() for this key since the previous call to SingleDelete() for this key. This feature is currently an experimental performance optimization for a very specific workload. The following code shows how to use SingleDelete:

  std::string value;
  rocksdb::Status s;
  db->Put(rocksdb::WriteOptions(), "foo", "bar1");
  db->SingleDelete(rocksdb::WriteOptions(), "foo");
  s = db->Get(rocksdb::ReadOptions(), "foo", &value); // s.IsNotFound()==true
  db->Put(rocksdb::WriteOptions(), "foo", "bar2");
  db->Put(rocksdb::WriteOptions(), "foo", "bar3");
  db->SingleDelete(rocksdb::ReadOptions(), "foo", &value); // Undefined result

SingleDelete API is also available in WriteBatch. Actually, DB::SingleDelete() is implemented by creating a WriteBatch with only one operation, SingleDelete, in this batch. The following code snippet shows the basic usage of WriteBatch::SingleDelete():

  rocksdb::WriteBatch batch;
  batch.Put(key1, value);
  batch.SingleDelete(key1);
  s = db->Write(rocksdb::WriteOptions(), &batch);

Notes

• Callers have to ensure that SingleDelete only applies to a key having not been deleted using Delete() or written using Merge(). Mixing SingleDelete() operations with Delete() and Merge() can result in undefined behavior (other keys are not affected by this)
• SingleDelete is NOT compatible with cuckoo hash tables, which means you should not call SingleDelete if you set options.memtable_factory with NewHashCuckooRepFactory
• Consecutive single deletions are currently not allowed
• Consider setting write_options.sync = true(Asynchronous Writes)