From 68c58009f2e69f0b92bfe4aba580b683e0b65384 Mon Sep 17 00:00:00 2001
From: hofmockel <dreagonfly@gmx.de>
Date: Mon, 28 Apr 2014 20:33:40 +0200
Subject: [PATCH] Add examples to use the 'table_factory' and
 'memtable_factory'

---
 docs/api/options.rst    |  6 +++--
 docs/tutorial/index.rst | 55 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/docs/api/options.rst b/docs/api/options.rst
index 6e066c3..ec04ad5 100644
--- a/docs/api/options.rst
+++ b/docs/api/options.rst
@@ -661,7 +661,7 @@ Options object
 
         Factory for the files forming the persisten data storage.
         Sometimes they are also named SST-Files. Right now you can assign
-        instances of the following classes
+        instances of the following classes.
 
         * :py:class:`rocksdb.BlockBasedTableFactory`
         * :py:class:`rocksdb.PlainTableFactory`
@@ -803,6 +803,8 @@ LRUCache
         the least-used order. If not enough space is freed, further free the
         entries in least used order.
 
+.. _table_factories_label:
+
 TableFactories
 ==============
 
@@ -816,7 +818,7 @@ Instances of this classes can assigned to :py:attr:`rocksdb.Options.table_factor
   for low query latency on pure-memory or really low-latency media.
 
 Tutorial of rocksdb table formats is available here:
- https://github.com/facebook/rocksdb/wiki/A-Tutorial-of-RocksDB-SST-formats
+https://github.com/facebook/rocksdb/wiki/A-Tutorial-of-RocksDB-SST-formats
 
 .. py:class:: rocksdb.BlockBasedTableFactory
 
diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst
index 1eb8119..74c99ee 100644
--- a/docs/tutorial/index.rst
+++ b/docs/tutorial/index.rst
@@ -270,3 +270,58 @@ The two arguments are the db_dir and wal_dir, which are mostly the same. ::
 
     backup = rocksdb.BackupEngine("test.db/backups")
     backup.restore_latest_backup("test.db", "test.db")
+
+
+Change Memtable or SST implementations
+======================================
+
+As noted here :ref:`memtable_factories_label`, RocksDB offers different implementations for the memtable
+representation. Per default :py:class:`rocksdb.SkipListMemtableFactory` is used,
+but changeing it to a different one is veary easy.
+
+Here is an example for HashSkipList-MemtableFactory.
+Keep in mind: To use the hashed based MemtableFactories you must set
+:py:attr:`rocksdb.Options.prefix_extractor`.
+In this example all keys have a static prefix of len 5. ::
+
+    class StaticPrefix(rocksdb.interfaces.SliceTransform):
+        def name(self):
+            return b'static'
+
+        def transform(self, src):
+            return (0, 5)
+
+        def in_domain(self, src):
+            return len(src) >= 5
+
+        def in_range(self, dst):
+            return len(dst) == 5
+
+
+    opts = rocksdb.Options()
+    opts.prefix_extractor = StaticPrefix()
+    opts.memtable_factory = rocksdb.HashSkipListMemtableFactory()
+    opts.create_if_missing = True
+
+    db = rocksdb.DB("test.db", opts)
+    db.put(b'00001.x', b'x')
+    db.put(b'00001.y', b'y')
+    db.put(b'00002.x', b'x')
+
+For initial bulk loads the Vector-MemtableFactory makes sense. ::
+
+    opts = rocksdb.Options()
+    opts.memtable_factory = rocksdb.VectorMemtableFactory()
+    opts.create_if_missing = True
+
+    db = rocksdb.DB("test.db", opts)
+
+As noted here :ref:`table_factories_label`, it is also possible to change the
+representation of the final data files.
+Here is an example how to use one of the 'PlainTables'. ::
+
+    opts = rocksdb.Options()
+    opts.table_factory = rocksdb.TotalOrderPlainTableFactory()
+    opts.create_if_missing = True
+
+    db = rocksdb.DB("test.db", opts)