REST API клиента Trino

REST API позволяет клиентам отправлять SQL-запросы в Trino и получать результаты. К клиентам относятся CLI, JDBC-драйвер и другие решения, предоставляемые сообществом. Предпочтительный способ взаимодействия с Trino — использование этих существующих клиентов. Этот документ содержит справочные сведения по API. При необходимости его также можно использовать для реализации собственного клиента.

Дополнительную информацию о драйверах, клиентских приложениях и настройке клиентского протокола смотрите в документации по клиентам.

HTTP-методы

• POST на /v1/statement выполняет строку запроса из тела POST и возвращает JSON-документ с результатами запроса. Если есть дополнительные результаты, JSON-документ содержит URL-атрибут nextUri.

• GET по адресу из атрибута nextUri возвращает следующую порцию результатов.

• DELETE на nextUri завершает выполняющийся запрос.

Обзор обработки запроса

Клиентский запрос к Trino инициируется HTTP-запросом POST к endpoint /v1/statement, где тело POST содержит строку SQL-запроса. Вызывающая сторона может установить различные Заголовки клиентского запроса. Заголовки требуются только в начальном запросе POST, но не при последующих переходах по ссылкам nextUri.

Если клиентский запрос возвращает HTTP 502, 503 или 504, это означает, что возникла временная проблема при обработке запроса, и клиенту следует повторить запрос через 50-100 мс. Trino сам не генерирует эти коды, но их могут генерировать балансировщики нагрузки перед Trino.

Кроме того, если запрос возвращает код статуса 429, клиент должен повторить запрос, используя значение заголовка Retry-After.

Любой HTTP-статус, отличный от 502, 503, 504 или 200, означает, что обработка запроса завершилась неудачно.

Запрос /v1/statement POST возвращает JSON-документ типа QueryResults, а также набор заголовков ответа. Документ QueryResults содержит поле error типа QueryError, если запрос завершился ошибкой. Если этот объект отсутствует, запрос выполнен успешно. Важные аспекты QueryResults описаны в следующих разделах.

Если в JSON-документе установлено поле data, оно содержит список строк данных. Поле columns содержит список имен и типов столбцов, возвращенных запросом. Большинство заголовков ответа обрабатываются клиентом как cookie браузера и передаются обратно в виде заголовков запроса в последующих запросах, как описано ниже.

Если JSON-документ, возвращенный POST к /v1/statement, не содержит ссылку nextUri, значит запрос завершен — успешно или с ошибкой — и дополнительные запросы не требуются. Если ссылка nextUri присутствует, остаются дополнительные результаты, которые нужно получить. Клиент должен в цикле выполнять GET по nextUri, возвращенному в объекте ответа QueryResults, пока nextUri не исчезнет из ответа.

Поле status в JSON-документе предназначено только для человека и дает подсказку о состоянии запроса. Его нельзя использовать для определения того, завершен ли запрос.

Важные атрибуты QueryResults

Наиболее важные атрибуты JSON-документа QueryResults, возвращаемого endpoint-ами REST API, перечислены в этой таблице. Дополнительные сведения см. в классе io.trino.client.QueryResults из модуля trino-client в каталоге client исходного кода Trino.

QueryResults attributes

Attribute	Description
id	Идентификатор запроса.
nextUri	Если присутствует, URL для последующих запросов GET или DELETE. Если отсутствует, запрос завершен или завершился ошибкой.
columns	Список имен и типов столбцов, возвращенных запросом.
data	Атрибут data содержит список строк, возвращенных запросом. Каждая строка также является списком, который содержит значения столбцов этой строки в порядке, заданном атрибутом columns.
updateType	Человекочитаемая строка, представляющая операцию. Для запроса CREATE TABLE значение updateType равно “CREATE TABLE”; для SET SESSION — “SET SESSION” и т. д.
error	Если запрос завершился ошибкой, атрибут error содержит объект QueryError. Этот объект содержит message, errorCode и другую информацию об ошибке. Подробности см. в классе io.trino.client.QueryError модуля trino-client в каталоге client.

Диагностические атрибуты QueryResults

Эти поля QueryResults могут быть полезны при поиске причин проблем:

QueryResults diagnostic attributes

Attribute	Type	Description
queryError	QueryError	Не равен null только если запрос завершился ошибкой.
failureInfo	FailureInfo	failureInfo содержит детали причины сбоя, включая stack trace, а FailureInfo.errorLocation указывает номер строки и номер столбца запроса, где был обнаружен сбой.
warnings	List<TrinoWarning>	Обычно пустой список предупреждений.
statementStats	StatementStats	Класс, содержащий статистику выполнения запроса. Особый интерес представляет StatementStats.rootStage типа StageStats, который предоставляет статистику выполнения каждой стадии обработки запроса.

Заголовки клиентского запроса

Эта таблица перечисляет все поддерживаемые заголовки клиентского запроса. Многие из этих заголовков могут обновляться клиентом по заголовкам ответа и передаваться в следующих запросах, как cookie браузера.

Client request headers

