Data Manipulation¶

Update parameters¶

The UPDATE, INSERT (and DELETE and BATCH for the TIMESTAMP and TIMEOUT) statements support the following parameters:

• TIMESTAMP: sets the timestamp for the operation. If not specified, the coordinator will use the current time, in microseconds since the Unix epoch (January 1st 1970 at 00:00:00 UTC), at the start of statement execution as the timestamp. This is usually a suitable default. INSERT, UPDATE, DELETE, or BATCH statements USING TIMESTAMP should provide a unique timestamp value, similar to the one implicitly set by the coordinator by default, when the USING TIMESTAMP update parameter is absent. ScyllaDB ensures that query timestamps created by the same coordinator node are unique (even across different shards on the same node). However, timestamps assigned at different nodes are not guaranteed to be globally unique. Note that with a steadily high write rate, timestamp collision is not unlikely. If it happens, e.g. two INSERTS have the same timestamp, a conflict resolution algorithm determines which of the inserted cells prevails (see update ordering for more information):

• TTL: specifies an optional Time To Live (in seconds) for the inserted values. If set, the inserted values are automatically removed from the database after the specified time. Note that the TTL concerns the inserted values, not the columns themselves. This means that any subsequent update of the column will also reset the TTL (to whatever TTL is specified in that update). By default, values never expire. A TTL of 0 is equivalent to no TTL. If the table has a default_time_to_live, a TTL of 0 will remove the TTL for the inserted or updated values. A TTL of null is equivalent to inserting with a TTL of 0. You can read more about TTL in the documentation and also in this ScyllaDB University lesson.

• TIMEOUT: specifies a timeout duration for the specific request. Please refer to the SELECT section for more information.

Update ordering¶

INSERT, UPDATE, and DELETE operations are ordered by their TIMESTAMP.

Ordering of such changes is done at the cell level, where each cell carries a write TIMESTAMP, other attributes related to its expiration when it has a non-zero time-to-live (TTL), and the cell value.

The fundamental rule for ordering cells that insert, update, or delete data in a given row and column is that the cell with the highest timestamp wins.

However, it is possible that multiple such cells will carry the same TIMESTAMP. There could be several reasons for TIMESTAMP collision:

• Benign collision can be caused by “replay” of a mutation, e.g., due to client retry, or due to internal processes. In such cases, the cells are equivalent, and any of them can be selected arbitrarily.

• TIMESTAMP collisions might be normally caused by parallel queries that are served by different coordinator nodes. The coordinators might calculate the same write TIMESTAMP based on their local time in microseconds.

• Collisions might also happen with user-provided timestamps if the application does not guarantee unique timestamps with the USING TIMESTAMP parameter (see Update parameters for more information).

As said above, in the replay case, ordering of cells should not matter, as they carry the same value and same expiration attributes, so picking any of them will reach the same result. However, other TIMESTAMP conflicts must be resolved in a consistent way by all nodes. Otherwise, if nodes would have picked an arbitrary cell in case of a conflict and they would reach different results, reading from different replicas would detect the inconsistency and trigger read-repair that will generate yet another cell that would still conflict with the existing cells, with no guarantee for convergence.

Therefore, ScyllaDB implements an internal, consistent conflict-resolution algorithm that orders cells with conflicting TIMESTAMP values based on other properties, like:

• whether the cell is a tombstone or a live cell,

• whether the cell has an expiration time,

• the cell TTL,

• and finally, what value the cell carries.

The conflict-resolution algorithm is documented in ScyllaDB’s internal documentation and it may be subject to change.

Reliable serialization can be achieved using unique write TIMESTAMP and by using Lightweight Transactions (LWT) to ensure atomicity of INSERT, UPDATE, and DELETE.

Apache Cassandra Query Language (CQL) Reference

Copyright

© 2016, The Apache Software Foundation.

Apache®, Apache Cassandra®, Cassandra®, the Apache feather logo and the Apache Cassandra® Eye logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries. No endorsement by The Apache Software Foundation is implied by the use of these marks.