natas_hw
/
cassandra
mirror of https://github.com/apache/cassandra
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

CASSANDRA-20117: fixed typos in NTR spec and SASI documents

This commit is contained in:
Schoening, Brad 2025-03-25 16:21:19 -04:00 committed by Brad Schoening
parent a449a4f76b
commit 5aadbc62f0
4 changed files with 106 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/SASI.md
View File

@ -199,7 +199,7 @@ cqlsh:demo> SELECT first_name, last_name, age, height, created_at FROM sasi
SASI supports queries with multiple predicates, however, due to the SASI supports queries with multiple predicates, however, due to the
nature of the default indexing implementation, CQL requires the user nature of the default indexing implementation, CQL requires the user
to specify `ALLOW FILTERING` to opt-in to the potential performance to specify `ALLOW FILTERING` to opt in to the potential performance
pitfalls of such a query. With SASI, while the requirement to include pitfalls of such a query. With SASI, while the requirement to include
`ALLOW FILTERING` remains, to reduce modifications to the grammar, the `ALLOW FILTERING` remains, to reduce modifications to the grammar, the
performance pitfalls do not exist because filtering is not performance pitfalls do not exist because filtering is not
@ -383,7 +383,7 @@ of the memtable to disk -- this is the origin of the name "SSTable
Attached Secondary Index". Attached Secondary Index".
The SASI index data structures are built in memory as the SSTable is The SASI index data structures are built in memory as the SSTable is
being written and they are flushed to disk before the writing of the being written, and they are flushed to disk before the writing of the
SSTable completes. The writing of each index file only requires SSTable completes. The writing of each index file only requires
sequential writes to disk. In some cases, partial flushes are sequential writes to disk. In some cases, partial flushes are
performed, and later stitched back together, to reduce memory performed, and later stitched back together, to reduce memory
@ -467,7 +467,7 @@ collision.
To optimize for its write-once environment the To optimize for its write-once environment the
[`TokenTreeBuilder`](https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/index/sasi/disk/TokenTreeBuilder.java) [`TokenTreeBuilder`](https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/index/sasi/disk/TokenTreeBuilder.java)
completely loads its interior nodes as the tree is built and it uses completely loads its interior nodes as the tree is built, and it uses
the well-known algorithm optimized for bulk-loading the data the well-known algorithm optimized for bulk-loading the data
structure. structure.
@ -562,7 +562,7 @@ been found, or there is no more matching data, the result set is
returned to the coordinator through the existing internal components. returned to the coordinator through the existing internal components.
The number of queries (total/failed/timed-out), and their latencies, The number of queries (total/failed/timed-out), and their latencies,
are maintined per-table/column family. are maintained per-table/column family.
SASI also supports concurrently iterating terms for the same index SASI also supports concurrently iterating terms for the same index
across SSTables. The concurrency factor is controlled by the across SSTables. The concurrency factor is controlled by the
@ -713,7 +713,7 @@ the documentation
The abstract `RangeIterator` class provides a unified interface over The abstract `RangeIterator` class provides a unified interface over
the two main operations performed by SASI at various layers in the the two main operations performed by SASI at various layers in the
execution path: set intersection and union. These operations are execution path: set intersection and union. These operations are
performed in a iterated, or "streaming", fashion to prevent unneeded performed in an iterated, or "streaming", fashion to prevent unneeded
reads of elements from either set. In both the intersection and union reads of elements from either set. In both the intersection and union
cases the algorithms take advantage of the data being pre-sorted using cases the algorithms take advantage of the data being pre-sorted using
the same sort order, e.g. term or token order. the same sort order, e.g. term or token order.
@ -725,7 +725,7 @@ performs the "Merge-Join" portion of the
algorithm, with the properties of an outer-join, or union. It is algorithm, with the properties of an outer-join, or union. It is
implemented with several optimizations to improve its performance over implemented with several optimizations to improve its performance over
a large number of iterators -- sets to union. Specifically, the a large number of iterators -- sets to union. Specifically, the
iterator exploits the likely case of the data having many sub-groups iterator exploits the likely case of the data having many subgroups
of overlapping ranges and the unlikely case that all ranges will of overlapping ranges and the unlikely case that all ranges will
overlap each other. For more details see the overlap each other. For more details see the
[javadoc](https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/index/sasi/utils/RangeUnionIterator.java#L9-L21). [javadoc](https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/index/sasi/utils/RangeUnionIterator.java#L9-L21).
@ -742,7 +742,7 @@ between them based on some properties of the data.
the the
[`RangeUnionIterator`](https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/index/sasi/utils/RangeUnionIterator.java) [`RangeUnionIterator`](https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/index/sasi/utils/RangeUnionIterator.java)
in that it performs a "Merge-Join", however, its nature is similar to in that it performs a "Merge-Join", however, its nature is similar to
a inner-join, where like values are merged by a data-specific merge an inner-join, where like values are merged by a data-specific merge
function (e.g. merging two tokens in a list to lookup in a SSTable function (e.g. merging two tokens in a list to lookup in a SSTable
later). See the later). See the
[javadoc](https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/index/sasi/utils/RangeIntersectionIterator.java#L88-L101) [javadoc](https://github.com/apache/cassandra/blob/trunk/src/java/org/apache/cassandra/index/sasi/utils/RangeIntersectionIterator.java#L88-L101)

44
doc/native_protocol_v3.spec
View File

@ -228,7 +228,7 @@ Table of Contents
representing the port. representing the port.
[consistency] A consistency level specification. This is a [short] [consistency] A consistency level specification. This is a [short]
representing a consistency level with the following representing a consistency level with the following
correspondance: correspondence:
0x0000 ANY 0x0000 ANY
0x0001 ONE 0x0001 ONE
0x0002 TWO 0x0002 TWO
@ -267,7 +267,7 @@ Table of Contents
The body is a [string map] of options. Possible options are: The body is a [string map] of options. Possible options are:
- "CQL_VERSION": the version of CQL to use. This option is mandatory and - "CQL_VERSION": the version of CQL to use. This option is mandatory and
currenty, the only version supported is "3.0.0". Note that this is currently, the only version supported is "3.0.0". Note that this is
different from the protocol version. different from the protocol version.
- "COMPRESSION": the compression algorithm to use for frames (See section 5). - "COMPRESSION": the compression algorithm to use for frames (See section 5).
This is optional, if not specified no compression will be used. This is optional, if not specified no compression will be used.
@ -316,8 +316,8 @@ Table of Contents
values are provided. Those value are used for bound variables in values are provided. Those value are used for bound variables in
the query. Optionally, if the 0x40 flag is present, each value the query. Optionally, if the 0x40 flag is present, each value
will be preceded by a [string] name, representing the name of will be preceded by a [string] name, representing the name of
the marker the value must be binded to. This is optional, and the marker the value must be bound to. This is optional, and
if not present, values will be binded by position. if not present, values will be bound by position.
0x02: Skip_metadata. If present, the Result Set returned as a response 0x02: Skip_metadata. If present, the Result Set returned as a response
to that query (if any) will have the NO_METADATA flag (see to that query (if any) will have the NO_METADATA flag (see
Section 4.2.5.2). Section 4.2.5.2).
@ -332,8 +332,8 @@ Table of Contents
started (See Section 8 for more details). started (See Section 8 for more details).
0x10: With serial consistency. If present, <serial_consistency> should be 0x10: With serial consistency. If present, <serial_consistency> should be
present. <serial_consistency> is the [consistency] level for the present. <serial_consistency> is the [consistency] level for the
serial phase of conditional updates. That consitency can only be serial phase of conditional updates. Consistency can be
either SERIAL or LOCAL_SERIAL and if not present, it defaults to either SERIAL or LOCAL_SERIAL, if not present, it defaults to
SERIAL. This option will be ignored for anything else that a SERIAL. This option will be ignored for anything else that a
conditional update/insert. conditional update/insert.
0x20: With default timestamp. If present, <timestamp> should be present. 0x20: With default timestamp. If present, <timestamp> should be present.
@ -400,8 +400,8 @@ Table of Contents
flags are, given there mask: flags are, given there mask:
0x10: With serial consistency. If present, <serial_consistency> should be 0x10: With serial consistency. If present, <serial_consistency> should be
present. <serial_consistency> is the [consistency] level for the present. <serial_consistency> is the [consistency] level for the
serial phase of conditional updates. That consitency can only be serial phase of conditional updates. Consistency can be
either SERIAL or LOCAL_SERIAL and if not present, it defaults to either SERIAL or LOCAL_SERIAL, if not present, it defaults to
SERIAL. This option will be ignored for anything else that a SERIAL. This option will be ignored for anything else that a
conditional update/insert. conditional update/insert.
0x20: With default timestamp. If present, <timestamp> should be present. 0x20: With default timestamp. If present, <timestamp> should be present.
@ -435,8 +435,8 @@ Table of Contents
- <consistency> is the [consistency] level for the operation. - <consistency> is the [consistency] level for the operation.
- <serial_consistency> is only present if the 0x10 flag is set. In that case, - <serial_consistency> is only present if the 0x10 flag is set. In that case,
<serial_consistency> is the [consistency] level for the serial phase of <serial_consistency> is the [consistency] level for the serial phase of
conditional updates. That consitency can only be either SERIAL or conditional updates. Consistency can be either SERIAL or
LOCAL_SERIAL and if not present will defaults to SERIAL. This option will LOCAL_SERIAL, if not present, it defaults to SERIAL. This option will
be ignored for anything else that a conditional update/insert. be ignored for anything else that a conditional update/insert.
The server will respond with a RESULT message. The server will respond with a RESULT message.
@ -461,7 +461,7 @@ Table of Contents
This section describes the content of the frame body for the different This section describes the content of the frame body for the different
responses. Please note that to make room for future evolution, clients should responses. Please note that to make room for future evolution, clients should
support extra informations (that they should simply discard) to the one support extra information (that they should simply discard) to the one
described in this document at the end of the frame body. described in this document at the end of the frame body.
4.2.1. ERROR 4.2.1. ERROR
@ -488,7 +488,7 @@ Table of Contents
The authentication is SASL based and thus consists on a number of server The authentication is SASL based and thus consists on a number of server
challenges (AUTH_CHALLENGE, Section 4.2.7) followed by client responses challenges (AUTH_CHALLENGE, Section 4.2.7) followed by client responses
(AUTH_RESPONSE, Section 4.1.2). The Initial exchange is however boostrapped (AUTH_RESPONSE, Section 4.1.2). The Initial exchange is however bootstrapped
by an initial client response. The details of that exchange (including how by an initial client response. The details of that exchange (including how
much challenge-response pair are required) are specific to the authenticator much challenge-response pair are required) are specific to the authenticator
in use. The exchange ends when the server sends an AUTH_SUCCESS message or in use. The exchange ends when the server sends an AUTH_SUCCESS message or
@ -541,7 +541,7 @@ Table of Contents
<flags><columns_count>[<paging_state>][<global_table_spec>?<col_spec_1>...<col_spec_n>] <flags><columns_count>[<paging_state>][<global_table_spec>?<col_spec_1>...<col_spec_n>]
where: where:
- <flags> is an [int]. The bits of <flags> provides information on the - <flags> is an [int]. The bits of <flags> provides information on the
formatting of the remaining informations. A flag is set if the bit formatting of the remaining information. A flag is set if the bit
corresponding to its `mask` is set. Supported flags are, given there corresponding to its `mask` is set. Supported flags are, given there
mask: mask:
0x0001 Global_tables_spec: if set, only one table spec (keyspace 0x0001 Global_tables_spec: if set, only one table spec (keyspace
@ -555,7 +555,7 @@ Table of Contents
this query (See Section 8 for more details). this query (See Section 8 for more details).
0x0004 No_metadata: if set, the <metadata> is only composed of 0x0004 No_metadata: if set, the <metadata> is only composed of
these <flags>, the <column_count> and optionally the these <flags>, the <column_count> and optionally the
<paging_state> (depending on the Has_more_pages flage) but <paging_state> (depending on the Has_more_pages flag) but
no other information (so no <global_table_spec> nor <col_spec_i>). no other information (so no <global_table_spec> nor <col_spec_i>).
This will only ever be the case if this was requested This will only ever be the case if this was requested
during the query (see QUERY and RESULT messages). during the query (see QUERY and RESULT messages).
@ -567,8 +567,8 @@ Table of Contents
(unique) keyspace name and table name the columns return are of. (unique) keyspace name and table name the columns return are of.
- <col_spec_i> specifies the columns returned in the query. There is - <col_spec_i> specifies the columns returned in the query. There is
<column_count> such column specifications that are composed of: <column_count> such column specifications that are composed of:
(<ksname><tablename>)?<name><type> (<ks_name><table_name>)?<name><type>
The initial <ksname> and <tablename> are two [string] are only present The initial <ks_name> and <table_name> are two [string] are only present
if the Global_tables_spec flag is not set. The <column_name> is a if the Global_tables_spec flag is not set. The <column_name> is a
[string] and <type> is an [option] that correspond to the description [string] and <type> is an [option] that correspond to the description
(what this description is depends a bit on the context: in results to (what this description is depends a bit on the context: in results to
@ -608,7 +608,7 @@ Table of Contents
- <ks> is a [string] representing the keyspace name this - <ks> is a [string] representing the keyspace name this
UDT is part of. UDT is part of.
- <udt_name> is a [string] representing the UDT name. - <udt_name> is a [string] representing the UDT name.
- <n> is a [short] reprensenting the number of fields of - <n> is a [short] representing the number of fields of
the UDT, and thus the number of <name_i><type_i> pair the UDT, and thus the number of <name_i><type_i> pair
following following
- <name_i> is a [string] representing the name of the - <name_i> is a [string] representing the name of the
@ -657,7 +657,7 @@ Table of Contents
Note that prepared query ID return is global to the node on which the query Note that prepared query ID return is global to the node on which the query
has been prepared. It can be used on any connection to that node and this has been prepared. It can be used on any connection to that node and this
until the node is restarted (after which the query must be reprepared). until the node is restarted (after which the query must be re-prepared).
4.2.5.5. Schema_change 4.2.5.5. Schema_change
@ -759,7 +759,7 @@ Table of Contents
bytes). bytes).
- snappy (https://code.google.com/p/snappy/). This compression might not be - snappy (https://code.google.com/p/snappy/). This compression might not be
available as it depends on a native lib (server-side) that might not be available as it depends on a native lib (server-side) that might not be
avaivable on some installation. available on some installation.
6. Data Type Serialization Formats 6. Data Type Serialization Formats
@ -981,7 +981,7 @@ Table of Contents
<blockfor> is an [int] representing the number of replica whose <blockfor> is an [int] representing the number of replica whose
acknowledgement is required to achieve <cl>. acknowledgement is required to achieve <cl>.
<writeType> is a [string] that describe the type of the write <writeType> is a [string] that describe the type of the write
that timeouted. The value of that string can be one that timed out. The value of that string can be one
of: of:
- "SIMPLE": the write was a non-batched - "SIMPLE": the write was a non-batched
non-counter write. non-counter write.
@ -993,10 +993,10 @@ Table of Contents
batch. Not batch log write has been attempted. batch. Not batch log write has been attempted.
- "COUNTER": the write was a counter write - "COUNTER": the write was a counter write
(batched or not). (batched or not).
- "BATCH_LOG": the timeout occured during the - "BATCH_LOG": the timeout occurred during the
write to the batch log when a (logged) batch write to the batch log when a (logged) batch
write was requested. write was requested.
- "CAS": the timeout occured during the Compare And Set write/update. - "CAS": the timeout occurred during the Compare And Set write/update.
0x1200 Read_timeout: Timeout exception during a read request. The rest 0x1200 Read_timeout: Timeout exception during a read request. The rest
of the ERROR message body will be of the ERROR message body will be
<cl><received><blockfor><data_present> <cl><received><blockfor><data_present>

58
doc/native_protocol_v4.spec
View File

@ -245,7 +245,7 @@ Table of Contents
representing the port. representing the port.
[consistency] A consistency level specification. This is a [short] [consistency] A consistency level specification. This is a [short]
representing a consistency level with the following representing a consistency level with the following
correspondance: correspondence:
0x0000 ANY 0x0000 ANY
0x0001 ONE 0x0001 ONE
0x0002 TWO 0x0002 TWO
@ -366,8 +366,8 @@ Table of Contents
started (See Section 8 for more details). started (See Section 8 for more details).
0x10: With serial consistency. If set, <serial_consistency> should be 0x10: With serial consistency. If set, <serial_consistency> should be
present. <serial_consistency> is the [consistency] level for the present. <serial_consistency> is the [consistency] level for the
serial phase of conditional updates. That consitency can only be serial phase of conditional updates. Consistency can be
either SERIAL or LOCAL_SERIAL and if not present, it defaults to SERIAL or LOCAL_SERIAL, if not present, it defaults to
SERIAL. This option will be ignored for anything else other than a SERIAL. This option will be ignored for anything else other than a
conditional update/insert. conditional update/insert.
0x20: With default timestamp. If set, <timestamp> should be present. 0x20: With default timestamp. If set, <timestamp> should be present.
@ -432,8 +432,8 @@ Table of Contents
flags are, given their mask: flags are, given their mask:
0x10: With serial consistency. If set, <serial_consistency> should be 0x10: With serial consistency. If set, <serial_consistency> should be
present. <serial_consistency> is the [consistency] level for the present. <serial_consistency> is the [consistency] level for the
serial phase of conditional updates. That consistency can only be serial phase of conditional updates. Consistency can be
either SERIAL or LOCAL_SERIAL and if not present, it defaults to either SERIAL or LOCAL_SERIAL, and if not present, it defaults to
SERIAL. This option will be ignored for anything else other than a SERIAL. This option will be ignored for anything else other than a
conditional update/insert. conditional update/insert.
0x20: With default timestamp. If set, <timestamp> should be present. 0x20: With default timestamp. If set, <timestamp> should be present.
@ -467,8 +467,8 @@ Table of Contents
- <consistency> is the [consistency] level for the operation. - <consistency> is the [consistency] level for the operation.
- <serial_consistency> is only present if the 0x10 flag is set. In that case, - <serial_consistency> is only present if the 0x10 flag is set. In that case,
<serial_consistency> is the [consistency] level for the serial phase of <serial_consistency> is the [consistency] level for the serial phase of
conditional updates. That consitency can only be either SERIAL or conditional updates. Consistency can be SERIAL or
LOCAL_SERIAL and if not present will defaults to SERIAL. This option will LOCAL_SERIAL, if not present, it defaults to SERIAL. This option will
be ignored for anything else other than a conditional update/insert. be ignored for anything else other than a conditional update/insert.
The server will respond with a RESULT message. The server will respond with a RESULT message.
@ -493,7 +493,7 @@ Table of Contents
This section describes the content of the frame body for the different This section describes the content of the frame body for the different
responses. Please note that to make room for future evolution, clients should responses. Please note that to make room for future evolution, clients should
support extra informations (that they should simply discard) to the one support extra information (that they should simply discard) to the one
described in this document at the end of the frame body. described in this document at the end of the frame body.
4.2.1. ERROR 4.2.1. ERROR
@ -521,7 +521,7 @@ Table of Contents
The authentication is SASL based and thus consists of a number of server The authentication is SASL based and thus consists of a number of server
challenges (AUTH_CHALLENGE, Section 4.2.7) followed by client responses challenges (AUTH_CHALLENGE, Section 4.2.7) followed by client responses
(AUTH_RESPONSE, Section 4.1.2). The initial exchange is however boostrapped (AUTH_RESPONSE, Section 4.1.2). The initial exchange is however bootstrapped
by an initial client response. The details of that exchange (including how by an initial client response. The details of that exchange (including how
many challenge-response pairs are required) are specific to the authenticator many challenge-response pairs are required) are specific to the authenticator
in use. The exchange ends when the server sends an AUTH_SUCCESS message or in use. The exchange ends when the server sends an AUTH_SUCCESS message or
@ -600,8 +600,8 @@ Table of Contents
(unique) keyspace name and table name the columns belong to. (unique) keyspace name and table name the columns belong to.
- <col_spec_i> specifies the columns returned in the query. There are - <col_spec_i> specifies the columns returned in the query. There are
<column_count> such column specifications that are composed of: <column_count> such column specifications that are composed of:
(<ksname><tablename>)?<name><type> (<ks_name><table_name>)?<name><type>
The initial <ksname> and <tablename> are two [string] and are only present The initial <ks_name> and <table_name> are two [string] and are only present
if the Global_tables_spec flag is not set. The <column_name> is a if the Global_tables_spec flag is not set. The <column_name> is a
[string] and <type> is an [option] that corresponds to the description [string] and <type> is an [option] that corresponds to the description
(what this description is depends a bit on the context: in results to (what this description is depends a bit on the context: in results to
@ -713,8 +713,8 @@ Table of Contents
- <col_spec_i> specifies the bind markers in the prepared statement. - <col_spec_i> specifies the bind markers in the prepared statement.
There are <column_count> such column specifications, each with the There are <column_count> such column specifications, each with the
following format: following format:
(<ksname><tablename>)?<name><type> (<ks_name><table_name>)?<name><type>
The initial <ksname> and <tablename> are two [string] that are only The initial <ks_name> and <table_name> are two [string] that are only
present if the Global_tables_spec flag is not set. The <name> field present if the Global_tables_spec flag is not set. The <name> field
is a [string] that holds the name of the bind marker (if named), is a [string] that holds the name of the bind marker (if named),
or the name of the column, field, or expression that the bind marker or the name of the column, field, or expression that the bind marker
@ -737,7 +737,7 @@ Table of Contents
Note that the prepared query ID returned is global to the node on which the query Note that the prepared query ID returned is global to the node on which the query
has been prepared. It can be used on any connection to that node has been prepared. It can be used on any connection to that node
until the node is restarted (after which the query must be reprepared). until the node is restarted (after which the query must be re-prepared).
4.2.5.5. Schema_change 4.2.5.5. Schema_change
@ -754,7 +754,7 @@ Table of Contents
4.2.6. EVENT 4.2.6. EVENT
An event pushed by the server. A client will only receive events for the An event pushed by the server. A client will only receive events for the
types it has REGISTERed to. The body of an EVENT message will start with a types it has REGISTER-ed to. The body of an EVENT message will start with a
[string] representing the event type. The rest of the message depends on the [string] representing the event type. The rest of the message depends on the
event type. The valid event types are: event type. The valid event types are:
- "TOPOLOGY_CHANGE": events related to change in the cluster topology. - "TOPOLOGY_CHANGE": events related to change in the cluster topology.
@ -842,7 +842,7 @@ Table of Contents
bytes). bytes).
- snappy (https://code.google.com/p/snappy/). This compression might not be - snappy (https://code.google.com/p/snappy/). This compression might not be
available as it depends on a native lib (server-side) that might not be available as it depends on a native lib (server-side) that might not be
avaivable on some installations. available on some installations.
6. Data Type Serialization Formats 6. Data Type Serialization Formats
@ -1099,11 +1099,11 @@ Table of Contents
- "BATCH_LOG": the timeout occurred during the - "BATCH_LOG": the timeout occurred during the
write to the batch log when a (logged) batch write to the batch log when a (logged) batch
write was requested. write was requested.
- "CAS": the timeout occured during the Compare And Set write/update. - "CAS": the timeout occurred during the Compare And Set write/update.
- "VIEW": the timeout occured when a write involves - "VIEW": the timeout occurred when a write involves
VIEW update and failure to acqiure local view(MV) VIEW update and failure to acquire local view(MV)
lock for key within timeout lock for key within timeout
- "CDC": the timeout occured when cdc_total_space is - "CDC": the timeout occurred when cdc_total_space is
exceeded when doing a write to data tracked by cdc. exceeded when doing a write to data tracked by cdc.
0x1200 Read_timeout: Timeout exception during a read request. The rest 0x1200 Read_timeout: Timeout exception during a read request. The rest
of the ERROR message body will be of the ERROR message body will be
@ -1124,7 +1124,7 @@ Table of Contents
responded. Otherwise, the value is != 0. responded. Otherwise, the value is != 0.
0x1300 Read_failure: A non-timeout exception during a read request. The rest 0x1300 Read_failure: A non-timeout exception during a read request. The rest
of the ERROR message body will be of the ERROR message body will be
<cl><received><blockfor><numfailures><data_present> <cl><received><blockfor><num_failures><data_present>
where: where:
<cl> is the [consistency] level of the query having triggered <cl> is the [consistency] level of the query having triggered
the exception. the exception.
@ -1132,7 +1132,7 @@ Table of Contents
answered the request. answered the request.
<blockfor> is an [int] representing the number of replicas whose <blockfor> is an [int] representing the number of replicas whose
acknowledgement is required to achieve <cl>. acknowledgement is required to achieve <cl>.
<numfailures> is an [int] representing the number of nodes that <num_failures> is an [int] representing the number of nodes that
experience a failure while executing the request. experience a failure while executing the request.
<data_present> is a single byte. If its value is 0, it means <data_present> is a single byte. If its value is 0, it means
the replica that was asked for data had not the replica that was asked for data had not
@ -1146,7 +1146,7 @@ Table of Contents
<arg_types> [string list] one string for each argument type (as CQL type) of the failed function <arg_types> [string list] one string for each argument type (as CQL type) of the failed function
0x1500 Write_failure: A non-timeout exception during a write request. The rest 0x1500 Write_failure: A non-timeout exception during a write request. The rest
of the ERROR message body will be of the ERROR message body will be
<cl><received><blockfor><numfailures><write_type> <cl><received><blockfor><num_failures><write_type>
where: where:
<cl> is the [consistency] level of the query having triggered <cl> is the [consistency] level of the query having triggered
the exception. the exception.
@ -1154,7 +1154,7 @@ Table of Contents
answered the request. answered the request.
<blockfor> is an [int] representing the number of replicas whose <blockfor> is an [int] representing the number of replicas whose
acknowledgement is required to achieve <cl>. acknowledgement is required to achieve <cl>.
<numfailures> is an [int] representing the number of nodes that <num_failures> is an [int] representing the number of nodes that
experience a failure while executing the request. experience a failure while executing the request.
<writeType> is a [string] that describes the type of the write <writeType> is a [string] that describes the type of the write
that failed. The value of that string can be one that failed. The value of that string can be one
@ -1169,14 +1169,14 @@ Table of Contents
batch. No batch log write has been attempted. batch. No batch log write has been attempted.
- "COUNTER": the write was a counter write - "COUNTER": the write was a counter write
(batched or not). (batched or not).
- "BATCH_LOG": the failure occured during the - "BATCH_LOG": the failure occurred during the
write to the batch log when a (logged) batch write to the batch log when a (logged) batch
write was requested. write was requested.
- "CAS": the failure occured during the Compare And Set write/update. - "CAS": the failure occurred during the Compare And Set write/update.
- "VIEW": the failure occured when a write involves - "VIEW": the failure occurred when a write involves
VIEW update and failure to acqiure local view(MV) VIEW update and failure to acquire local view(MV)
lock for key within timeout lock for key within timeout
- "CDC": the failure occured when cdc_total_space is - "CDC": the failure occurred when cdc_total_space is
exceeded when doing a write to data tracked by cdc. exceeded when doing a write to data tracked by cdc.
0x2000 Syntax_error: The submitted query has a syntax error. 0x2000 Syntax_error: The submitted query has a syntax error.

96
doc/native_protocol_v5.spec
View File

@ -404,7 +404,7 @@ Table of Contents
The purpose is to send small negative values as small unsigned values, so that we save bytes on the wire. The purpose is to send small negative values as small unsigned values, so that we save bytes on the wire.
To encode a value n use "(n >> 31) ^ (n << 1)" for 32 bit values, and "(n >> 63) ^ (n << 1)" To encode a value n use "(n >> 31) ^ (n << 1)" for 32 bit values, and "(n >> 63) ^ (n << 1)"
for 64 bit values where "^" is the xor operation, "<<" is the left shift operation and ">>" is for 64 bit values where "^" is the xor operation, "<<" is the left shift operation and ">>" is
the arithemtic right shift operation (highest-order bit is replicated). the arithmetic right shift operation (highest-order bit is replicated).
Decode with "(n >> 1) ^ -(n & 1)". Decode with "(n >> 1) ^ -(n & 1)".
[option] A pair of <id><value> where <id> is a [short] representing [option] A pair of <id><value> where <id> is a [short] representing
@ -422,7 +422,7 @@ Table of Contents
[byte] representing the IP address. [byte] representing the IP address.
[consistency] A consistency level specification. This is a [short] [consistency] A consistency level specification. This is a [short]
representing a consistency level with the following representing a consistency level with the following
correspondance: correspondence:
0x0000 ANY 0x0000 ANY
0x0001 ONE 0x0001 ONE
0x0002 TWO 0x0002 TWO
@ -478,7 +478,7 @@ Table of Contents
This is optional; if not specified no compression will be used. This is optional; if not specified no compression will be used.
- "DRIVER_NAME": allows clients to supply a free-form label representing the driver - "DRIVER_NAME": allows clients to supply a free-form label representing the driver
implementation. This is displayed in the output of `nodetool clientstats` implementation. This is displayed in the output of `nodetool clientstats`
- "DRIVER_VERSION": allows clients to supply a free-form label represting the driver - "DRIVER_VERSION": allows clients to supply a free-form label representing the driver
version. This is displayed in the output of `nodetool clientstats` version. This is displayed in the output of `nodetool clientstats`
- "THROW_ON_OVERLOAD": flag to specify server behaviour where the incoming message - "THROW_ON_OVERLOAD": flag to specify server behaviour where the incoming message
rate is too high. An [string] value of "1" instructs the server to respond with rate is too high. An [string] value of "1" instructs the server to respond with
@ -548,8 +548,8 @@ Table of Contents
started (See Section 7 for more details). started (See Section 7 for more details).
0x0010: With serial consistency. If set, <serial_consistency> should be 0x0010: With serial consistency. If set, <serial_consistency> should be
present. <serial_consistency> is the [consistency] level for the present. <serial_consistency> is the [consistency] level for the
serial phase of conditional updates. That consitency can only be serial phase of conditional updates. Consistency can be
either SERIAL or LOCAL_SERIAL and if not present, it defaults to either SERIAL or LOCAL_SERIAL, if not present, it defaults to
SERIAL. This option will be ignored for anything else other than a SERIAL. This option will be ignored for anything else other than a
conditional update/insert. conditional update/insert.
0x0020: With default timestamp. If set, <timestamp> must be present. 0x0020: With default timestamp. If set, <timestamp> must be present.
@ -567,7 +567,7 @@ Table of Contents
and using this flag, while supported, is almost surely inefficient. and using this flag, while supported, is almost surely inefficient.
0x0080: With keyspace. If set, <keyspace> must be present. <keyspace> is a 0x0080: With keyspace. If set, <keyspace> must be present. <keyspace> is a
[string] indicating the keyspace that the query should be executed in. [string] indicating the keyspace that the query should be executed in.
It supercedes the keyspace that the connection is bound to, if any. It supersedes the keyspace that the connection is bound to, if any.
0x0100: With now in seconds. If set, <now_in_seconds> must be present. 0x0100: With now in seconds. If set, <now_in_seconds> must be present.
<now_in_seconds> is an [int] representing the current time (now) for <now_in_seconds> is an [int] representing the current time (now) for
the query. Affects TTL cell liveness in read queries and local deletion the query. Affects TTL cell liveness in read queries and local deletion
@ -593,7 +593,7 @@ Table of Contents
flags are, given their mask: flags are, given their mask:
0x01: With keyspace. If set, <keyspace> must be present. <keyspace> is a 0x01: With keyspace. If set, <keyspace> must be present. <keyspace> is a
[string] indicating the keyspace that the query should be executed in. [string] indicating the keyspace that the query should be executed in.
It supercedes the keyspace that the connection is bound to, if any. It supersedes the keyspace that the connection is bound to, if any.
The server will respond with a RESULT message with a `prepared` kind (0x0004, The server will respond with a RESULT message with a `prepared` kind (0x0004,
see Section 4.2.5). see Section 4.2.5).
@ -606,10 +606,10 @@ Table of Contents
where where
- <id> is the prepared query ID. It's the [short bytes] returned as a - <id> is the prepared query ID. It's the [short bytes] returned as a
response to a PREPARE message. response to a PREPARE message.
- <result_metadata_id> is the ID of the resultset metadata that was sent - <result_metadata_id> is the ID of the result set metadata that was sent
along with response to PREPARE message. If a RESULT/Rows message reports along with response to PREPARE message. If a RESULT/Rows message reports
changed resultset metadata with the Metadata_changed flag, the reported new changed result set metadata with the Metadata_changed flag, the reported new
resultset metadata must be used in subsequent executions. result set metadata must be used in subsequent executions.
- <query_parameters> has the exact same definition as in QUERY (see Section 4.1.4). - <query_parameters> has the exact same definition as in QUERY (see Section 4.1.4).
@ -634,8 +634,8 @@ Table of Contents
flags are, given their mask: flags are, given their mask:
0x0010: With serial consistency. If set, <serial_consistency> should be 0x0010: With serial consistency. If set, <serial_consistency> should be
present. <serial_consistency> is the [consistency] level for the present. <serial_consistency> is the [consistency] level for the
serial phase of conditional updates. That consistency can only be serial phase of conditional updates. Consistency can be
either SERIAL or LOCAL_SERIAL and if not present, it defaults to either SERIAL or LOCAL_SERIAL, if not present, it defaults to
SERIAL. This option will be ignored for anything else other than a SERIAL. This option will be ignored for anything else other than a
conditional update/insert. conditional update/insert.
0x0020: With default timestamp. If set, <timestamp> should be present. 0x0020: With default timestamp. If set, <timestamp> should be present.
@ -652,7 +652,7 @@ Table of Contents
more details]. more details].
0x0080: With keyspace. If set, <keyspace> must be present. <keyspace> is a 0x0080: With keyspace. If set, <keyspace> must be present. <keyspace> is a
[string] indicating the keyspace that the query should be executed in. [string] indicating the keyspace that the query should be executed in.
It supercedes the keyspace that the connection is bound to, if any. It supersedes the keyspace that the connection is bound to, if any.
0x0100: With now in seconds. If set, <now_in_seconds> must be present. 0x0100: With now in seconds. If set, <now_in_seconds> must be present.
<now_in_seconds> is an [int] representing the current time (now) for <now_in_seconds> is an [int] representing the current time (now) for
the query. Affects TTL cell liveness in read queries and local deletion the query. Affects TTL cell liveness in read queries and local deletion
@ -677,8 +677,8 @@ Table of Contents
- <consistency> is the [consistency] level for the operation. - <consistency> is the [consistency] level for the operation.
- <serial_consistency> is only present if the 0x10 flag is set. In that case, - <serial_consistency> is only present if the 0x10 flag is set. In that case,
<serial_consistency> is the [consistency] level for the serial phase of <serial_consistency> is the [consistency] level for the serial phase of
conditional updates. That consitency can only be either SERIAL or conditional updates. Consistency can be either SERIAL or
LOCAL_SERIAL and if not present will defaults to SERIAL. This option will LOCAL_SERIAL, if not present, it defaults to SERIAL. This option will
be ignored for anything else other than a conditional update/insert. be ignored for anything else other than a conditional update/insert.
The server will respond with a RESULT message. The server will respond with a RESULT message.
@ -703,7 +703,7 @@ Table of Contents
This section describes the content of the frame body for the different This section describes the content of the frame body for the different
responses. Please note that to make room for future evolution, clients should responses. Please note that to make room for future evolution, clients should
support extra informations (that they should simply discard) to the one support extra information (that they should simply discard) to the one
described in this document at the end of the frame body. described in this document at the end of the frame body.
4.2.1. ERROR 4.2.1. ERROR
@ -731,7 +731,7 @@ Table of Contents
The authentication is SASL based and thus consists of a number of server The authentication is SASL based and thus consists of a number of server
challenges (AUTH_CHALLENGE, Section 4.2.7) followed by client responses challenges (AUTH_CHALLENGE, Section 4.2.7) followed by client responses
(AUTH_RESPONSE, Section 4.1.2). The initial exchange is however boostrapped (AUTH_RESPONSE, Section 4.1.2). The initial exchange is however bootstrapped
by an initial client response. The details of that exchange (including how by an initial client response. The details of that exchange (including how
many challenge-response pairs are required) are specific to the authenticator many challenge-response pairs are required) are specific to the authenticator
in use. The exchange ends when the server sends an AUTH_SUCCESS message or in use. The exchange ends when the server sends an AUTH_SUCCESS message or
@ -809,12 +809,12 @@ Table of Contents
during the query (see QUERY and RESULT messages). during the query (see QUERY and RESULT messages).
0x0008 Metadata_changed: if set, the No_metadata flag has to be unset 0x0008 Metadata_changed: if set, the No_metadata flag has to be unset
and <new_metadata_id> has to be supplied. This flag is to be and <new_metadata_id> has to be supplied. This flag is to be
used to avoid a roundtrip in case of metadata changes for queries used to avoid a round trip in case of metadata changes for queries
that requested metadata to be skipped. that requested metadata to be skipped.
- <columns_count> is an [int] representing the number of columns selected - <columns_count> is an [int] representing the number of columns selected
by the query that produced this result. It defines the number of <col_spec_i> by the query that produced this result. It defines the number of <col_spec_i>
elements in and the number of elements for each row in <rows_content>. elements in and the number of elements for each row in <rows_content>.
- <new_metadata_id> is [short bytes] representing the new, changed resultset - <new_metadata_id> is [short bytes] representing the new, changed result set
metadata. The new metadata ID must also be used in subsequent executions of metadata. The new metadata ID must also be used in subsequent executions of
the corresponding prepared statement, if any. the corresponding prepared statement, if any.
- <global_table_spec> is present if the Global_tables_spec is set in - <global_table_spec> is present if the Global_tables_spec is set in
@ -822,8 +822,8 @@ Table of Contents
(unique) keyspace name and table name the columns belong to. (unique) keyspace name and table name the columns belong to.
- <col_spec_i> specifies the columns returned in the query. There are - <col_spec_i> specifies the columns returned in the query. There are
<column_count> such column specifications that are composed of: <column_count> such column specifications that are composed of:
(<ksname><tablename>)?<name><type> (<ks_name><table_name>)?<name><type>
The initial <ksname> and <tablename> are two [string] and are only present The initial <ks_name> and <table_name> are two [string] and are only present
if the Global_tables_spec flag is not set. The <column_name> is a if the Global_tables_spec flag is not set. The <column_name> is a
[string] and <type> is an [option] that corresponds to the description [string] and <type> is an [option] that corresponds to the description
(what this description is depends a bit on the context: in results to (what this description is depends a bit on the context: in results to
@ -901,7 +901,7 @@ Table of Contents
<id><result_metadata_id><metadata><result_metadata> <id><result_metadata_id><metadata><result_metadata>
where: where:
- <id> is [short bytes] representing the prepared query ID. - <id> is [short bytes] representing the prepared query ID.
- <result_metadata_id> is [short bytes] representing the resultset metadata ID. - <result_metadata_id> is [short bytes] representing the result set metadata ID.
- <metadata> is composed of: - <metadata> is composed of:
<flags><columns_count><pk_count>[<pk_index_1>...<pk_index_n>][<global_table_spec>?<col_spec_1>...<col_spec_n>] <flags><columns_count><pk_count>[<pk_index_1>...<pk_index_n>][<global_table_spec>?<col_spec_1>...<col_spec_n>]
where: where:
@ -937,8 +937,8 @@ Table of Contents
- <col_spec_i> specifies the bind markers in the prepared statement. - <col_spec_i> specifies the bind markers in the prepared statement.
There are <column_count> such column specifications, each with the There are <column_count> such column specifications, each with the
following format: following format:
(<ksname><tablename>)?<name><type> (<ks_name><table_name>)?<name><type>
The initial <ksname> and <tablename> are two [string] that are only The initial <ks_name> and <table_name> are two [string] that are only
present if the Global_tables_spec flag is not set. The <name> field present if the Global_tables_spec flag is not set. The <name> field
is a [string] that holds the name of the bind marker (if named), is a [string] that holds the name of the bind marker (if named),
or the name of the column, field, or expression that the bind marker or the name of the column, field, or expression that the bind marker
@ -961,7 +961,7 @@ Table of Contents
Note that the prepared query ID returned is global to the node on which the query Note that the prepared query ID returned is global to the node on which the query
has been prepared. It can be used on any connection to that node has been prepared. It can be used on any connection to that node
until the node is restarted (after which the query must be reprepared). until the node is restarted (after which the query must be re-prepared).
4.2.5.5. Schema_change 4.2.5.5. Schema_change
@ -978,7 +978,7 @@ Table of Contents
4.2.6. EVENT 4.2.6. EVENT
An event pushed by the server. A client will only receive events for the An event pushed by the server. A client will only receive events for the
types it has REGISTERed to. The body of an EVENT message will start with a types it has REGISTER-ed to. The body of an EVENT message will start with a
[string] representing the event type. The rest of the message depends on the [string] representing the event type. The rest of the message depends on the
event type. The valid event types are: event type. The valid event types are:
- "TOPOLOGY_CHANGE": events related to change in the cluster topology. - "TOPOLOGY_CHANGE": events related to change in the cluster topology.
@ -1209,7 +1209,7 @@ Table of Contents
5.25 vector 5.25 vector
For a vector of n dimensions of a fixed-length type, a sequence of those n elements. For a vector of n dimensions of a fixed-length type, a sequence of those n elements.
For a vector with variable-length elements, the size of the elements will preced For a vector with variable-length elements, the size of the elements will precede
each element. Each element is the [bytes] representing the serialized value. The each element. Each element is the [bytes] representing the serialized value. The
number of dimensions is not encoded, since it's part of the type definition. number of dimensions is not encoded, since it's part of the type definition.
@ -1318,13 +1318,13 @@ Table of Contents
- "BATCH_LOG": the timeout occurred during the - "BATCH_LOG": the timeout occurred during the
write to the batch log when a (logged) batch write to the batch log when a (logged) batch
write was requested. write was requested.
- "CAS": the timeout occured during the Compare And Set write/update. - "CAS": the timeout occurred during the Compare And Set write/update.
- "VIEW": the timeout occured when a write involves - "VIEW": the timeout occurred when a write involves
VIEW update and failure to acqiure local view(MV) VIEW update and failure to acquire local view(MV)
lock for key within timeout lock for key within timeout
- "CDC": the timeout occured when cdc_total_space is - "CDC": the timeout occurred when cdc_total_space is
exceeded when doing a write to data tracked by cdc. exceeded when doing a write to data tracked by cdc.
<contentions> is a [short] that describes the number of contentions occured during the CAS operation. <contentions> is a [short] that describes the number of contentions occurred during the CAS operation.
The field only presents when the <writeType> is "CAS". The field only presents when the <writeType> is "CAS".
0x1200 Read_timeout: Timeout exception during a read request. The rest 0x1200 Read_timeout: Timeout exception during a read request. The rest
of the ERROR message body will be of the ERROR message body will be
@ -1345,7 +1345,7 @@ Table of Contents
responded. Otherwise, the value is != 0. responded. Otherwise, the value is != 0.
0x1300 Read_failure: A non-timeout exception during a read request. The rest 0x1300 Read_failure: A non-timeout exception during a read request. The rest
of the ERROR message body will be of the ERROR message body will be
<cl><received><blockfor><reasonmap><data_present> <cl><received><blockfor><reason_map><data_present>
where: where:
<cl> is the [consistency] level of the query having triggered <cl> is the [consistency] level of the query having triggered
the exception. the exception.
@ -1353,12 +1353,12 @@ Table of Contents
answered the request. answered the request.
<blockfor> is an [int] representing the number of replicas whose <blockfor> is an [int] representing the number of replicas whose
acknowledgement is required to achieve <cl>. acknowledgement is required to achieve <cl>.
<reasonmap> is a map of endpoint to failure reason codes. This maps <reason_map> is a map of endpoint to failure reason codes. This maps
the endpoints of the replica nodes that failed when the endpoints of the replica nodes that failed when
executing the request to a code representing the reason executing the request to a code representing the reason
for the failure. The map is encoded starting with an [int] n for the failure. The map is encoded starting with an [int] n
followed by n pairs of <endpoint><failurecode> where followed by n pairs of <endpoint><failure_code> where
<endpoint> is an [inetaddr] and <failurecode> is a [short]. <endpoint> is an [inetaddr] and <failure_code> is a [short].
<data_present> is a single byte. If its value is 0, it means <data_present> is a single byte. If its value is 0, it means
the replica that was asked for data had not the replica that was asked for data had not
responded. Otherwise, the value is != 0. responded. Otherwise, the value is != 0.
@ -1371,7 +1371,7 @@ Table of Contents
<arg_types> [string list] one string for each argument type (as CQL type) of the failed function <arg_types> [string list] one string for each argument type (as CQL type) of the failed function
0x1500 Write_failure: A non-timeout exception during a write request. The rest 0x1500 Write_failure: A non-timeout exception during a write request. The rest
of the ERROR message body will be of the ERROR message body will be
<cl><received><blockfor><reasonmap><write_type> <cl><received><blockfor><reason_map><write_type>
where: where:
<cl> is the [consistency] level of the query having triggered <cl> is the [consistency] level of the query having triggered
the exception. the exception.
@ -1379,12 +1379,12 @@ Table of Contents
answered the request. answered the request.
<blockfor> is an [int] representing the number of replicas whose <blockfor> is an [int] representing the number of replicas whose
acknowledgement is required to achieve <cl>. acknowledgement is required to achieve <cl>.
<reasonmap> is a map of endpoint to failure reason codes. This maps <reason_map> is a map of endpoint to failure reason codes. This maps
the endpoints of the replica nodes that failed when the endpoints of the replica nodes that failed when
executing the request to a code representing the reason executing the request to a code representing the reason
for the failure. The map is encoded starting with an [int] n for the failure. The map is encoded starting with an [int] n
followed by n pairs of <endpoint><failurecode> where followed by n pairs of <endpoint><failure_code> where
<endpoint> is an [inetaddr] and <failurecode> is a [short]. <endpoint> is an [inetaddr] and <failure_code> is a [short].
<writeType> is a [string] that describes the type of the write <writeType> is a [string] that describes the type of the write
that failed. The value of that string can be one that failed. The value of that string can be one
of: of:
@ -1398,17 +1398,17 @@ Table of Contents
batch. No batch log write has been attempted. batch. No batch log write has been attempted.
- "COUNTER": the write was a counter write - "COUNTER": the write was a counter write
(batched or not). (batched or not).
- "BATCH_LOG": the failure occured during the - "BATCH_LOG": the failure occurred during the
write to the batch log when a (logged) batch write to the batch log when a (logged) batch
write was requested. write was requested.
- "CAS": the failure occured during the Compare And Set write/update. - "CAS": the failure occurred during the Compare And Set write/update.
- "VIEW": the failure occured when a write involves - "VIEW": the failure occurred when a write involves
VIEW update and failure to acqiure local view(MV) VIEW update and failure to acquire local view(MV)
lock for key within timeout lock for key within timeout
- "CDC": the failure occured when cdc_total_space is - "CDC": the failure occurred when cdc_total_space is
exceeded when doing a write to data tracked by cdc. exceeded when doing a write to data tracked by cdc.
0x1600 CDC_WRITE_FAILURE: // todo 0x1600 CDC_WRITE_FAILURE: // todo
0x1700 CAS_WRITE_UNKNOWN: An exception occured due to contended Compare And Set write/update. 0x1700 CAS_WRITE_UNKNOWN: An exception occurred due to contended Compare And Set write/update.
The CAS operation was only partially completed and the operation may or may not get completed by The CAS operation was only partially completed and the operation may or may not get completed by
the contending CAS write or SERIAL/LOCAL_SERIAL read. The rest of the ERROR message body will be the contending CAS write or SERIAL/LOCAL_SERIAL read. The rest of the ERROR message body will be
<cl><received><blockfor> <cl><received><blockfor>
@ -1444,8 +1444,8 @@ Table of Contents
* Added result set metadata id to Prepared responses (Section 4.2.5.4) * Added result set metadata id to Prepared responses (Section 4.2.5.4)
* Beta protocol flag for v5 native protocol is added (Section 2.2) * Beta protocol flag for v5 native protocol is added (Section 2.2)
* <numfailures> in Read_failure and Write_failure error message bodies (Section 9) * <num_failures> in Read_failure and Write_failure error message bodies (Section 9)
has been replaced with <reasonmap>. The <reasonmap> maps node IP addresses to has been replaced with <reason_map>. The <reason_map> maps node IP addresses to
a failure reason code which indicates why the request failed on that node. a failure reason code which indicates why the request failed on that node.
* Enlarged flag's bitmaps for QUERY, EXECUTE and BATCH messages from [byte] to [int] * Enlarged flag's bitmaps for QUERY, EXECUTE and BATCH messages from [byte] to [int]
(Sections 4.1.4, 4.1.6 and 4.1.7). (Sections 4.1.4, 4.1.6 and 4.1.7).