Ключи, используемые в запросах и ответах

В этом разделе описаны ключи iproto, содержащиеся в запросах и ответах. Ключи – это константы Tarantool, которые определены или упомянуты в файле iproto_constants.h.

Хотя сами ключи являются 8-битными целыми числами без знака, их значения могут иметь разные типы.

Все ключи IPROTO_RAFT_* используются только в запросах IPROTO_RAFT*.

Подробнее о событиях и подписках в iproto см. box-protocol-watchers.

Эти ключи используются с SQL в специфичных для SQL запросах и ответах, таких как IPROTO_EXECUTE и IPROTO_PREPARE.

Код: 0x54.

IPROTO_VERSION – целое число, отражающее версию протокола, которую поддерживает клиент. Последняя версия IPROTO_VERSION – IPROTO_VERSION.

Код: 0x55.

Доступные IPROTO_FEATURES:

• IPROTO_FEATURE_STREAMS = 0 – поддержка потоков: IPROTO_STREAM_ID в заголовке запроса.

• IPROTO_FEATURE_TRANSACTIONS = 1 – поддержка транзакций: команды IPROTO_BEGIN, IPROTO_COMMIT и IPROTO_ROLLBACK (с IPROTO_STREAM_ID в заголовке запроса). Подробнее см. отправку команд транзакций.

• IPROTO_FEATURE_ERROR_EXTENSION = 2 – поддержка расширения MP_ERROR MsgPack. Клиенты, не поддерживающие эту возможность, получают ответы об ошибках на IPROTO_EVAL и IPROTO_CALL в виде строковых сообщений об ошибках.

• IPROTO_FEATURE_WATCHERS = 3 – поддержка удаленных наблюдателей: команды IPROTO_WATCH, IPROTO_UNWATCH и IPROTO_EVENT.

• IPROTO_FEATURE_INSERT_ARROW = 12 – поддержка вставки данных в формате Arrow. Подробнее об этой возможности. Доступно начиная с версии 3.3.0.

Код: 0x01.

Это беззнаковое целое число, которое должно увеличиваться так, чтобы быть уникальным для каждого запроса. Это число также возвращается функцией box.session.sync().

Значение IPROTO_SYNC в ответе должно совпадать со значением IPROTO_SYNC в запросе.

Код: 0x05.

Версия схемы базы данных – беззнаковое число, которое увеличивается при значительном изменении схемы.

В заголовке запроса IPROTO_SCHEMA_VERSION является необязательным, поэтому при его отсутствии версия проверяться не будет.

В заголовке ответа IPROTO_SCHEMA_VERSION присутствует всегда, и проверка того, изменилась ли версия, выполняется на стороне клиента.

Код: 0x14.

Возможные значения (см. iterator_type.h):

Код: 0x0a.

Используется только в потоках. Это беззнаковое число, которое должно быть уникальным для каждого потока.

В запросах IPROTO_STREAM_ID используется для двух целей: обеспечения выполнения запросов внутри транзакций отдельными группами и обеспечения строго консистентного выполнения запросов (вне зависимости от того, выполняются ли они внутри транзакций).

В ответах IPROTO_STREAM_ID не используется.

См. Бинарный протокол – потоки.

IPROTO_TXN_ISOLATION – уровень изоляции транзакций. Может принимать следующие значения:

• TXN_ISOLATION_DEFAULT = 0 – использовать уровень по умолчанию из box.cfg (значение по умолчанию)
• TXN_ISOLATION_READ_COMMITTED = 1 – чтение зафиксированных, но еще не подтвержденных изменений
• TXN_ISOLATION_READ_CONFIRMED = 2 – чтение подтвержденных изменений
• TXN_ISOLATION_BEST_EFFORT = 3 – определять уровень изоляции автоматически

См. Бинарный протокол – потоки, чтобы узнать больше о потоковых транзакциях в бинарном протоколе.

Код: 0x00.

Этот ключ используется как в запросах, так и в ответах. Он указывает тип запроса или ответа и в качестве значения содержит имя запроса или ответа (например: IPROTO_AUTH). Запросы и ответы см. в разделах взаимодействие клиента и сервера, репликация, события и подписки, потоки и интерактивные транзакции.

Код: 0x52.

В случае ошибки тело ответа содержит IPROTO_ERROR и IPROTO_ERROR_24 вместо IPROTO_DATA.

Подробнее об ответах с ошибками см. в разделе Формат запросов и ответов.

Код: 0x31.

IPROTO_ERROR_24 используется в версиях Tarantool до 2.4.1. Ключ содержит ошибку в строковом формате.