Header name	Description
X-Trino-User	Задает пользователя сессии. Если не указан, пользователь сессии автоматически определяется через Сопоставление пользователей.
X-Trino-Original-User	Задает исходного пользователя сессии.
X-Trino-Source	Для целей отчетности задает имя ПО, отправившего запрос.
X-Trino-Catalog	Контекст каталога для обработки запроса. Устанавливается заголовком ответа X-Trino-Set-Catalog.
X-Trino-Schema	Контекст схемы для обработки запроса. Устанавливается заголовком ответа X-Trino-Set-Schema.
X-Trino-Time-Zone	Часовой пояс для обработки запроса. По умолчанию используется часовой пояс кластера Trino, а не часовой пояс клиента.
X-Trino-Language	Язык, используемый при обработке запроса и форматировании результатов, в формате строки Java Locale, например en-US для американского английского. Язык сессии может задаваться для каждого запроса отдельно через HTTP-заголовок X-Trino-Language.
X-Trino-Trace-Token	Передает trace token в движок Trino, чтобы проще находить строки логов, относящиеся к этому запросу.
X-Trino-Session	Передает список пар name=value, разделенных запятыми, как свойства сессии. Когда клиент Trino выполняет запрос SET SESSION name=value, пара name=value возвращается в заголовке ответа X-Set-Trino-Session и добавляется в список свойств сессии клиента. Если возвращается заголовок ответа X-Trino-Clear-Session, его значение — это имя свойства сессии, которое удаляется из накопленного списка клиента.
X-Trino-Role	Устанавливает “role” для обработки запроса. “role” представляет набор разрешений. Устанавливается заголовком ответа X-Trino-Set-Role. См. CREATE ROLE, чтобы понять роли.
X-Trino-Prepared-Statement	Список пар name=value, разделенных запятыми, где имена — это имена ранее подготовленных SQL-выражений, а значения — ключи, идентифицирующие исполняемую форму соответствующих подготовленных выражений.
X-Trino-Transaction-Id	Идентификатор транзакции, используемый для обработки запроса. Устанавливается заголовком ответа X-Trino-Started-Transaction-Id и очищается X-Trino-Clear-Transaction-Id.
X-Trino-Client-Info	Содержит произвольную информацию о клиентской программе, отправляющей запрос.
X-Trino-Client-Tags	Список строковых “tag”, разделенных запятыми, используемых для идентификации resource groups Trino.
X-Trino-Resource-Estimate	Список присваиваний вида resource=value, разделенных запятыми. Возможные значения resource: EXECUTION_TIME, CPU_TIME, PEAK_MEMORY и PEAK_TASK_MEMORY. Для EXECUTION_TIME и CPU_TIME значения задаются строками airlift Duration. Формат — число двойной точности и строка TimeUnit, например s для секунд, m для минут, h для часов и т. д. “PEAK_MEMORY” и “PEAK_TASK_MEMORY” задаются строками airlift DataSize в формате целого числа и суффикса B для байтов; kB для килобайтов; mB для мегабайтов; gB для гигабайтов и т. д.
X-Trino-Extra-Credential	Передает дополнительные учетные данные в коннектор. Заголовок — это строка name=value, которая сохраняется в объекте сессии Identity. Имя и значение имеют смысл только для коннектора.

Заголовки клиентского ответа

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

Client response headers

Header name	Description
X-Trino-Set-Catalog	Указывает клиенту установить каталог в заголовке запроса X-Trino-Catalog для последующих клиентских запросов.
X-Trino-Set-Schema	Указывает клиенту установить схему в заголовке запроса X-Trino-Schema для последующих клиентских запросов.
X-Trino-Set-Authorization-User	Указывает клиенту установить пользователя авторизации сессии в заголовке запроса X-Trino-User для последующих клиентских запросов. Также должен быть установлен X-Trino-Original-User.
X-Trino-Reset-Authorization-User	Указывает клиенту сбросить заголовок запроса X-Trino-User к исходному значению в последующих запросах и удалить X-Trino-Original-User, чтобы вернуть пользователя авторизации к исходному пользователю.
X-Trino-Set-Original-Roles	Указывает клиенту установить роли исходного пользователя в заголовке запроса X-Trino-Original-Roles в последующих клиентских запросах.
X-Trino-Set-Session	Значение заголовка ответа X-Trino-Set-Session — это строка вида property = value. Она указывает клиенту включать свойство сессии property со значением value в заголовок X-Trino-Session последующих клиентских запросов.
X-Trino-Clear-Session	Указывает клиенту удалить свойство сессии, имя которого является значением заголовка X-Trino-Clear-Session, из списка свойств сессии в заголовке X-Trino-Session в последующих клиентских запросах.
X-Trino-Set-Role	Указывает клиенту установить заголовок запроса X-Trino-Role в роль каталога, переданную в заголовке X-Trino-Set-Role, в последующих клиентских запросах.
X-Trino-Added-Prepare	Указывает клиенту добавить пару name=value в набор подготовленных выражений в заголовке запроса X-Trino-Prepared-Statement в последующих клиентских запросах.
X-Trino-Deallocated-Prepare	Указывает клиенту удалить подготовленное выражение, имя которого является значением заголовка X-Trino-Deallocated-Prepare, из списка подготовленных выражений клиента, отправляемых в заголовке запроса X-Trino-Prepared-Statement в последующих клиентских запросах.
X-Trino-Started-Transaction-Id	Передает идентификатор транзакции, который клиент должен возвращать в заголовке запроса X-Trino-Transaction-Id в последующих запросах.
X-Trino-Clear-Transaction-Id	Указывает клиенту очистить заголовок запроса X-Trino-Transaction-Id в последующих запросах.

ProtocolHeaders

Класс io.trino.client.ProtocolHeaders в модуле trino-client в каталоге client исходного кода Trino перечисляет все HTTP-заголовки запроса и ответа, разрешенные клиентским REST API Trino.