Add some docs for default and per-query TTL

aboudreault · aboudreault · commit 02320a9906f5 · 2016-07-19T14:13:44.000-04:00
diff --git a/docs/api/cassandra/cqlengine/models.rst b/docs/api/cassandra/cqlengine/models.rst
@@ -32,8 +32,10 @@ Model
 
     .. autoattribute:: __keyspace__
 
-    .. _ttl-change:
-    .. autoattribute:: __default_ttl__
+    .. attribute:: __default_ttl__
+        :annotation:  = None
+
+        Will be deprecated in release 4.0. You can set the default ttl by configuring the table ``__options__``. See :ref:`ttl-change` for more details.
 
     .. autoattribute:: __discriminator_value__
 
diff --git a/docs/cqlengine/queryset.rst b/docs/cqlengine/queryset.rst
@@ -343,6 +343,42 @@ None means no timeout.
     Setting the timeout on the model is meaningless and will raise an AssertionError.
 
 
+.. _ttl-change:
+
+Default TTL and Per Query TTL
+=============================
+
+Model default TTL now relies on the *default_time_to_live* feature, introduced in Cassandra 2.0. It is not handled anymore in the CQLEngine Model (cassandra-driver >=3.6). You can set the default TTL of a table like this:
+
+    Example:
+
+    .. code-block:: python
+
+        class User(Model):
+            __options__ = {'default_time_to_live': 20}
+
+            user_id = columns.UUID(primary_key=True)
+            ...
+
+You can set TTL per-query if needed. Here are a some examples:
+
+    Example:
+
+    .. code-block:: python
+
+        class User(Model):
+            __options__ = {'default_time_to_live': 20}
+
+            user_id = columns.UUID(primary_key=True)
+            ...
+
+        user = User.objects.create(user_id=1)  # Default TTL 20 will be set automatically on the server
+
+        user.ttl(30).update(age=21)            # Update the TTL to 30
+        User.objects.ttl(10).create(user_id=1)  # TTL 10
+        User(user_id=1, age=21).ttl(10).save()  # TTL 10
+
+
 Named Tables
 ===================
 
