Lightweight Transactions (Compare-and-set)

Lightweight Transactions (LWTs) are mostly pass-through CQL for the driver. However, the server returns some specialized results indicating the outcome and optional state preceding the transaction.

For pertinent execution parameters, see Statement.serial_consistency_level.

This section discusses working with specialized result sets returned by the server for LWTs, and how to work with them using the driver.

Specialized Results

The result returned from a LWT request is always a single row result. It will always have prepended a special column named [applied]. How this value appears in your results depends on the row factory in use. See below for examples.

The value of this [applied] column is boolean value indicating whether or not the transaction was applied. If True, it is the only column in the result. If False, the additional columns depend on the LWT operation being executed:

• When using a UPDATE ... IF "col" = ... clause, the result will contain the [applied] column, plus the existing columns and values for any columns in the IF clause (and thus the value that caused the transaction to fail).
• When using INSERT ... IF NOT EXISTS, the result will contain the [applied] column, plus all columns and values of the existing row that rejected the transaction.
• UPDATE .. IF EXISTS never has additional columns, regardless of [applied] status.

How the [applied] column manifests depends on the row factory in use. Considering the following (initially empty) table:

CREATE TABLE test.t (
    k int PRIMARY KEY,
    v int,
    x int
)

… the following sections show the expected result for a number of example statements, using the three base row factories.

named_tuple_factory (default)

The name [applied] is not a valid Python identifier, so the square brackets are actually removed from the attribute for the resulting namedtuple. The row always has a boolean column applied in position 0:

>>> session.execute("INSERT INTO t (k,v) VALUES (0,0) IF NOT EXISTS")
Row(applied=True)

>>> session.execute("INSERT INTO t (k,v) VALUES (0,0) IF NOT EXISTS")
Row(applied=False, k=0, v=0, x=None)

>>> session.execute("UPDATE t SET v = 1, x = 2 WHERE k = 0 IF v =0")
Row(applied=True)

>>> session.execute("UPDATE t SET v = 1, x = 2 WHERE k = 0 IF v =0 AND x = 1")
Row(applied=False, v=1, x=2)

tuple_factory

This return type does not refer to names, but the boolean value applied is always present in position 0:

>>> session.execute("INSERT INTO t (k,v) VALUES (0,0) IF NOT EXISTS")
(True,)

>>> session.execute("INSERT INTO t (k,v) VALUES (0,0) IF NOT EXISTS")
(False, 0, 0, None)

>>> session.execute("UPDATE t SET v = 1, x = 2 WHERE k = 0 IF v =0")
(True,)

>>> session.execute("UPDATE t SET v = 1, x = 2 WHERE k = 0 IF v =0 AND x = 1")
(False, 1, 2)

dict_factory

The retuned dict contains the [applied] key:

>>> session.execute("INSERT INTO t (k,v) VALUES (0,0) IF NOT EXISTS")
{u'[applied]': True}

>>> session.execute("INSERT INTO t (k,v) VALUES (0,0) IF NOT EXISTS")
{u'x': 2, u'[applied]': False, u'v': 1}

>>> session.execute("UPDATE t SET v = 1, x = 2 WHERE k = 0 IF v =0")
{u'x': None, u'[applied]': False, u'k': 0, u'v': 0}

>>> session.execute("UPDATE t SET v = 1, x = 2 WHERE k = 0 IF v =0 AND x = 1")
{u'[applied]': True}