You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by sl...@apache.org on 2015/12/21 16:33:13 UTC
[1/3] cassandra git commit: Fix grammatical errors and imprecisions
in native protocol spec
Repository: cassandra
Updated Branches:
refs/heads/trunk 565799c28 -> 43f8f8bb3
Fix grammatical errors and imprecisions in native protocol spec
patch by stamhankar999; reviewed by slebresne for CASSANDRA-10850
Project: http://git-wip-us.apache.org/repos/asf/cassandra/repo
Commit: http://git-wip-us.apache.org/repos/asf/cassandra/commit/8565ca89
Tree: http://git-wip-us.apache.org/repos/asf/cassandra/tree/8565ca89
Diff: http://git-wip-us.apache.org/repos/asf/cassandra/diff/8565ca89
Branch: refs/heads/trunk
Commit: 8565ca89a93707740021c04c3c5bb49b504ac89d
Parents: df49cec
Author: Sandeep Tamhankar <sa...@datastax.com>
Authored: Mon Dec 21 16:30:51 2015 +0100
Committer: Sylvain Lebresne <sy...@datastax.com>
Committed: Mon Dec 21 16:31:36 2015 +0100
----------------------------------------------------------------------
doc/native_protocol_v4.spec | 312 ++++++++++++++++++++-------------------
1 file changed, 158 insertions(+), 154 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cassandra/blob/8565ca89/doc/native_protocol_v4.spec
----------------------------------------------------------------------
diff --git a/doc/native_protocol_v4.spec b/doc/native_protocol_v4.spec
index 7aca858..51cb875 100644
--- a/doc/native_protocol_v4.spec
+++ b/doc/native_protocol_v4.spec
@@ -65,20 +65,19 @@ Table of Contents
Each frame contains a fixed size header (9 bytes) followed by a variable size
body. The header is described in Section 2. The content of the body depends
on the header opcode value (the body can in particular be empty for some
- opcode values). The list of allowed opcode is defined Section 2.3 and the
- details of each corresponding message is described Section 4.
+ opcode values). The list of allowed opcodes is defined in Section 2.3 and the
+ details of each corresponding message are described Section 4.
- The protocol distinguishes 2 types of frames: requests and responses. Requests
- are those frame sent by the clients to the server, response are the ones sent
- by the server. Note however that the protocol supports server pushes (events)
- so responses does not necessarily come right after a client request.
+ The protocol distinguishes two types of frames: requests and responses. Requests
+ are those frames sent by the client to the server. Responses are those frames sent
+ by the server to the client. Note, however, that the protocol supports server pushes
+ (events) so a response does not necessarily come right after a client request.
- Note to client implementors: clients library should always assume that the
+ Note to client implementors: client libraries should always assume that the
body of a given frame may contain more data than what is described in this
- document. It will however always be safe to ignore the remaining of the frame
- body in such cases. The reason is that this may allow to sometimes extend the
- protocol with optional features without needing to change the protocol
- version.
+ document. It will however always be safe to ignore the remainder of the frame
+ body in such cases. The reason is that this may enable extending the protocol
+ with optional features without needing to change the protocol version.
@@ -86,59 +85,58 @@ Table of Contents
2.1. version
- The version is a single byte that indicate both the direction of the message
- (request or response) and the version of the protocol in use. The up-most bit
- of version is used to define the direction of the message: 0 indicates a
- request, 1 indicates a responses. This can be useful for protocol analyzers to
- distinguish the nature of the packet from the direction which it is moving.
- The rest of that byte is the protocol version (4 for the protocol defined in
- this document). In other words, for this version of the protocol, version will
- have one of:
+ The version is a single byte that indicates both the direction of the message
+ (request or response) and the version of the protocol in use. The most
+ significant bit of version is used to define the direction of the message:
+ 0 indicates a request, 1 indicates a response. This can be useful for protocol
+ analyzers to distinguish the nature of the packet from the direction in which
+ it is moving. The rest of that byte is the protocol version (4 for the protocol
+ defined in this document). In other words, for this version of the protocol,
+ version will be one of:
0x04 Request frame for this protocol version
0x84 Response frame for this protocol version
- Please note that the while every message ship with the version, only one version
+ Please note that while every message ships with the version, only one version
of messages is accepted on a given connection. In other words, the first message
exchanged (STARTUP) sets the version for the connection for the lifetime of this
connection.
- This document describe the version 3 of the protocol. For the changes made since
+ This document describes version 4 of the protocol. For the changes made since
version 3, see Section 10.
2.2. flags
Flags applying to this frame. The flags have the following meaning (described
- by the mask that allow to select them):
+ by the mask that allows selecting them):
0x01: Compression flag. If set, the frame body is compressed. The actual
compression to use should have been set up beforehand through the
Startup message (which thus cannot be compressed; Section 4.1.1).
- 0x02: Tracing flag. For a request frame, this indicate the client requires
- tracing of the request. Note that not all requests support tracing.
- Currently, only QUERY, PREPARE and EXECUTE queries support tracing.
- Other requests will simply ignore the tracing flag if set. If a
- request support tracing and the tracing flag was set, the response to
- this request will have the tracing flag set and contain tracing
+ 0x02: Tracing flag. For a request frame, this indicates the client requires
+ tracing of the request. Note that only QUERY, PREPARE and EXECUTE queries
+ support tracing. Other requests will simply ignore the tracing flag if
+ set. If a request supports tracing and the tracing flag is set, the response
+ to this request will have the tracing flag set and contain tracing
information.
If a response frame has the tracing flag set, its body contains
a tracing ID. The tracing ID is a [uuid] and is the first thing in
the frame body. The rest of the body will then be the usual body
corresponding to the response opcode.
0x04: Custom payload flag. For a request or response frame, this indicates
- that generic key-value custom payload for a custom QueryHandler
- implementation is present in the frame. Such custom payload is simply
+ that a generic key-value custom payload for a custom QueryHandler
+ implementation is present in the frame. Such a custom payload is simply
ignored by the default QueryHandler implementation.
Currently, only QUERY, PREPARE, EXECUTE and BATCH requests support
payload.
Type of custom payload is [bytes map] (see below).
- 0x08: Warning flag. The response contains warnings from the server which
- were generated by the server to go along with this response.
+ 0x08: Warning flag. The response contains warnings which were generated by the
+ server to go along with this response.
If a response frame has the warning flag set, its body will contain the
text of the warnings. The warnings are a [string list] and will be the
first value in the frame body if the tracing flag is not set, or directly
after the tracing ID if it is.
- The rest of the flags is currently unused and ignored.
+ The rest of flags is currently unused and ignored.
2.3. stream
@@ -149,24 +147,23 @@ Table of Contents
with the stream id X, it is guaranteed that the stream id of the response to
that message will be X.
- This allow to deal with the asynchronous nature of the protocol. If a client
+ This helps to enable the asynchronous nature of the protocol. If a client
sends multiple messages simultaneously (without waiting for responses), there
is no guarantee on the order of the responses. For instance, if the client
writes REQ_1, REQ_2, REQ_3 on the wire (in that order), the server might
- respond to REQ_3 (or REQ_2) first. Assigning different stream id to these 3
- requests allows the client to distinguish to which request an received answer
- respond to. As there can only be 32768 different simultaneous streams, it is up
+ respond to REQ_3 (or REQ_2) first. Assigning different stream ids to these 3
+ requests allows the client to distinguish to which request a received answer
+ responds to. As there can only be 32768 different simultaneous streams, it is up
to the client to reuse stream id.
Note that clients are free to use the protocol synchronously (i.e. wait for
the response to REQ_N before sending REQ_N+1). In that case, the stream id
can be safely set to 0. Clients should also feel free to use only a subset of
- the 32768 maximum possible stream ids if it is simpler for those
- implementation.
+ the 32768 maximum possible stream ids if it is simpler for its implementation.
2.4. opcode
- An integer byte that distinguish the actual message:
+ An integer byte that distinguishes the actual message:
0x00 ERROR
0x01 STARTUP
0x02 READY
@@ -266,14 +263,14 @@ Table of Contents
This must be the first message of the connection, except for OPTIONS that can
be sent before to find out the options supported by the server. Once the
connection has been initialized, a client should not send any more STARTUP
- message.
+ messages.
The body is a [string map] of options. Possible options are:
- "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.
- "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.
4.1.2. AUTH_RESPONSE
@@ -281,10 +278,10 @@ Table of Contents
Answers a server authentication challenge.
Authentication in the protocol is SASL based. The server sends authentication
- challenges (a bytes token) to which the client answer with this message. Those
+ challenges (a bytes token) to which the client answers with this message. Those
exchanges continue until the server accepts the authentication by sending a
- AUTH_SUCCESS message after a client AUTH_RESPONSE. It is however that client that
- initiate the exchange by sending an initial AUTH_RESPONSE in response to a
+ AUTH_SUCCESS message after a client AUTH_RESPONSE. Note that the exchange
+ begins with the client sending an initial AUTH_RESPONSE in response to a
server AUTHENTICATE request.
The body of this message is a single [bytes] token. The details of what this
@@ -297,7 +294,7 @@ Table of Contents
4.1.3. OPTIONS
- Asks the server to return what STARTUP options are supported. The body of an
+ Asks the server to return which STARTUP options are supported. The body of an
OPTIONS message should be empty and the server will respond with a SUPPORTED
message.
@@ -314,34 +311,33 @@ Table of Contents
- <flags> is a [byte] whose bits define the options for this query and
in particular influence what the remainder of the message contains.
A flag is set if the bit corresponding to its `mask` is set. Supported
- flags are, given there mask:
- 0x01: Values. In that case, a [short] <n> followed by <n> [value]
- values are provided. Those value are used for bound variables in
+ flags are, given their mask:
+ 0x01: Values. If set, a [short] <n> followed by <n> [value]
+ values are provided. Those values are used for bound variables in
the query. Optionally, if the 0x40 flag is present, each value
will be preceded by a [string] name, representing the name of
- the marker the value must be binded to. This is optional, and
- if not present, values will be binded by position.
- 0x02: Skip_metadata. If present, the Result Set returned as a response
- to that query (if any) will have the NO_METADATA flag (see
+ the marker the value must be bound to.
+ 0x02: Skip_metadata. If set, the Result Set returned as a response
+ to the query (if any) will have the NO_METADATA flag (see
Section 4.2.5.2).
- 0x04: Page_size. In that case, <result_page_size> is an [int]
+ 0x04: Page_size. If set, <result_page_size> is an [int]
controlling the desired page size of the result (in CQL3 rows).
See the section on paging (Section 8) for more details.
- 0x08: With_paging_state. If present, <paging_state> should be present.
+ 0x08: With_paging_state. If set, <paging_state> should be present.
<paging_state> is a [bytes] value that should have been returned
- in a result set (Section 4.2.5.2). If provided, the query will be
- executed but starting from a given paging state. This also to
- continue paging on a different node from the one it has been
+ in a result set (Section 4.2.5.2). The query will be
+ executed but starting from a given paging state. This is also to
+ continue paging on a different node than the one where it
started (See Section 8 for more details).
- 0x10: With serial consistency. If present, <serial_consistency> should be
+ 0x10: With serial consistency. If set, <serial_consistency> should be
present. <serial_consistency> is the [consistency] level for the
serial phase of conditional updates. That consitency can only be
either SERIAL or LOCAL_SERIAL and 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 other than a
conditional update/insert.
- 0x20: With default timestamp. If present, <timestamp> should be present.
+ 0x20: With default timestamp. If set, <timestamp> should be present.
<timestamp> is a [long] representing the default timestamp for the query
- in microseconds (negative values are forbidden). If provided, this will
+ in microseconds (negative values are forbidden). This will
replace the server side assigned timestamp as default timestamp.
Note that a timestamp in the query itself will still override
this timestamp. This is entirely optional.
@@ -375,7 +371,7 @@ Table of Contents
<id><query_parameters>
where <id> is the prepared query ID. It's the [short bytes] returned as a
response to a PREPARE message. As for <query_parameters>, it has the exact
- same definition than in QUERY (see Section 4.1.4).
+ same definition as in QUERY (see Section 4.1.4).
The response from the server will be a RESULT message.
@@ -394,20 +390,20 @@ Table of Contents
- If <type> == 2, the batch will be a "counter" batch (and non-counter
statements will be rejected).
- <flags> is a [byte] whose bits define the options for this query and
- in particular influence the remainder of the message contains. It is similar
+ in particular influence what the remainder of the message contains. It is similar
to the <flags> from QUERY and EXECUTE methods, except that the 4 rightmost
- bits must always be 0 as their corresponding option do not make sense for
+ bits must always be 0 as their corresponding options do not make sense for
Batch. A flag is set if the bit corresponding to its `mask` is set. Supported
- flags are, given there mask:
- 0x10: With serial consistency. If present, <serial_consistency> should be
+ flags are, given their mask:
+ 0x10: With serial consistency. If set, <serial_consistency> should be
present. <serial_consistency> is the [consistency] level for the
- serial phase of conditional updates. That consitency can only be
+ serial phase of conditional updates. That consistency can only be
either SERIAL or LOCAL_SERIAL and 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 other than a
conditional update/insert.
- 0x20: With default timestamp. If present, <timestamp> should be present.
+ 0x20: With default timestamp. If set, <timestamp> should be present.
<timestamp> is a [long] representing the default timestamp for the query
- in microseconds. If provided, this will replace the server side assigned
+ in microseconds. This will replace the server side assigned
timestamp as default timestamp. Note that a timestamp in the query itself
will still override this timestamp. This is entirely optional.
0x40: With names for values. If set, then all values for all <query_i> must be
@@ -438,15 +434,15 @@ Table of Contents
<serial_consistency> is the [consistency] level for the serial phase of
conditional updates. That consitency can only be either SERIAL or
LOCAL_SERIAL and if not present will defaults to SERIAL. This option will
- be ignored for anything else that a conditional update/insert.
+ be ignored for anything else other than a conditional update/insert.
The server will respond with a RESULT message.
4.1.8. REGISTER
- Register this connection to receive some type of events. The body of the
- message is a [string list] representing the event types to register to. See
+ Register this connection to receive some types of events. The body of the
+ message is a [string list] representing the event types to register for. See
section 4.2.6 for the list of valid event types.
The response to a REGISTER message will be a READY message.
@@ -477,21 +473,22 @@ Table of Contents
Indicates that the server is ready to process queries. This message will be
sent by the server either after a STARTUP message if no authentication is
- required, or after a successful CREDENTIALS message.
+ required (if authentication is required, the server indicates readiness by
+ sending a AUTH_RESPONSE message).
The body of a READY message is empty.
4.2.3. AUTHENTICATE
- Indicates that the server require authentication, and which authentication
+ Indicates that the server requires authentication, and which authentication
mechanism to use.
- The authentication is SASL based and thus consists on 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
- (AUTH_RESPONSE, Section 4.1.2). The Initial exchange is however boostrapped
+ (AUTH_RESPONSE, Section 4.1.2). The initial exchange is however boostrapped
by an initial client response. The details of that exchange (including how
- much challenge-response pair 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
an ERROR message.
@@ -535,52 +532,52 @@ Table of Contents
4.2.5.2. Rows
- Indicates a set of rows. The rest of body of a Rows result is:
+ Indicates a set of rows. The rest of the body of a Rows result is:
<metadata><rows_count><rows_content>
where:
- <metadata> is composed of:
<flags><columns_count>[<paging_state>][<global_table_spec>?<col_spec_1>...<col_spec_n>]
where:
- <flags> is an [int]. The bits of <flags> provides information on the
- formatting of the remaining informations. A flag is set if the bit
- corresponding to its `mask` is set. Supported flags are, given there
+ formatting of the remaining information. A flag is set if the bit
+ corresponding to its `mask` is set. Supported flags are, given their
mask:
0x0001 Global_tables_spec: if set, only one table spec (keyspace
and table name) is provided as <global_table_spec>. If not
set, <global_table_spec> is not present.
0x0002 Has_more_pages: indicates whether this is not the last
- page of results and more should be retrieve. If set, the
+ page of results and more should be retrieved. If set, the
<paging_state> will be present. The <paging_state> is a
[bytes] value that should be used in QUERY/EXECUTE to
- continue paging and retrieve the remained of the result for
+ continue paging and retrieve the remainder of the result for
this query (See Section 8 for more details).
0x0004 No_metadata: if set, the <metadata> is only composed of
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>).
This will only ever be the case if this was requested
during the query (see QUERY and RESULT messages).
- <columns_count> is an [int] representing the number of columns selected
- by the query this result is of. It defines the number of <col_spec_i>
- elements in and the number of element for each row in <rows_content>.
+ 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>.
- <global_table_spec> is present if the Global_tables_spec is set in
- <flags>. If present, it is composed of two [string] representing the
- (unique) keyspace name and table name the columns return are of.
- - <col_spec_i> specifies the columns returned in the query. There is
+ <flags>. It is composed of two [string] representing the
+ (unique) keyspace name and table name the columns belong to.
+ - <col_spec_i> specifies the columns returned in the query. There are
<column_count> such column specifications that are composed of:
(<ksname><tablename>)?<name><type>
- The initial <ksname> and <tablename> are two [string] are only present
+ The initial <ksname> and <tablename> are two [string] and are only present
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 corresponds to the description
(what this description is depends a bit on the context: in results to
selects, this will be either the user chosen alias or the selection used
(often a colum name, but it can be a function call too). In results to
- a PREPARE, this will be either the name of the bind variable corresponding
+ a PREPARE, this will be either the name of the corresponding bind variable
or the column name for the variable if it is "anonymous") and type of
the corresponding result. The option for <type> is either a native
type (see below), in which case the option has no value, or a
'custom' type, in which case the value is a [string] representing
- the full qualified class name of the type represented. Valid option
+ the fully qualified class name of the type represented. Valid option
ids are:
0x0000 Custom: the value is a [string], see above.
0x0001 Ascii
@@ -613,15 +610,15 @@ Table of Contents
- <ks> is a [string] representing the keyspace name this
UDT is part of.
- <udt_name> is a [string] representing the UDT name.
- - <n> is a [short] reprensenting the number of fields of
- the UDT, and thus the number of <name_i><type_i> pair
+ - <n> is a [short] representing the number of fields of
+ the UDT, and thus the number of <name_i><type_i> pairs
following
- <name_i> is a [string] representing the name of the
i_th field of the UDT.
- <type_i> is an [option] representing the type of the
i_th field of the UDT.
0x0031 Tuple: the value is <n><type_1>...<type_n> where <n> is a [short]
- representing the number of value in the type, and <type_i>
+ representing the number of values in the type, and <type_i>
are [option] representing the type of the i_th component
of the tuple
@@ -650,7 +647,7 @@ Table of Contents
<flags><columns_count><pk_count>[<pk_index_1>...<pk_index_n>][<global_table_spec>?<col_spec_1>...<col_spec_n>]
where:
- <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 masks and their flags
are:
0x0001 Global_tables_spec: if set, only one table spec (keyspace
@@ -696,15 +693,15 @@ Table of Contents
result set that will be returned when this prepared statement is executed.
Note that <result_metadata> may be empty (have the No_metadata flag and
0 columns, See section 4.2.5.2) and will be for any query that is not a
- Select. In fact, there is never a guarantee that this will non-empty, so
+ Select. In fact, there is never a guarantee that this will be non-empty, so
implementations should protect themselves accordingly. This result metadata
is an optimization that allows implementations to later execute the
prepared statement without requesting the metadata (see the Skip_metadata
flag in EXECUTE). Clients can safely discard this metadata if they do not
want to take advantage of that optimization.
- 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
+ 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
until the node is restarted (after which the query must be reprepared).
4.2.5.5. Schema_change
@@ -713,16 +710,16 @@ Table of Contents
keyspace/table/index). The body (after the kind [int]) is the same
as the body for a "SCHEMA_CHANGE" event, so 3 strings:
<change_type><target><options>
- Please refer to the section 4.2.6 below for the meaning of those fields.
+ Please refer to section 4.2.6 below for the meaning of those fields.
- Note that queries to create and drop an index are considered as change
- updating the table the index is on.
+ Note that a query to create or drop an index is considered to be a change
+ to the table the index is on.
4.2.6. EVENT
- And event pushed by the server. A client will only receive events for the
- type it has REGISTER to. The body of an EVENT message will start by a
+ 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
[string] representing the event type. The rest of the message depends on the
event type. The valid event types are:
- "TOPOLOGY_CHANGE": events related to change in the cluster topology.
@@ -763,7 +760,7 @@ Table of Contents
Please note that "NEW_NODE" and "UP" events are sent based on internal Gossip
communication and as such may be sent a short delay before the binary
protocol server on the newly up node is fully started. Clients are thus
- advise to wait a short time before trying to connect to the node (1 seconds
+ advised to wait a short time before trying to connect to the node (1 second
should be enough), otherwise they may experience a connection refusal at
first.
@@ -776,12 +773,12 @@ Table of Contents
token contains (and when it can be null/empty, if ever) depends on the actual
authenticator used.
- Clients are expected to answer the server challenge by an AUTH_RESPONSE
+ Clients are expected to answer the server challenge with an AUTH_RESPONSE
message.
4.2.8. AUTH_SUCCESS
- Indicate the success of the authentication phase. See Section 4.2.3 for more
+ Indicates the success of the authentication phase. See Section 4.2.3 for more
details.
The body of this message is a single [bytes] token holding final information
@@ -798,19 +795,19 @@ Table of Contents
Before being used, client and server must agree on a compression algorithm to
use, which is done in the STARTUP message. As a consequence, a STARTUP message
must never be compressed. However, once the STARTUP frame has been received
- by the server can be compressed (including the response to the STARTUP
- request). Frame do not have to be compressed however, even if compression has
- been agreed upon (a server may only compress frame above a certain size at its
+ by the server, messages can be compressed (including the response to the STARTUP
+ request). Frames do not have to be compressed, however, even if compression has
+ been agreed upon (a server may only compress frames above a certain size at its
discretion). A frame body should be compressed if and only if the compressed
flag (see Section 2.2) is set.
- As of this version 2 of the protocol, the following compressions are available:
- - lz4 (https://code.google.com/p/lz4/). In that, note that the 4 first bytes
+ As of version 2 of the protocol, the following compressions are available:
+ - lz4 (https://code.google.com/p/lz4/). In that, note that the first four bytes
of the body will be the uncompressed length (followed by the compressed
bytes).
- 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
- avaivable on some installation.
+ avaivable on some installations.
6. Data Type Serialization Formats
@@ -868,11 +865,11 @@ Table of Contents
6.7 double
- An eight-byte floating point number in the IEEE 754 binary64 format.
+ An 8 byte floating point number in the IEEE 754 binary64 format.
6.8 float
- An four-byte floating point number in the IEEE 754 binary32 format.
+ A 4 byte floating point number in the IEEE 754 binary32 format.
6.9 inet
@@ -880,7 +877,7 @@ Table of Contents
6.10 int
- A four-byte two's complement integer.
+ A 4 byte two's complement integer.
6.11 list
@@ -900,7 +897,7 @@ Table of Contents
6.14 smallint
- A two-byte two's complement integer.
+ A 2 byte two's complement integer.
6.15 text
@@ -908,12 +905,12 @@ Table of Contents
6.16 time
- An eight-byte two's complement long representing nanoseconds since midnight.
+ An 8 byte two's complement long representing nanoseconds since midnight.
Valid values are in the range 0 to 86399999999999
6.17 timestamp
- An eight-byte two's complement integer representing a millisecond-precision
+ An 8 byte two's complement integer representing a millisecond-precision
offset from the unix epoch (00:00:00, January 1st, 1970). Negative values
represent a negative offset from the epoch.
@@ -923,7 +920,7 @@ Table of Contents
6.19 tinyint
- A one-byte two's complement integer.
+ A 1 byte two's complement integer.
6.20 tuple
@@ -932,8 +929,6 @@ Table of Contents
Null values may be represented by using length -1 for the [bytes]
representation of an element.
- Within a tuple, all data types should use the v3 protocol serialization format.
-
6.21 uuid
A 16 byte sequence representing any valid UUID as defined by RFC 4122.
@@ -964,6 +959,7 @@ Table of Contents
value. Implementors should pad positive values that have a MSB >= 0x80
with a leading 0x00 byte.
+
7. User Defined Types
This section describes the serialization format for User defined types (UDT),
@@ -974,9 +970,6 @@ Table of Contents
for each field of the type it represents, but it is allowed to have less values than
the type has fields.
- Within a user-defined type value, all data types should use the v3 protocol
- serialization format.
-
8. Result paging
@@ -986,12 +979,12 @@ Table of Contents
If a positive value is provided for <result_page_size>, the result set of the
RESULT message returned for the query will contain at most the
- <result_page_size> first rows of the query result. If that first page of result
+ <result_page_size> first rows of the query result. If that first page of results
contains the full result set for the query, the RESULT message (of kind `Rows`)
will have the Has_more_pages flag *not* set. However, if some results are not
part of the first response, the Has_more_pages flag will be set and the result
will contain a <paging_state> value. In that case, the <paging_state> value
- should be used in a QUERY or EXECUTE message (that has the *same* query than
+ should be used in a QUERY or EXECUTE message (that has the *same* query as
the original one or the behavior is undefined) to retrieve the next page of
results.
@@ -1004,34 +997,40 @@ Table of Contents
to performance to pick a value too low. A value below 100 is probably too
low for most use cases.
- Clients should not rely on the actual size of the result set returned to
- decide if there is more result to fetch or not. Instead, they should always
- check the Has_more_pages flag (unless they did not enabled paging for the query
+ decide if there are more results to fetch or not. Instead, they should always
+ check the Has_more_pages flag (unless they did not enable paging for the query
obviously). Clients should also not assert that no result will have more than
- <result_page_size> results. While the current implementation always respect
- the exact value of <result_page_size>, we reserve ourselves the right to return
+ <result_page_size> results. While the current implementation always respects
+ the exact value of <result_page_size>, we reserve the right to return
slightly smaller or bigger pages in the future for performance reasons.
+ - The <paging_state> is specific to a protocol version and drivers should not
+ send a <paging_state> returned by a node using protocol v3 to query a node
+ using protocol v4 for instance.
9. Error codes
- The supported error codes are described below:
+ Let us recall that an ERROR message is composed of <code><message>[...]
+ (see 4.2.1 for details). The supported error codes, as well as any additional
+ information the message may contain after the <message> are described below:
0x0000 Server error: something unexpected happened. This indicates a
server-side bug.
0x000A Protocol error: some client message triggered a protocol
violation (for instance a QUERY message is sent before a STARTUP
one has been sent)
- 0x0100 Bad credentials: CREDENTIALS request failed because Cassandra
- did not accept the provided credentials.
-
+ 0x0100 Authentication error: authentication was required and failed. The
+ possible reason for failing depends on the authenticator in use,
+ which may or may not include more detail in the accompanying
+ error message.
0x1000 Unavailable exception. The rest of the ERROR message body will be
<cl><required><alive>
where:
- <cl> is the [consistency] level of the query having triggered
+ <cl> is the [consistency] level of the query that triggered
the exception.
- <required> is an [int] representing the number of node that
+ <required> is an [int] representing the number of nodes that
should be alive to respect <cl>
- <alive> is an [int] representing the number of replica that
- were known to be alive when the request has been
+ <alive> is an [int] representing the number of replicas that
+ were known to be alive when the request had been
processed (since an unavailable exception has been
triggered, there will be <alive> < <required>)
0x1001 Overloaded: the request cannot be processed because the
@@ -1050,7 +1049,7 @@ Table of Contents
<blockfor> is an [int] representing the number of replicas whose
acknowledgement is required to achieve <cl>.
<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:
- "SIMPLE": the write was a non-batched
non-counter write.
@@ -1062,7 +1061,7 @@ Table of Contents
batch. No batch log write has been attempted.
- "COUNTER": the write was a counter write
(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 was requested.
0x1200 Read_timeout: Timeout exception during a read request. The rest
@@ -1076,10 +1075,9 @@ Table of Contents
<blockfor> is an [int] representing the number of replicas whose
response is required to achieve <cl>. Please note that
it is possible to have <received> >= <blockfor> if
- <data_present> is false. And also in the (unlikely)
- case were <cl> is achieved but the coordinator node
- timeout while waiting for read-repair
- acknowledgement.
+ <data_present> is false. Also in the (unlikely)
+ case where <cl> is achieved but the coordinator node
+ times out while waiting for read-repair acknowledgement.
<data_present> is a single byte. If its value is 0, it means
the replica that was asked for data has not
responded. Otherwise, the value is != 0.
@@ -1117,7 +1115,7 @@ Table of Contents
acknowledgement is required to achieve <cl>.
<numfailures> is an [int] representing the number of nodes that
experience a failure while executing the request.
- <writeType> is a [string] that describe 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
of:
- "SIMPLE": the write was a non-batched
@@ -1150,17 +1148,23 @@ Table of Contents
keyspace, <table> will be present but will be the empty
string.
0x2500 Unprepared: Can be thrown while a prepared statement tries to be
- executed if the provide prepared statement ID is not known by
+ executed if the provided prepared statement ID is not known by
this host. The rest of the ERROR message body will be [short
bytes] representing the unknown ID.
10. Changes from v3
- * The format of "SCHEMA_CHANGE" events (Section 4.2.6) (and implicitly "Schema_change" results (Section 4.2.5.5))
- has been modified, and now includes changes related to user defined functions and user defined aggregates.
+ * The format of "SCHEMA_CHANGE" events (Section 4.2.6) (and implicitly
+ "Schema_change" results (Section 4.2.5.5)) has been modified, and now includes
+ changes related to user defined functions and user defined aggregates.
* Read_failure error code was added.
* Function_failure error code was added.
- * Add custom payload to frames for custom QueryHandler implementations (ignored by Cassandra's standard QueryHandler)
- * Add warnings to frames for responses for which the server generated a warning during processing, which the client needs to address.
+ * Add custom payload to frames for custom QueryHandler implementations (ignored by
+ Cassandra's standard QueryHandler)
+ * Add warnings to frames for responses for which the server generated a warning
+ during processing, which the client needs to address.
* Add the date and time data types
* Add the tinyint and smallint data types
+ * The <paging_state> returned in the v4 protocol is not compatible with the v3
+ protocol. In other words, a <paging_state> returned by a node using protocol v4
+ should not be used to query a node using protocol v3 (and vice-versa).
[2/3] cassandra git commit: Merge branch 'cassandra-2.2' into
cassandra-3.0
Posted by sl...@apache.org.
Merge branch 'cassandra-2.2' into cassandra-3.0
Project: http://git-wip-us.apache.org/repos/asf/cassandra/repo
Commit: http://git-wip-us.apache.org/repos/asf/cassandra/commit/adc9a241
Tree: http://git-wip-us.apache.org/repos/asf/cassandra/tree/adc9a241
Diff: http://git-wip-us.apache.org/repos/asf/cassandra/diff/adc9a241
Branch: refs/heads/trunk
Commit: adc9a241e396e91ce7d6843aca27eedf6f87944d
Parents: 67fd42f 8565ca8
Author: Sylvain Lebresne <sy...@datastax.com>
Authored: Mon Dec 21 16:32:52 2015 +0100
Committer: Sylvain Lebresne <sy...@datastax.com>
Committed: Mon Dec 21 16:32:52 2015 +0100
----------------------------------------------------------------------
doc/native_protocol_v4.spec | 311 +++++++++++++++++++--------------------
1 file changed, 155 insertions(+), 156 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cassandra/blob/adc9a241/doc/native_protocol_v4.spec
----------------------------------------------------------------------
diff --cc doc/native_protocol_v4.spec
index 7f54970,51cb875..7fcf1d8
--- a/doc/native_protocol_v4.spec
+++ b/doc/native_protocol_v4.spec
@@@ -1004,15 -997,15 +997,15 @@@ Table of Content
to performance to pick a value too low. A value below 100 is probably too
low for most use cases.
- Clients should not rely on the actual size of the result set returned to
- decide if there is more result to fetch or not. Instead, they should always
- check the Has_more_pages flag (unless they did not enabled paging for the query
+ decide if there are more results to fetch or not. Instead, they should always
+ check the Has_more_pages flag (unless they did not enable paging for the query
obviously). Clients should also not assert that no result will have more than
- <result_page_size> results. While the current implementation always respect
- the exact value of <result_page_size>, we reserve ourselves the right to return
+ <result_page_size> results. While the current implementation always respects
+ the exact value of <result_page_size>, we reserve the right to return
slightly smaller or bigger pages in the future for performance reasons.
- The <paging_state> is specific to a protocol version and drivers should not
- send a <paging_state> returned by a node using protocol v3 to query a node
- using protocol v4 for instance.
+ send a <paging_state> returned by a node using the protocol v3 to query a node
+ using the protocol v4 for instance.
9. Error codes
[3/3] cassandra git commit: Merge branch 'cassandra-3.0' into trunk
Posted by sl...@apache.org.
Merge branch 'cassandra-3.0' into trunk
Project: http://git-wip-us.apache.org/repos/asf/cassandra/repo
Commit: http://git-wip-us.apache.org/repos/asf/cassandra/commit/43f8f8bb
Tree: http://git-wip-us.apache.org/repos/asf/cassandra/tree/43f8f8bb
Diff: http://git-wip-us.apache.org/repos/asf/cassandra/diff/43f8f8bb
Branch: refs/heads/trunk
Commit: 43f8f8bb3b151eaa3f2f11cc4b124780b9dc4d0f
Parents: 565799c adc9a24
Author: Sylvain Lebresne <sy...@datastax.com>
Authored: Mon Dec 21 16:33:06 2015 +0100
Committer: Sylvain Lebresne <sy...@datastax.com>
Committed: Mon Dec 21 16:33:06 2015 +0100
----------------------------------------------------------------------
doc/native_protocol_v4.spec | 311 +++++++++++++++++++--------------------
1 file changed, 155 insertions(+), 156 deletions(-)
----------------------------------------------------------------------