CONSISTENCY

Sets and displays the consistency level. The consistency level determines the number of replica nodes that must respond for the coordinator node to successfully process a non-lightweight transaction (non-LWT).

The CQL shell supports only read requests (SELECT statements) when the consistency level is set to SERIAL or LOCAL_SERIAL. See Data consistency in the documentation.

To set the consistency level of a lightweight transaction (LWT), use the SERIAL CONSISTENCY command. When using a LWT, you must have both a CONSISTENCY and a SERIAL CONSISTENCY level set. CONSISTENCY cannot be set to SERIAL or LOCAL_SERIAL, only SERIAL CONSISTENCY can be set to SERIAL or LOCAL_SERIAL.

Synopsis

CONSISTENCY [ <consistency_level> ]
Syntax legend
Legend
Syntax conventions Description

UPPERCASE

Literal keyword.

Lowercase

Not literal.

< >

Variable value. Replace with a user-defined value.

[]

Optional. Square brackets ([]) surround optional command arguments. Do not type the square brackets.

( )

Group. Parentheses ( ( ) ) identify a group to choose from. Do not type the parentheses.

|

Or. A vertical bar (|) separates alternative elements. Type any one of the elements. Do not type the vertical bar.

...

Repeatable. An ellipsis ( ... ) indicates that you can repeat the syntax element as often as required.

'<Literal string>'

