Object Mapper
=============

cqlengine is the Cassandra CQL 3 Object Mapper packaged with this driver

:ref:`Jump to Getting Started <getting-started>`

Contents
--------
:doc:`cqlengine/upgrade_guide`
    For migrating projects from legacy cqlengine, to the integrated product

:doc:`cqlengine/models`
    Examples defining models, and mapping them to tables

:doc:`cqlengine/queryset`
    Overview of query sets and filtering

:doc:`cqlengine/batches`
    Working with batch mutations

:doc:`cqlengine/connections`
    Working with multiple sessions

:ref:`API Documentation <om_api>`
    Index of API documentation

:doc:`cqlengine/third_party`
    High-level examples in Celery and uWSGI

:doc:`cqlengine/faq`

.. toctree::
    :hidden:

    cqlengine/upgrade_guide
    cqlengine/models
    cqlengine/queryset
    cqlengine/batches
    cqlengine/connections
    cqlengine/third_party
    cqlengine/faq

.. _getting-started:

Getting Started
---------------

.. code-block:: python

    import uuid
    from cassandra.cqlengine import columns
    from cassandra.cqlengine import connection
    from datetime import datetime
    from cassandra.cqlengine.management import sync_table
    from cassandra.cqlengine.models import Model

    #first, define a model
    class ExampleModel(Model):
        example_id      = columns.UUID(primary_key=True, default=uuid.uuid4)
        example_type    = columns.Integer(index=True)
        created_at      = columns.DateTime()
        description     = columns.Text(required=False)

    #next, setup the connection to your cassandra server(s)...
    # see https://docs.datastax.com/en/developer/python-driver/latest/api/cassandra/cluster.html for options
    # the list of hosts will be passed to create a Cluster() instance
    connection.setup(['127.0.0.1'], "cqlengine", protocol_version=3)

    #...and create your CQL table
    >>> sync_table(ExampleModel)

    #now we can create some rows:
    >>> em1 = ExampleModel.create(example_type=0, description="example1", created_at=datetime.now())
    >>> em2 = ExampleModel.create(example_type=0, description="example2", created_at=datetime.now())
    >>> em3 = ExampleModel.create(example_type=0, description="example3", created_at=datetime.now())
    >>> em4 = ExampleModel.create(example_type=0, description="example4", created_at=datetime.now())
    >>> em5 = ExampleModel.create(example_type=1, description="example5", created_at=datetime.now())
    >>> em6 = ExampleModel.create(example_type=1, description="example6", created_at=datetime.now())
    >>> em7 = ExampleModel.create(example_type=1, description="example7", created_at=datetime.now())
    >>> em8 = ExampleModel.create(example_type=1, description="example8", created_at=datetime.now())

    #and now we can run some queries against our table
    >>> ExampleModel.objects.count()
    8
    >>> q = ExampleModel.objects(example_type=1)
    >>> q.count()
    4
    >>> for instance in q:
    >>>     print(instance.description)
    example5
    example6
    example7
    example8

    #here we are applying additional filtering to an existing query
    #query objects are immutable, so calling filter returns a new
    #query object
    >>> q2 = q.filter(example_id=em5.example_id)

    >>> q2.count()
    1
    >>> for instance in q2:
    >>>     print(instance.description)
    example5