Keys used in requests and responses
This section describes iproto
keys contained in requests and responses.
The keys are Tarantool constants that are either defined or mentioned in the
iproto_constants.h file.
While the keys themselves are unsigned 8-bit integers, their values can have different types.
Name | Code and value type |
Description |
---|---|---|
IPROTO_VERSION | 0x54 MP_UINT |
Binary protocol version supported by the client |
IPROTO_FEATURES | 0x55 MP_ARRAY |
Supported binary protocol features |
IPROTO_SYNC | 0x01 MP_UINT |
Unique request identifier |
IPROTO_SCHEMA_VERSION | 0x05 MP_UINT |
Version of the database schema |
IPROTO_TIMESTAMP | 0x04 MP_DOUBLE |
Time in seconds since the Unix epoch |
IPROTO_REQUEST_TYPE | 0x00 MP_UINT |
Request type or response type |
IPROTO_ERROR | 0x52 MP_ERROR |
Error response |
IPROTO_ERROR_24 | 0x31 MP_STR |
Error as a string |
IPROTO_DATA | 0x30 MP_OBJECT |
Data passed in the transaction. Can be empty. Used in all requests and responses |
IPROTO_SPACE_ID | 0x10 MP_UINT |
Space identifier |
IPROTO_INDEX_ID | 0x11 MP_UINT |
Index identifier |
IPROTO_TUPLE | 0x21 MP_ARRAY |
Tuple, arguments, operations, or authentication pair. See details |
IPROTO_KEY | 0x20 MP_ARRAY |
Array of index keys in the request. See space_object:select() |
IPROTO_LIMIT | 0x12 MP_UINT |
Maximum number of tuples in the space |
IPROTO_OFFSET | 0x13 MP_UINT |
Number of tuples to skip in the select |
IPROTO_ITERATOR | 0x14 MP_UINT |
Iterator type |
IPROTO_INDEX_BASE | 0x15 MP_UINT |
Indicates whether the first field number is 1 or 0 |
IPROTO_FUNCTION_NAME | 0x22 MP_STR |
Name of the called function. Used in IPROTO_CALL |
IPROTO_USER_NAME | 0x23 MP_STR |
User name. Used in IPROTO_AUTH |
IPROTO_OPS | 0x28 MP_ARRAY |
Array of operations. Used in IPROTO_UPSERT |
IPROTO_EXPR | 0x27 MP_STR |
Command argument. Used in IPROTO_EVAL |
IPROTO_AUTH_TYPE | 0x5b MP_STR |
A protocol used to generate user authentication data |
IPROTO_AFTER_POSITION | 0x2e MP_STR |
The position of a tuple after which space_object:select() starts the search |
IPROTO_AFTER_TUPLE | 0x2f MP_ARRAY |
A tuple after which space_object:select() starts the search |
IPROTO_FETCH_POSITION | 0x1f MP_BOOL |
If true, space_object:select() returns the position of the last selected tuple |
IPROTO_POSITION | 0x35 MP_STR |
If IPROTO_FETCH_POSITION is true, returns a base64-encoded string representing
the position of the last selected tuple |
Name | Code and value type |
Description |
---|---|---|
IPROTO_STREAM_ID | 0x0a MP_UINT |
Unique stream identifier |
IPROTO_TIMEOUT | 0x56 MP_DOUBLE |
Timeout in seconds, after which the transactions are rolled back |
IPROTO_TXN_ISOLATION | 0x59 MP_UINT |
Transaction isolation level |
Name | Code and value type |
Description |
---|---|---|
IPROTO_REPLICA_ID | 0x02 MP_INT |
Replica ID |
IPROTO_INSTANCE_UUID | 0x24 MP_STR |
Instance UUID |
IPROTO_VCLOCK | 0x26 MP_MAP |
The instance’s vclock |
IPROTO_VCLOCK_SYNC | 0x5a MP_UINT |
ID of the vclock synchronization request. Since 2.11 |
IPROTO_REPLICASET_UUID | 0x25 MP_STR |
Before Tarantool version 2.11, IPROTO_REPLICASET_UUID was called IPROTO_CLUSTER_UUID. |
IPROTO_LSN | 0x03 MP_UINT |
Log sequence number of the transaction |
IPROTO_TSN | 0x08 MP_UINT |
Transaction sequence number |
IPROTO_BALLOT_IS_RO_CFG | 0x01 MP_BOOL |
True if the instance is configured as read_only. Since 2.6.1 |
IPROTO_BALLOT_VCLOCK | 0x02 MP_MAP |
Current vclock of the instance |
IPROTO_BALLOT_GC_VCLOCK | 0x03 MP_MAP |
Vclock of the instance’s oldest WAL entry |
IPROTO_BALLOT_IS_RO | 0x04 MP_BOOL |
True if the instance is not writable: configured as read_only, has orphan status, or is a Raft follower. Since 2.6.1 |
IPROTO_BALLOT_IS_ANON | 0x05 MP_BOOL |
True if the replica is anonymous. Corresponds to replication.anon. Since 2.7.1 |
IPROTO_BALLOT_IS_BOOTED | 0x06 MP_BOOL |
True if the instance has finished its bootstrap or recovery process. Since 2.7.3, 2.8.2, 2.10.0 |
IPROTO_BALLOT_CAN_LEAD | 0x07 MP_BOOL |
True if box.cfg.election_mode is candidate or manual .
Since v. 2.7.3 and 2.8.2 |
IPROTO_BALLOT_BOOTSTRAP_LEADER_UUID | 0x08 MP_STR |
UUID of the bootstrap leader. The UUID is encoded as a 36-byte string. Since v. 2.11 |
IPROTO_BALLOT_REGISTERED_REPLICA_UUIDS | 0x09 MP_ARRAY |
An array of MP_STR elements that contains the UUIDs of members registered in the replica set. Each UUID is encoded as a 36-byte string. Since v. 2.11 |
IPROTO_FLAGS | 0x09 MP_UINT |
Auxiliary data to indicate the last transaction message state. Included in the header of any DML request that is recorded in the WAL. |
IPROTO_SERVER_VERSION | 0x06 MP_UINT |
Tarantool version of the subscribing node, in a compact representation |
IPROTO_REPLICA_ANON | 0x50 MP_BOOL |
Optional key used in SUBSCRIBE request. True if the subscribing replica is anonymous |
IPROTO_ID_FILTER | 0x51 MP_ARRAY |
Optional key used in SUBSCRIBE request, followed by an array of ids of instances whose rows won’t be relayed to the replica. Since v. 2.10.0 |
Name | Code and value type |
Description |
---|---|---|
IPROTO_TERM | 0x53 MP_UINT |
RAFT term on an instance |
IPROTO_RAFT_TERM | 0x00 MP_UINT |
RAFT term on an instance. The key is only used for requests with the IPROTO_RAFT type. |
IPROTO_RAFT_VOTE | 0x01 MP_UINT |
Instance vote in the current term (if any) |
IPROTO_RAFT_STATE | 0x02 MP_UINT |
RAFT state. Possible values: 1 – follower, 2 – candidate, 3 – leader |
IPROTO_RAFT_VCLOCK | 0x03 MP_MAP |
Current vclock of the instance |
IPROTO_RAFT_LEADER_ID | 0x04 MP_UINT |
Current leader node ID as seen by the node that issues the request Since version 2.10.0 |
IPROTO_RAFT_IS_LEADER_SEEN | 0x05 MP_BOOL |
True if the node has a direct connection to the leader node. Since version 2.10.0 |
All IPROTO_RAFT_*
keys are used only in IPROTO_RAFT*
requests.
These keys are used with SQL within SQL-specific requests and responses like IPROTO_EXECUTE and IPROTO_PREPARE.
Name | Code and value type |
Description |
---|---|---|
IPROTO_SQL_TEXT | 0x40 MP_STR |
SQL statement text |
IPROTO_STMT_ID | 0x43 MP_INT |
Identifier of the prepared statement |
IPROTO_OPTIONS | 0x2b MP_ARRAY |
SQL transaction options. Usually empty |
IPROTO_METADATA | 0x32 MP_ARRAY of MP_MAP items |
SQL transaction metadata |
IPROTO_FIELD_NAME | 0x00 MP_STR |
Field name. Nested in IPROTO_METADATA |
IPROTO_FIELD_TYPE | 0x01 MP_STR |
Field type. Nested in IPROTO_METADATA |
IPROTO_FIELD_COLL | 0x02 MP_STR |
Field collation. Nested in IPROTO_METADATA |
IPROTO_FIELD_IS_NULLABLE | 0x03 MP_BOOL |
True if the field is nullable. Nested in IPROTO_METADATA. |
IPROTO_FIELD_IS_AUTOINCREMENT | 0x04 MP_BOOL |
True if the field is auto-incremented. Nested in IPROTO_METADATA. |
IPROTO_FIELD_SPAN | 0x05 MP_STR or MP_NIL |
Original expression under SELECT. Nested in IPROTO_METADATA. See box.execute() |
IPROTO_BIND_METADATA | 0x33 MP_ARRAY |
Bind variable names and types |
IPROTO_BIND_COUNT | 0x34 MP_INT |
Number of parameters to bind |
IPROTO_SQL_BIND | 0x41 MP_ARRAY |
Parameter values to match ? placeholders or :name placeholders |
IPROTO_SQL_INFO | 0x42 MP_MAP |
Additional SQL-related parameters |
SQL_INFO_ROW_COUNT | 0x00 MP_UINT |
Number of changed rows. Is 0 for statements that do not change rows. Nested in IPROTO_SQL_INFO |
SQL_INFO_AUTO_INCREMENT_IDS | 0x01 MP_ARRAY of MP_UINT items |
New primary key value (or values) for an INSERT in a table defined with PRIMARY KEY AUTOINCREMENT. Nested in IPROTO_SQL_INFO |
Code: 0x54.
IPROTO_VERSION is an integer number reflecting the version of protocol that the client supports. The latest IPROTO_VERSION is 3.
Code: 0x55.
Available IPROTO_FEATURES are the following:
IPROTO_FEATURE_STREAMS = 0
– streams support: IPROTO_STREAM_ID in the request header.IPROTO_FEATURE_TRANSACTIONS = 1
– transaction support: IPROTO_BEGIN, IPROTO_COMMIT, and IPROTO_ROLLBACK commands (with IPROTO_STREAM_ID in the request header). Learn more about sending transaction commands.IPROTO_FEATURE_ERROR_EXTENSION = 2
– MP_ERROR MsgPack extension support. Clients that don’t support this feature receive error responses for IPROTO_EVAL and IPROTO_CALL encoded to string error messages.IPROTO_FEATURE_WATCHERS = 3
– remote watchers support: IPROTO_WATCH, IPROTO_UNWATCH, and IPROTO_EVENT commands.
Code: 0x01.
This is an unsigned integer that should be incremented so that it is unique in every request. This integer is also returned from box.session.sync().
The IPROTO_SYNC value of a response should be the same as the IPROTO_SYNC value of a request.
Code: 0x05.
Version of the database schema – an unsigned number that goes up when there is a major change in the schema.
In a request header, IPROTO_SCHEMA_VERSION is optional, so the version will not be checked if it is absent.
In a response header, IPROTO_SCHEMA_VERSION is always present, and it is up to the client to check if it has changed.
Code: 0x14.
Possible values (see iterator_type.h):
0 |
EQ |
1 |
REQ |
2 |
ALL, all tuples |
3 |
LT, less than |
4 |
LE, less than or equal |
5 |
GE, greater than or equal |
6 |
GT, greater than |
7 |
BITS_ALL_SET, all bits of the value are set in the key |
8 |
BITS_ANY_SET, at least one bit of the value is set |
9 |
BITS_ALL_NOT_SET, no bits are set |
10 |
OVERLAPS, overlaps the rectangle or box |
11 |
NEIGHBOR, neighbors the rectangle or box |
Code: 0x0a.
Only used in streams. This is an unsigned number that should be unique in every stream.
In requests, IPROTO_STREAM_ID is useful for two things: ensuring that requests within transactions are done in separate groups, and ensuring strictly consistent execution of requests (whether or not they are within transactions).
In responses, IPROTO_STREAM_ID does not appear.
IPROTO_TXN_ISOLATION is the transaction isolation level. It can take the following values:
TXN_ISOLATION_DEFAULT = 0
– use the default level frombox.cfg
(default value)TXN_ISOLATION_READ_COMMITTED = 1
– read changes that are committed but not confirmed yetTXN_ISOLATION_READ_CONFIRMED = 2
– read confirmed changesTXN_ISOLATION_BEST_EFFORT = 3
– determine isolation level automatically
See Binary protocol – streams to learn more about stream transactions in the binary protocol.
Code: 0x00.
The key is used both in requests and responses. It indicates the request or response type and has any request or response name for the value (example: IPROTO_AUTH). See requests and responses for client-server communication, replication, events and subscriptions, streams and interactive transactions.
Code: 0x52.
In case of error, the response body contains IPROTO_ERROR and IPROTO_ERROR_24 instead of IPROTO_DATA.
To learn more about error responses, check the section Request and response format.
Code: 0x31.
IPROTO_ERROR_24 is used in Tarantool versions before 2.4.1. The key contains the error in the string format.
Since Tarantool 2.4.1, Tarantool packs errors as the MP_ERROR MessagePack extension, which includes extra information. Two keys are passed in the error response body: IPROTO_ERROR and IPROTO_ERROR_24.
To learn more about error responses, check the section Request and response format.
Code: 0x21.
Multiple operations make use of this key in different ways:
IPROTO_INSERT, IPROTO_REPLACE, IPROTO_UPSERT | Tuple to be inserted |
IPROTO_UPSERT | Operations to perform |
IPROTO_AUTH | Array of 2 fields: authentication mechanism and scramble, encrypted according to the specified mechanism. See more on the authentication sequence. |
IPROTO_CALL, IPROTO_EVAL | Array of arguments |
Code: 0x09.
When it comes to replicating synchronous transactions, the IPROTO_FLAGS key is included in the header. The key contains an MP_UINT value of one or more bits:
- IPROTO_FLAG_COMMIT (0x01) is set if this is the last message for a transaction.
- IPROTO_FLAG_WAIT_SYNC (0x02) is set if this is the last message for a transaction which cannot be completed immediately.
- IPROTO_FLAG_WAIT_ACK (0x04) is set if this is the last message for a synchronous transaction.
Example:
Code: 0x53.
- The key is used in the IPROTO_RAFT_PROMOTE and IPROTO_RAFT_DEMOTE requests.
- Since version 2.11, the key is included in response to a heartbeat message. The term corresponds to the value of box.info.synchro.queue.term on the sender instance.
The vclock (vector clock) is a log sequence number map that defines the version of the dataset stored on the node. In fact, it represents the number of logical operations executed on a specific node. A vclock looks like this:
There are five keys that correspond to vector clocks in different contexts of replication. They all have the MP_MAP type:
- IPROTO_VCLOCK (0x26) is passed to a new instance joining the replica set.
- IPROTO_VCLOCK_SYNC (0x5a) is used by replication heartbeats. The master sends its heartbeats, including this monotonically growing key, to a replica. Once the replica receives a heartbeat with a non-zero IPROTO_VCLOCK_SYNC value, it starts responding with the same value in all its acknowledgements. This key was introduced in version 2.11.
- IPROTO_BALLOT_VCLOCK (0x02) is included in the IPROTO_BALLOT message. IPROTO_BALLOT is sent in response to the IPROTO_VOTE request. This key was introduced in Tarantool 2.6.1.
- IPROTO_BALLOT_GC_VCLOCK (0x03) is also included in the IPROTO_BALLOT message. IPROTO_BALLOT is sent in response to the IPROTO_VOTE request. It is the vclock of the oldest WAL entry on the instance. Corresponds to box.info.gc().vclock. This key was introduced in Tarantool 2.6.1.
- IPROTO_RAFT_VCLOCK (0x03) is included in the IPROTO_RAFT message. It is present only on the instances in the «candidate» state (IPROTO_RAFT_STATE == 2).
All IPROTO_BALLOT_* keys are only used in the IPROTO_BALLOT requests. There have been the following name changes starting with versions Tarantool 2.7.3, Tarantool 2.8.2, and Tarantool 2.10.0:
- IPROTO_BALLOT_IS_RO_CFG (0x01) was formerly called IPROTO_BALLOT_IS_RO.
- IPROTO_BALLOT_IS_RO (0x04) was formerly called IPROTO_BALLOT_IS_LOADING.
Code: 0x32.
Used with SQL within IPROTO_EXECUTE.
The key contains an array of column maps, with each column map containing at least IPROTO_FIELD_NAME (0x00) and MP_STR, and IPROTO_FIELD_TYPE (0x01) and MP_STR.
Additionally, if sql_full_metadata
in the
_session_settings system space
is TRUE, then the array has these additional column maps
which correspond to components described in the box.execute() section.
Code: 0x41.
Used with SQL within IPROTO_EXECUTE.
IPROTO_SQL_BIND is an array of parameter values to match ? placeholders or :name placeholders. It can contain values of any type, including MP_MAP.
Values that are not MP_MAP replace the
?
placeholders in the request.MP_MAP values must have the format
{[name] = value}
, wherename
is the named parameter in the request. Here is an example of such a request:tarantool> conn:execute('SELECT ?, ?, :name1, ?, :name2, :name1', {1, 2, {[':name1'] = 5}, 'str', {[':name2'] = true}}) --- - metadata: - name: COLUMN_1 type: integer - name: COLUMN_2 type: integer - name: COLUMN_3 type: integer - name: COLUMN_4 type: text - name: COLUMN_5 type: boolean - name: COLUMN_6 type: boolean rows: - [1, 2, 5, 'str', true, 5]