Начиная с Tarantool 2.4.1 Tarantool упаковывает ошибки как расширение MP_ERROR MessagePack, которое включает дополнительную информацию. В теле ответа с ошибкой передаются два ключа: IPROTO_ERROR и IPROTO_ERROR_24.

Подробнее об ответах с ошибками см. в разделе Формат запросов и ответов.

Код: 0x21.

Несколько операций используют этот ключ по-разному:

Код: 0x09.

При репликации синхронных транзакций ключ IPROTO_FLAGS включается в заголовок. Ключ содержит значение MP_UINT с одним или несколькими битами:

• IPROTO_FLAG_COMMIT (0x01) устанавливается, если это последнее сообщение транзакции.

• IPROTO_FLAG_WAIT_SYNC (0x02) устанавливается, если это последнее сообщение транзакции, которая не может быть завершена немедленно.

• IPROTO_FLAG_WAIT_ACK (0x04) устанавливается, если это последнее сообщение синхронной транзакции.

Пример:

Код: 0x53.

• Ключ используется в запросах IPROTO_RAFT_PROMOTE и IPROTO_RAFT_DEMOTE.
• Начиная с версии 2.11 ключ включается в ответ на сообщение heartbeat. Терм соответствует значению box.info.synchro.queue.term на экземпляре-отправителе.

Vclock (векторные часы) – это карта порядковых номеров журнала, определяющая версию набора данных, хранящегося на узле. Фактически она представляет количество логических операций, выполненных на конкретном узле. Vclock выглядит так:

Существует пять ключей, соответствующих векторным часам в различных контекстах репликации. Все они имеют тип MP_MAP:

• IPROTO_VCLOCK (0x26) передается новому экземпляру, присоединяющемуся к набору реплик.

• IPROTO_VCLOCK_SYNC (0x5a) используется в heartbeat-сообщениях репликации. Мастер отправляет свои heartbeat-сообщения реплике, включая этот монотонно возрастающий ключ. Как только реплика получает heartbeat с ненулевым значением IPROTO_VCLOCK_SYNC, она начинает отвечать с тем же значением во всех подтверждениях. Этот ключ был добавлен в версии 2.11.

• IPROTO_BALLOT_VCLOCK (0x02) включается в сообщение IPROTO_BALLOT. IPROTO_BALLOT отправляется в ответ на запрос IPROTO_VOTE. Этот ключ был добавлен в /release/2.6.1.

• IPROTO_BALLOT_GC_VCLOCK (0x03) также включается в сообщение IPROTO_BALLOT. IPROTO_BALLOT отправляется в ответ на запрос IPROTO_VOTE. Это vclock самой старой записи WAL на экземпляре. Соответствует box.info.gc().vclock. Этот ключ был добавлен в /release/2.6.1.

• IPROTO_RAFT_VCLOCK (0x03) включается в сообщение IPROTO_RAFT. Присутствует только на экземплярах в состоянии "candidate" (IPROTO_RAFT_STATE == 2).

Все ключи IPROTO_BALLOT* используются только в запросах IPROTO_BALLOT. Начиная с версий /release/2.7.3, /release/2.8.2 и /release/2.10.0 были произведены следующие переименования:

• IPROTO_BALLOT_IS_RO_CFG (0x01) ранее назывался IPROTO_BALLOT_IS_RO.
• IPROTO_BALLOT_IS_RO (0x04) ранее назывался IPROTO_BALLOT_IS_LOADING.

Код: 0x32.

Используется с SQL в рамках IPROTO_EXECUTE.

Ключ содержит массив карт колонок, при этом каждая карта колонки содержит как минимум IPROTO_FIELD_NAME (0x00) и MP_STR, а также IPROTO_FIELD_TYPE (0x01) и MP_STR.

Кроме того, если sql_full_metadata в системном пространстве _session_settings имеет значение TRUE, то массив содержит дополнительные карты колонок, соответствующие компонентам, описанным в разделе box.execute().

Код: 0x41.

Используется с SQL в рамках IPROTO_EXECUTE.

IPROTO_SQL_BIND – это массив значений параметров для подстановки вместо плейсхолдеров. Может содержать значения любого типа, включая MP_MAP.

• Значения, не являющиеся MP_MAP, заменяют плейсхолдеры ? в запросе.

• Значения MP_MAP должны иметь формат {[name] = value}, где name – именованный параметр в запросе. Пример такого запроса:

   
  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: booleanrows:- [1, 2, 5, 'str', true, 5]