_position = 0

if len(hosts) > 1:

:annotation: = <cassandra.policies.RetryPolicy object>

.. automethod:: add_execution_profile

.. autoclass:: ExecutionProfile

:members:

.. autodata:: EXEC_PROFILE_DEFAULT

:annotation:

:annotation: = 10.0

:annotation: = None

:annotation: = <function named_tuple_factory>

.. automethod:: execution_profile_clone_update

Execution Profiles (experimental)

Execution profiles are an experimental API aimed at making it easier to execute requests in different ways within

a single connected ``Session``. Execution profiles are being introduced to deal with the exploding number of

configuration options, especially as the database platform evolves more complex workloads.

The Execution Profile API is being introduced now, in an experimental capacity in order to take advantage of it in

existing projects, and to gauge interest and feedback in the community. For now, the legacy configuration remains

intact, but legacy and Execution Profile APIs cannot be used simultaneously on the same client ``Cluster``.

This document explains how Execution Profiles relate to existing settings, and shows how to use the new profiles for

request execution.

Mapping Legacy Parameters to Profiles

Execution profiles can inherit from :class:`.cluster.ExecutionProfile`, and currently provide the following options,

previously input from the noted attributes:

- load_balancing_policy - :attr:`.Cluster.load_balancing_policy`

- request_timeout - :attr:`.Session.default_timeout`, optional :meth:`.Session.execute` parameter

- retry_policy - :attr:`.Cluster.default_retry_policy`, optional :attr:`.Statement.retry_policy` attribute

- consistency_level - :attr:`.Session.default_consistency_level`, optional :attr:`.Statement.consistency_level` attribute

- serial_consistency_level - :attr:`.Session.default_serial_consistency_level`, optional :attr:`.Statement.serial_consistency_level` attribute

- row_factory - :attr:`.Session.row_factory` attribute

When using the new API, these parameters can be defined by instances of :class:`.cluster.ExecutionProfile`.

Using Execution Profiles

Default

.. code:: python

.. parsed-literal::

The default execution profile is built from Cluster parameters and default Session attributes. This profile matches existing default

parameters.

Initializing cluster with profiles

.. code:: python

.. parsed-literal::

.. code:: python

.. parsed-literal::

.. code:: python

.. parsed-literal::

Note that, even when custom profiles are injected, the default ``TokenAwarePolicy(DCAwareRoundRobinPolicy())`` is still

present. To override the default, specify a policy with the :data:`~.cluster.EXEC_PROFILE_DEFAULT` key.

.. code:: python

Adding named profiles

New profiles can be added constructing from scratch, or deriving from default:

.. code:: python

.. parsed-literal::

See :meth:`.Cluster.add_execution_profile` for details and optional parameters.

Passing a profile instance without mapping

We also have the ability to pass profile instances to be used for execution, but not added to the mapping:

.. code:: python

.. parsed-literal::

The new profile is a shallow copy, so the ``tmp`` profile shares a load balancing policy with one managed by the cluster.

If reference objects are to be updated in the clone, one would typically set those attributes to a new instance.

A guide through the first steps of connecting to Cassandra and executing queries

A guide to upgrading versions of the driver

:doc:`execution_profiles`

An introduction to a more flexible way of configuring request execution

Notes on paging large query results

Working with Cassandra 2.1's user-defined types

An overview of the security features of the driver

execution_profiles

from copy import copy

from cassandra.cluster import Cluster, NoHostAvailable, ExecutionProfile, EXEC_PROFILE_DEFAULT

from cassandra.query import SimpleStatement, TraceUnavailable, tuple_factory

def test_profile_load_balancing(self):

query = "select release_version from system.local"

node1 = ExecutionProfile(load_balancing_policy=WhiteListRoundRobinPolicy(['127.0.0.1']))

with Cluster(execution_profiles={'node1': node1}) as cluster:

session = cluster.connect()

# default is DCA RR for all hosts

expected_hosts = set(cluster.metadata.all_hosts())

queried_hosts = set()

for _ in expected_hosts:

rs = session.execute(query)

queried_hosts.add(rs.response_future._current_host)

self.assertEqual(queried_hosts, expected_hosts)

# by name we should only hit the one

expected_hosts = set(h for h in cluster.metadata.all_hosts() if h.address == '127.0.0.1')

queried_hosts = set()

for _ in cluster.metadata.all_hosts():

rs = session.execute(query, execution_profile='node1')

queried_hosts.add(rs.response_future._current_host)

self.assertEqual(queried_hosts, expected_hosts)

# use a copied instance and override the row factory

# assert last returned value can be accessed as a namedtuple so we can prove something different

named_tuple_row = rs[0]

self.assertIsInstance(named_tuple_row, tuple)

self.assertTrue(named_tuple_row.release_version)

tmp_profile = copy(node1)

tmp_profile.row_factory = tuple_factory

queried_hosts = set()

for _ in cluster.metadata.all_hosts():

rs = session.execute(query, execution_profile=tmp_profile)

queried_hosts.add(rs.response_future._current_host)

self.assertEqual(queried_hosts, expected_hosts)

tuple_row = rs[0]

self.assertIsInstance(tuple_row, tuple)

with self.assertRaises(AttributeError):

tuple_row.release_version

# make sure original profile is not impacted

self.assertTrue(session.execute(query, execution_profile='node1')[0].release_version)

def test_profile_pool_management(self):

node1 = ExecutionProfile(load_balancing_policy=WhiteListRoundRobinPolicy(['127.0.0.1']))

node2 = ExecutionProfile(load_balancing_policy=WhiteListRoundRobinPolicy(['127.0.0.2']))

with Cluster(execution_profiles={EXEC_PROFILE_DEFAULT: node1, 'node2': node2}) as cluster:

session = cluster.connect()

pools = session.get_pool_state()

# there are more hosts, but we connected to the ones in the lbp aggregate

self.assertGreater(len(cluster.metadata.all_hosts()), 2)

self.assertEqual(set(h.address for h in pools), set(('127.0.0.1', '127.0.0.2')))

# dynamically update pools on add

node3 = ExecutionProfile(load_balancing_policy=WhiteListRoundRobinPolicy(['127.0.0.3']))

cluster.add_execution_profile('node3', node3)

pools = session.get_pool_state()

self.assertEqual(set(h.address for h in pools), set(('127.0.0.1', '127.0.0.2', '127.0.0.3')))

def test_add_profile_timeout(self):

node1 = ExecutionProfile(load_balancing_policy=WhiteListRoundRobinPolicy(['127.0.0.1']))

with Cluster(execution_profiles={EXEC_PROFILE_DEFAULT: node1}) as cluster:

session = cluster.connect()

pools = session.get_pool_state()

self.assertGreater(len(cluster.metadata.all_hosts()), 2)

self.assertEqual(set(h.address for h in pools), set(('127.0.0.1',)))

node2 = ExecutionProfile(load_balancing_policy=WhiteListRoundRobinPolicy(['127.0.0.2']))

self.assertRaises(cassandra.OperationTimedOut, cluster.add_execution_profile, 'node2', node2, pool_wait_timeout=0.0000001)