Single quotation (') marks must surround literal strings in CQL statements. Use single quotation marks to preserve upper case.

{ <key> : <value> }

Map collection. Braces ({ }) enclose map collections or key value pairs. A colon separates the key and the value.

<datatype2

Set, list, map, or tuple. Angle brackets ( < > ) enclose data types in a set, list, map, or tuple. Separate the data types with a comma.

<cql_statement>;

End CQL statement. A semicolon (;) terminates all CQL statements.

[--]

Separate the command line options from the command arguments with two hyphens ( -- ). This syntax is useful when arguments might be mistaken for command line options.

' <<schema\> ... </schema\>> '

Search CQL only: Single quotation marks (') surround an entire XML schema declaration.

@<xml_entity>='<xml_entity_type>'

Search CQL only: Identify the entity and literal value to overwrite the XML element in the schema and solrConfig files.
<consistency_level>

The consistency level. See the documentation for the list of valid levels and their description, which is extensive.

Display the current consistency level

To show the current consistency level, use the CONSISTENCY command with no options.

CONSISTENCY

Current consistency level is ONE.

Set the consistency level

The consistency level determines data availability versus data accuracy for transactions during the CQL shell session. Some settings also may have high impact other transactions occurring in the cluster, such as ALL and SERIAL. The CQL shell setting overrides the consistency-level global setting.

Before changing this setting it is important to understand these topics in the documentation: How the database reads and writes data, Data replication, How QUORUM is calculated, and partition keys. See the documentation for the links.

When you initiate a transaction from the CQL shell, the coordinator node is typically the node where you started cqlsh. If you connect to a remote host, then the remote node is the coordinator.

Write consistency levels
Level Description Usage

ALL

All replica nodes must acknowledge the write.

This write consistency level provides the highest consistency, the highest latency, and the lowest availability of any level.

QUORUM

A quorum of replica nodes across all datacenters must acknowledge the write.

Cross-datacenter communication may incur extra latency.

ONE

At least one replica node must acknowledge the write.

Use for high availability and low consistency.

Note: Astra DB does not support write consistency level ONE.

TWO

At least two replica nodes must acknowledge the write.

Similar to ONE.

THREE

At least three replica nodes must acknowledge the write.

Similar to TWO.

ANY

At least one replica node must acknowledge the write, or if no replica nodes are available, a coordinator node must store a hint. If all replica nodes are down at write time, the data will not be available until the replica nodes for that partition have recovered.

This write consistency level provides the lowest latency, the highest write availability, and the lowest consistency.

Note: Astra DB does not support write consistency level ANY.

LOCAL_QUORUM

A quorum of replica nodes in the local datacenter must acknowledge the write. Avoids latency of cross-datacenter communication.

Use LOCAL_QUORUM to maintain consistency within a single datacenter in a multiple-datacenter cluster.

EACH_QUORUM

A quorum of replica nodes in the each datacenter must acknowledge the write.

Use EACH_QUORUM in multi-datacenter clusters to strictly maintain consistency at the same level in each datacenter. Writes will fail if any datacenter fails to achieve a quorum.

LOCAL_ONE

At least one replica node in the local datacenter must acknowledge the write.

Use LOCAL_ONE to a consistency level of ONE without cross-datacenter communication.

Note: Astra DB does not support write consistency level LOCAL_ONE.

SERIAL

Write consistency level SERIAL is a special case for compare and set operations like INSERT, UPDATE, and DELETE operations that use an IF clause.

Use to achieve linearizable consistency for lightweight transactions.

LOCAL_SERIAL

Write consistency level LOCAL_SERIAL is the same as SERIAL, but confined to the local datacenter.

Use to achieve linearizable consistency for lightweight transactions.
Read consistency levels
Level Description Usage

ALL

Queries return the most recent data from all replica nodes in the cluster. All replica nodes must must respond.

This read consistency level provides the highest consistency, the highest latency, and the lowest availability of any level.

QUORUM

Queries return the most recent data from a quorum of replica nodes across all datacenters.

Cross-datacenter communication may incur extra latency.

ONE

Queries return data from the closest replica.

Use for high availability and low consistency.

TWO

Queries return the most recent data from two of the closest replicas. Two replica nodes must respond.

Similar to ONE.

THREE

Queries return the most recent data from three of the closest replicas. Three replica nodes must respond.

Similar to TWO.

LOCAL_QUORUM

Queries returns the most recent data from a quorum of replicas in the current datacenter. LOCAL_QUORUM avoids latency of cross-datacenter communication.

Use LOCAL_QUORUM to maintain consistency within a single datacenter in a multiple-datacenter cluster.

EACH_QUORUM

Queries return the most recent data from a quorum of replica nodes in each datacenter has responded.

Use EACH_QUORUM in multiple datacenter clusters to ensure data consistency at the same level in each datacenter. Queries will fail if any datacenter fails to achieve a quorum.

LOCAL_ONE

Queries return data from the closest replica node in the local datacenter.

Use LOCAL_ONE to achieve a consistency level of ONE without cross-datacenter communications.

SERIAL

Read consistency level SERIAL is a special case for querying data that may be involved in in-flight lightweight transactions.

Use to achieve linearizable consistency for lightweight transactions.

LOCAL_SERIAL

Read consistency level LOCAL_SERIAL is the same as SERIAL, but confined to the local datacenter.

Use to achieve linearizable consistency for lightweight transactions.

Examples

Set the CONSISTENCY QUORUM level to force the majority of the nodes to respond:

CONSISTENCY QUORUM

Set the level to serial for LWT read requests:

CONSISTENCY SERIAL
Consistency level set to SERIAL.

Query that returns all cycling race winners:

SELECT *
FROM cycling.race_winners;

The query results are as follows:

@ Row 1
---------------+--------------------------------------------------
 race_name     | National Championships South Africa WJ-ITT (CN)
 race_position | 1
 cyclist_name  | {firstname: 'Frances', lastname: 'DU TOUT'}

@ Row 2
---------------+--------------------------------------------------
 race_name     | National Championships South Africa WJ-ITT (CN)
 race_position | 2
 cyclist_name  | {firstname: 'Lynette', lastname: 'BENSON'}

@ Row 3
---------------+--------------------------------------------------
 race_name     | National Championships South Africa WJ-ITT (CN)
 race_position | 3
 cyclist_name  | {firstname: 'Anja', lastname: 'GERBER'}

@ Row 4
---------------+--------------------------------------------------
 race_name     | National Championships South Africa WJ-ITT (CN)
 race_position | 4
 cyclist_name  | {firstname: 'Ame', lastname: 'VENTER'}

@ Row 5
---------------+--------------------------------------------------
 race_name     | National Championships South Africa WJ-ITT (CN)
 race_position | 5
 cyclist_name  | {firstname: 'Danielle', lastname: 'VAN NIEKERK'}

(5 rows)

The previous query format uses expand ON for legibility.

A LWT is a write request that contains IF EXISTS or IF NOT EXISTS statements. To set the consistency level of LWTs, see SERIAL CONSISTENCY. When using a LWT, you must have both a CONSISTENCY and a SERIAL CONSISTENCY level set. CONSISTENCY cannot be set to SERIAL or LOCAL_SERIAL, only SERIAL CONSISTENCY can be set to SERIAL or LOCAL_SERIAL.

The following examples show LWT failure scenarios. Inserts for a LWT with CONSISTENCY SERIAL fail:

CONSISTENCY SERIAL

INSERT INTO cycling.race_winners (
  race_name,
  race_position,
  cyclist_name
) VALUES (
  'National Championships South Africa WJ-ITT (CN)',
  7,
  { firstname: 'Joe', lastname: 'Anderson' }
)
IF NOT EXISTS;
InvalidRequest: Error from server: code=2200 [Invalid query]
message="SERIAL is not supported as conditional update commit
consistency. Use ANY if you mean "make sure it is accepted but I don't
care how many replicas commit it for non-SERIAL reads""

Updates for a LWT with CONSISTENCY SERIAL also fail:

CONSISTENCY SERIAL

UPDATE cycling.race_winners SET
  cyclist_name = { firstname: 'JOHN', lastname: 'DOE' }
WHERE
  race_name='National Championships South Africa WJ-ITT (CN)'
  AND race_position = 6
IF EXISTS;
InvalidRequest: Error from server: code=2200 [Invalid query]
message="SERIAL is not supported as conditional update commit
consistency. Use ANY if you mean "make sure it is accepted but I don't
care how many replicas commit it for non-SERIAL reads""

Omitting the IF clause generates errors. Also, using CONSISTENCY LOCAL_SERIAL generates the errors as that consistency level results in an invalid request.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com