219 lines
6.5 KiB
ReStructuredText
219 lines
6.5 KiB
ReStructuredText
``cassandra.cqlengine.models`` - Table models for object mapping
|
|
================================================================
|
|
|
|
.. module:: cassandra.cqlengine.models
|
|
|
|
Model
|
|
-----
|
|
.. autoclass:: Model(\*\*kwargs)
|
|
|
|
The initializer creates an instance of the model. Pass in keyword arguments for columns you've defined on the model.
|
|
|
|
.. code-block:: python
|
|
|
|
class Person(Model):
|
|
id = columns.UUID(primary_key=True)
|
|
first_name = columns.Text()
|
|
last_name = columns.Text()
|
|
|
|
person = Person(first_name='Blake', last_name='Eggleston')
|
|
person.first_name #returns 'Blake'
|
|
person.last_name #returns 'Eggleston'
|
|
|
|
*Model attributes define how the model maps to tables in the database. These are class variables that should be set
|
|
when defining Model deriviatives.*
|
|
|
|
.. autoattribute:: __abstract__
|
|
:annotation: = False
|
|
|
|
.. autoattribute:: __table_name__
|
|
|
|
.. autoattribute:: __keyspace__
|
|
|
|
.. _ttl-change:
|
|
.. autoattribute:: __default_ttl__
|
|
|
|
.. autoattribute:: __polymorphic_key__
|
|
|
|
.. autoattribute:: __discriminator_value__
|
|
|
|
See :ref:`model_inheritance` for usage examples.
|
|
|
|
*Each table can have its own set of configuration options.
|
|
These can be specified on a model with the following attributes:*
|
|
|
|
See the `list of supported table properties for more information
|
|
<http://www.datastax.com/documentation/cql/3.1/cql/cql_reference/tabProp.html>`_.
|
|
|
|
.. attribute:: __bloom_filter_fp_chance
|
|
|
|
.. attribute:: __caching__
|
|
|
|
.. attribute:: __comment__
|
|
|
|
.. attribute:: __dclocal_read_repair_chance__
|
|
|
|
.. attribute:: __default_time_to_live__
|
|
|
|
.. attribute:: __gc_grace_seconds__
|
|
|
|
.. attribute:: __index_interval__
|
|
|
|
.. attribute:: __memtable_flush_period_in_ms__
|
|
|
|
.. attribute:: __populate_io_cache_on_flush__
|
|
|
|
.. attribute:: __read_repair_chance__
|
|
|
|
.. attribute:: __replicate_on_write__
|
|
|
|
|
|
*Model presently supports specifying compaction options via class attributes.
|
|
cqlengine will only use your compaction options if you have a strategy set.
|
|
When a table is synced, it will be altered to match the compaction options set on your table.
|
|
This means that if you are changing settings manually they will be changed back on resync.*
|
|
|
|
*Do not use the compaction settings of cqlengine if you want to manage your compaction settings manually.*
|
|
|
|
*cqlengine supports all compaction options as of Cassandra 1.2.8.*
|
|
|
|
**These attibutes will likely be replaced by a single options string in a future version, and are therefore deprecated.**
|
|
|
|
.. attribute:: __compaction_bucket_high__
|
|
:annotation: Deprecated
|
|
|
|
.. attribute:: __compaction_bucket_low__
|
|
:annotation: Deprecated
|
|
|
|
.. attribute:: __compaction_max_compaction_threshold__
|
|
:annotation: Deprecated
|
|
|
|
.. attribute:: __compaction_min_compaction_threshold__
|
|
:annotation: Deprecated
|
|
|
|
.. attribute:: __compaction_min_sstable_size__
|
|
:annotation: Deprecated
|
|
|
|
.. attribute:: __compaction_sstable_size_in_mb__
|
|
:annotation: Deprecated
|
|
|
|
.. attribute:: __compaction_tombstone_compaction_interval__
|
|
:annotation: Deprecated
|
|
|
|
.. attribute:: __compaction_tombstone_threshold__
|
|
:annotation: Deprecated
|
|
|
|
For example:
|
|
|
|
.. code-block:: python
|
|
|
|
class User(Model):
|
|
__compaction__ = cqlengine.LeveledCompactionStrategy
|
|
__compaction_sstable_size_in_mb__ = 64
|
|
__compaction_tombstone_threshold__ = .2
|
|
|
|
user_id = columns.UUID(primary_key=True)
|
|
name = columns.Text()
|
|
|
|
or for SizeTieredCompaction:
|
|
|
|
.. code-block:: python
|
|
|
|
class TimeData(Model):
|
|
__compaction__ = SizeTieredCompactionStrategy
|
|
__compaction_bucket_low__ = .3
|
|
__compaction_bucket_high__ = 2
|
|
__compaction_min_threshold__ = 2
|
|
__compaction_max_threshold__ = 64
|
|
__compaction_tombstone_compaction_interval__ = 86400
|
|
|
|
Tables may use `LeveledCompactionStrategy` or `SizeTieredCompactionStrategy`. Both options are available in the top level cqlengine module. To reiterate, you will need to set your `__compaction__` option explicitly in order for cqlengine to handle any of your settings.
|
|
|
|
*The base methods allow creating, storing, and querying modeled objects.*
|
|
|
|
.. automethod:: create
|
|
|
|
.. method:: if_not_exists()
|
|
|
|
Check the existence of an object before insertion. The existence of an
|
|
object is determined by its primary key(s). And please note using this flag
|
|
would incur performance cost.
|
|
|
|
if the insertion didn't applied, a LWTException exception would be raised.
|
|
|
|
.. code-block:: python
|
|
|
|
try:
|
|
TestIfNotExistsModel.if_not_exists().create(id=id, count=9, text='111111111111')
|
|
except LWTException as e:
|
|
# handle failure case
|
|
print e.existing # existing object
|
|
|
|
This method is supported on Cassandra 2.0 or later.
|
|
|
|
.. automethod:: save
|
|
|
|
.. automethod:: update
|
|
|
|
.. method:: iff(**values)
|
|
|
|
Checks to ensure that the values specified are correct on the Cassandra cluster.
|
|
Simply specify the column(s) and the expected value(s). As with if_not_exists,
|
|
this incurs a performance cost.
|
|
|
|
If the insertion isn't applied, a LWTException is raised
|
|
|
|
.. code-block:: python
|
|
|
|
t = TestTransactionModel(text='some text', count=5)
|
|
try:
|
|
t.iff(count=5).update('other text')
|
|
except LWTException as e:
|
|
# handle failure
|
|
|
|
.. automethod:: get
|
|
|
|
.. automethod:: filter
|
|
|
|
.. automethod:: all
|
|
|
|
.. automethod:: delete
|
|
|
|
.. method:: batch(batch_object)
|
|
|
|
Sets the batch object to run instance updates and inserts queries with.
|
|
|
|
See :doc:`/cqlengine/batches` for usage examples
|
|
|
|
.. automethod:: timeout
|
|
|
|
.. method:: timestamp(timedelta_or_datetime)
|
|
|
|
Sets the timestamp for the query
|
|
|
|
.. method:: ttl(ttl_in_sec)
|
|
|
|
Sets the ttl values to run instance updates and inserts queries with.
|
|
|
|
.. automethod:: column_family_name
|
|
|
|
Models also support dict-like access:
|
|
|
|
.. method:: len(m)
|
|
|
|
Returns the number of columns defined in the model
|
|
|
|
.. method:: m[col_name]
|
|
|
|
Returns the value of column ``col_name``
|
|
|
|
.. method:: m[col_name] = value
|
|
|
|
Set ``m[col_name]`` to value
|
|
|
|
.. automethod:: keys
|
|
|
|
.. automethod:: values
|
|
|
|
.. automethod:: items
|