Keys used in requests and responses | Tarantool
Tarantool
Check out the new release policy
Reference Internals Binary protocol Keys used in requests and responses

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

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_CLUSTER_UUID 0x25
MP_STR
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 box.cfg.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_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

All IPROTO_BALLOT_* keys are only used in IPROTO_BALLOT requests. There have been some name changes starting with versions 2.7.3, 2.8.2, and 2.10.0:

  • IPROTO_BALLOT_IS_RO_CFG was formerly called IPROTO_BALLOT_IS_RO.
  • IPROTO_BALLOT_IS_RO was formerly called IPROTO_BALLOT_IS_LOADING.

Name Code and
value type
Description
IPROTO_TERM 0x53
MP_UINT
The term in which the node becomes the synchronous queue owner. Used in IPROTO_RAFT_PROMOTE
IPROTO_RAFT_TERM 0x00
MP_UINT
RAFT term on an instance
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.

Name Code and
value type
Description
IPROTO_EVENT_KEY 0x56
MP_STR
Event key name
IPROTO_EVENT_DATA 0x57
MP_OBJECT
Event data sent to a remote watcher

Learn more about events and subscriptions in iproto.

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:

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.

See Binary protocol – streams.

IPROTO_TXN_ISOLATION is the transaction isolation level. It can take the following values:

  • TXN_ISOLATION_DEFAULT = 0 – use the default level from box.cfg (default value)
  • TXN_ISOLATION_READ_COMMITTED = 1 – read changes that are committed but not confirmed yet
  • TXN_ISOLATION_READ_CONFIRMED = 2 – read confirmed changes
  • TXN_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 prior to 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 (“chap-sha1” is the only supported mechanism right now) 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) will be set if this is the last message for a transaction.
  • IPROTO_FLAG_WAIT_SYNC (0x02) will be set if this is the last message for a transaction which cannot be completed immediately.
  • IPROTO_FLAG_WAIT_ACK (0x04) will be set if this is the last message for a synchronous transaction.

Example:

Example of IPROTO_FLAGS usageSizeMP_UINTHeader............IPROTO_FLAGSMP_UINTBody...

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:

vclockreplica_id1LSN1replica_id2LSN2......

There are four keys that correspond to vector clocks in different contexts of replication. They all have the MP_MAP type:

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 will have 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}, where name 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]
    
Found what you were looking for?
Feedback