Интерфейс командной строки#

Trino CLI предоставляет терминальную интерактивную оболочку для выполнения запросов. CLI представляет собой самоисполняемый JAR-файл, поэтому ведет себя как обычный исполняемый файл UNIX.

CLI использует Клиентский протокол поверх HTTP/HTTPS для взаимодействия с координатором в кластере.

Требования#

Trino CLI предъявляет следующие требования:

Java версии 11 или выше, доступная в PATH. Java 22 или выше рекомендуется для лучшей производительности распаковки.
Сетевой доступ по HTTP/HTTPS к координатору кластера Trino.
Сетевой доступ к настроенному объектному хранилищу, если включен Протокол спулинга.

Версия CLI должна совпадать с версией кластера Trino или быть новее. Более старые версии обычно работают, но регулярно тестируется только часть комбинаций. Версии до 350 не поддерживаются.

Установка#

Скачайте trino-cli-latest, переименуйте файл в trino, сделайте его исполняемым с помощью chmod +x и запустите, чтобы вывести версию CLI:

./trino --version

Запустите CLI с --help или -h, чтобы увидеть все доступные опции.

Пользователи Windows и пользователи, которые не могут выполнить предыдущие шаги, могут использовать эквивалентную команду java с опцией -jar, чтобы запустить CLI и вывести версию:

java -jar trino-cli-*-executable.jar --version

Этот синтаксис можно использовать для примеров в следующих разделах. Кроме того, команда java позволяет добавлять параметры конфигурации среды выполнения Java с помощью синтаксиса -D. Это полезно для отладки и диагностики, например при указании дополнительных параметров отладки Kerberos.

Запуск CLI#

Минимальная команда для запуска CLI в интерактивном режиме указывает URL координатора в кластере Trino:

./trino http://trino.example.com:8080

При успешном подключении появится приглашение для выполнения команд. Используйте команду help, чтобы увидеть список поддерживаемых команд. Используйте команду clear, чтобы очистить терминал. Чтобы остановить CLI и выйти из него, выполните exit или quit:

trino> help

Supported commands:
QUIT
EXIT
CLEAR
EXPLAIN [ ( option [, ...] ) ] <query>
    options: FORMAT { TEXT | GRAPHVIZ | JSON }
            TYPE { LOGICAL | DISTRIBUTED | VALIDATE | IO }
DESCRIBE <table>
SHOW COLUMNS FROM <table>
SHOW FUNCTIONS
SHOW CATALOGS [LIKE <pattern>]
SHOW SCHEMAS [FROM <catalog>] [LIKE <pattern>]
SHOW TABLES [FROM <schema>] [LIKE <pattern>]
USE [<catalog>.]<schema>

Теперь можно выполнять SQL-операторы. После обработки CLI показывает результаты и статистику.

trino> SELECT count(*) FROM tpch.tiny.nation;

_col0
-------
    25
(1 row)

Query 20220324_213359_00007_w6hbk, FINISHED, 1 node
Splits: 13 total, 13 done (100.00%)
2.92 [25 rows, 0B] [8 rows/s, 0B/s]

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

./trino http://trino.example.com:8080/tpch/tiny

trino:tiny> SHOW TABLES;

  Table
----------
customer
lineitem
nation
orders
part
partsupp
region
supplier
(8 rows)

Каталог и схему по умолчанию также можно задать оператором USE.

trino> USE tpch.tiny;
USE
trino:tiny>

Для дополнительной настройки CLI в интерактивном режиме доступно множество других опций:

Опция	Описание
`--catalog`	Задает каталог по умолчанию. При необходимости также используйте `--schema`, чтобы задать схему по умолчанию. Каталог и схему по умолчанию можно изменить с помощью USE.
`--client-info`	Добавляет произвольный текст как дополнительную информацию о клиенте.
`--client-request-timeout`	Задает продолжительность обработки запроса, после которой клиентский запрос завершается. По умолчанию — `2m`.
`--client-tags`	Добавляет дополнительные теги о клиенте и пользователе CLI. Несколько тегов разделяются запятыми. Теги можно использовать как входные данные для Resource groups.
`--debug`	Включает отображение отладочной информации во время использования CLI для Устранение неполадок. Показывает больше сведений о статистике обработки запросов.
`--decimal-data-size`	Показывает размер данных и скорость в системе с основанием 10 (kB, MB и т. д.), а не в используемой по умолчанию системе с основанием 2 (KiB, MiB и т. д.).
`--disable-auto-suggestion`	Отключает предложения автодополнения.
`--disable-compression`	Отключает сжатие результатов запросов.
`--editing-mode`	Задает сочетания клавиш в CLI, совместимые с редакторами VI или EMACS. По умолчанию — `EMACS`.
`--extra-credential`	Дополнительные учетные данные. Свойство можно использовать несколько раз; формат — `key=value`.
`--extra-header`	HTTP-заголовок, добавляемый к аутентифицированным HTTP-запросам. Свойство можно использовать несколько раз; формат — `key=value`.
`--http-proxy`	Настраивает URL HTTP-прокси для подключения к Trino.
`--history-file`	Путь к файлу истории. По умолчанию — `~/.trino_history`.
`--network-logging`	Настраивает уровень детализации сетевого журналирования CLI. По умолчанию — `NONE`; другие варианты: `BASIC`, `HEADERS` или `BODY`.
`--output-format-interactive=<format>`	Указывает формат для вывода результатов запроса. По умолчанию — `ALIGNED`.
`--pager=<pager>`	Путь к программе pager, используемой для отображения результатов запроса. Установите пустое значение, чтобы полностью отключить постраничный вывод. По умолчанию используется `less` с тщательно подобранным набором опций.
`--no-progress`	Не показывать ход обработки запроса.
`--path`	Задает SQL path по умолчанию для сеанса. Полезно для задания расположения каталога и схемы для Catalog user-defined functions.
`--password`	Запрашивает пароль. Используйте, если сервер Trino требует аутентификацию по паролю. Чтобы избежать приглашения, можно задать переменную окружения `TRINO_PASSWORD` со значением пароля. Дополнительные сведения см. в Аутентификация по имени пользователя и паролю.
`--schema`	Задает схему по умолчанию. Должно использоваться вместе с `--catalog`. Каталог и схему по умолчанию можно изменить с помощью USE.
`--server`	HTTP/HTTPS-адрес и порт координатора Trino. Порт должен соответствовать порту, на котором координатор Trino принимает подключения. Порт 80 для HTTP и порт 443 для HTTPS можно опустить. Расположение сервера Trino по умолчанию — `http://localhost:8080`. Можно задавать только если URL не указан.
`--session`	Задает одно или несколько свойств сеанса. Свойство можно использовать несколько раз в формате `session_property_name=value`.
`--socks-proxy`	Настраивает URL SOCKS-прокси для подключения к Trino.
`--source`	Указывает имя приложения или источника, подключающегося к Trino. По умолчанию — `trino-cli`. Значение можно использовать как входные данные для Resource groups.
`--timezone`	Задает часовой пояс сеанса с помощью имени часового пояса. По умолчанию используется часовой пояс, заданный на вашей рабочей станции.
`--user`	Задает имя пользователя для Аутентификация по имени пользователя и паролю. По умолчанию используется имя пользователя операционной системы. Имя пользователя по умолчанию можно переопределить, если кластер использует другое имя пользователя или механизм аутентификации.

Большинство опций также можно задать как параметры в URL. Это означает, что URL JDBC можно использовать в CLI после удаления префикса jdbc:. Однако один и тот же параметр нельзя указывать обоими способами. См. справочник параметров драйвера JDBC, чтобы узнать имена параметров URL. Например:

./trino 'https://trino.example.com?SSL=true&SSLVerification=FULL&clientInfo=extra'

TLS/HTTPS#

Trino обычно доступен по HTTPS URL. Это означает, что весь сетевой трафик между CLI и Trino использует TLS. Конфигурация TLS часто используется, поскольку она требуется для любой аутентификации.

Используйте HTTPS URL для подключения к серверу:

./trino https://trino.example.com

Рекомендуемая реализация TLS — использовать глобально доверенный сертификат. В этом случае другие опции не нужны, поскольку JVM, запускающая CLI, распознает такие сертификаты.

Используйте опции из следующей таблицы для дополнительной настройки TLS и использования сертификатов:

Опция	Описание
`--insecure`	Пропустить проверку сертификата при подключении с TLS/HTTPS. Следует использовать только для отладки.
`--keystore-path`	Расположение файла Java Keystore, содержащего сертификат сервера для подключения с TLS.
`--keystore-password`	Пароль для keystore. Он должен совпадать с паролем, указанным при создании keystore.
`--keystore-type`	Определяется форматом файла keystore. Тип keystore по умолчанию — JKS. Эта расширенная опция нужна только при использовании пользовательской реализации поставщика Java Cryptography Architecture (JCA).
`--use-system-keystore`	Использовать клиентский сертификат, полученный из системного keystore операционной системы. Поддерживаются Windows и macOS. Для других операционных систем используется Java keystore по умолчанию. Тип keystore можно переопределить с помощью `--keystore-type`.
`--truststore-password`	Пароль для truststore. Он должен совпадать с паролем, указанным при создании truststore.
`--truststore-path`	Расположение файла Java truststore, который будет использоваться для защиты TLS.
`--truststore-type`	Определяется форматом файла truststore. Тип keystore по умолчанию — JKS. Эта расширенная опция нужна только при использовании пользовательской реализации поставщика Java Cryptography Architecture (JCA).
`--use-system-truststore`	Проверять сертификат сервера с помощью системного truststore операционной системы. Поддерживаются Windows и macOS. Для других операционных систем используется Java truststore по умолчанию. Тип truststore можно переопределить с помощью `--truststore-type`.

Аутентификация#

Trino CLI поддерживает многие типы аутентификации, подробно описанные в следующих разделах.

Аутентификация по имени пользователя и паролю#

Аутентификация по имени пользователя и паролю обычно настраивается в кластере с помощью типа аутентификации PASSWORD, например через LDAP-аутентификация или Аутентификация по файлу паролей.

Следующий пример подключается к серверу, задает имя пользователя и заставляет CLI запросить пароль:

./trino https://trino.example.com --user=exampleusername --password

Либо задайте пароль как значение переменной окружения TRINO_PASSWORD. Обычно используют одинарные кавычки, чтобы избежать проблем со специальными символами, такими как $:

export TRINO_PASSWORD='LongSecurePassword123!@#'

Если переменная окружения TRINO_PASSWORD задана, CLI не запрашивает пароль для подключения.

./trino https://trino.example.com --user=exampleusername --password

Внешняя аутентификация — SSO#

Используйте опцию --external-authentication для браузерной SSO-аутентификации, как подробно описано в OAuth 2.0-аутентификация. При такой конфигурации CLI показывает URL, который нужно открыть в веб-браузере для аутентификации.

Подробное поведение:

Запустите CLI с опцией --external-authentication и выполните запрос.
CLI запускается и подключается к Trino.
При отправке первого запроса в CLI появляется сообщение с указанием открыть браузер по заданному URL.
Откройте URL в браузере и пройдите процесс аутентификации.
CLI автоматически получает токен.
После успешной аутентификации в браузере CLI продолжает выполнение запроса.
Последующие запросы в сеансе CLI не требуют дополнительных входов, пока токен аутентификации остается действительным. Срок действия токена зависит от конфигурации типа внешней аутентификации.
Токены с истекшим сроком действия вынуждают войти снова.

Аутентификация по сертификату#

Используйте следующие аргументы CLI для подключения к кластеру, который использует аутентификацию по сертификату.

Опции CLI для аутентификации по сертификату#
Опция	Описание
`--keystore-path=<path>`	Абсолютный или относительный путь к файлу PEM или JKS, который должен содержать сертификат, доверенный кластером Trino, к которому выполняется подключение.
`--keystore-password=<password>`	Требуется только если у keystore есть пароль.

Опции, связанные с truststore, не зависят от аутентификации клиентским сертификатом в CLI; вместо этого они управляют доверием клиента к сертификату сервера.

Аутентификация JWT#

Чтобы получить доступ к кластеру Trino, настроенному для использования JWT-аутентификация, передайте JWT серверу с помощью опции --access-token=<token>.

Аутентификация Kerberos#

Trino CLI может подключаться к кластеру Trino, где включен Kerberos-аутентификация.

Вызов CLI с включенной поддержкой Kerberos требует нескольких дополнительных опций командной строки. Также на машине, запускающей CLI, нужны файлы конфигурации Kerberos для вашего пользователя. Самый простой способ запустить CLI — использовать wrapper-скрипт:

#!/bin/bash

./trino \
  --server https://trino.example.com \
  --krb5-config-path /etc/krb5.conf \
  --krb5-principal someuser@EXAMPLE.COM \
  --krb5-keytab-path /home/someuser/someuser.keytab \
  --krb5-remote-service-name trino

При использовании аутентификации Kerberos доступ к координатору Trino должен осуществляться через TLS и HTTPS.

В следующей таблице перечислены доступные опции для аутентификации Kerberos:

Опции CLI для аутентификации Kerberos#
Опция	Описание
`--krb5-config-path`	Путь к файлам конфигурации Kerberos.
`--krb5-credential-cache-path`	Путь к кэшу учетных данных Kerberos.
`--krb5-disable-remote-service-hostname-canonicalization`	Отключить каноникализацию имени хоста службы с помощью обратного DNS-поиска.
`--krb5-keytab-path`	Расположение keytab, который можно использовать для аутентификации principal, указанного в `--krb5-principal`.
`--krb5-principal`	Principal, используемый при аутентификации на координаторе.
`--krb5-remote-service-name`	Имя службы Kerberos координатора Trino.
`--krb5-service-principal-pattern`	Шаблон principal удаленной службы Kerberos. По умолчанию — `${SERVICE}@${HOST}`.

Дополнительная отладочная информация Kerberos#

Можно включить дополнительную отладочную информацию Kerberos для процесса Trino CLI, передав -Dsun.security.krb5.debug=true, -Dtrino.client.debugKerberos=true и -Djava.security.debug=gssloginconfig,configfile,configparser,logincontext как аргументы JVM при запуске процесса CLI:

java \
  -Dsun.security.krb5.debug=true \
  -Djava.security.debug=gssloginconfig,configfile,configparser,logincontext \
  -Dtrino.client.debugKerberos=true \
  -jar trino-cli-*-executable.jar \
  --server https://trino.example.com \
  --krb5-config-path /etc/krb5.conf \
  --krb5-principal someuser@EXAMPLE.COM \
  --krb5-keytab-path /home/someuser/someuser.keytab \
  --krb5-remote-service-name trino

Помощь в интерпретации отладочных сообщений Kerberos см. в дополнительных ресурсах.

Постраничный вывод#

По умолчанию результаты запросов выводятся постранично с помощью программы less, настроенной тщательно подобранным набором опций. Это поведение можно переопределить, задав опцию --pager или переменную окружения TRINO_PAGER с именем другой программы, например more или pspg, либо можно задать пустое значение, чтобы полностью отключить постраничный вывод.

История#

CLI хранит историю ранее использованных команд. Историю можно просматривать прокруткой или поиском. Используйте стрелки вверх и вниз для прокрутки, а Control+S и Control+R для поиска. Чтобы выполнить запрос снова, нажмите Enter.

По умолчанию файл истории Trino находится в ~/.trino_history. Используйте опцию --history-file или переменную окружения TRINO_HISTORY_FILE, чтобы изменить значение по умолчанию.

Автопредложение#

CLI создает предложения автодополнения на основе истории команд.

Нажмите →, чтобы принять предложение и заменить текущий буфер командной строки. Нажмите Ctrl+→ (Option+→ на Mac), чтобы принять только следующее ключевое слово. Продолжайте ввод, чтобы отклонить предложение.

Файл конфигурации#

CLI может читать значения по умолчанию для всех опций из файла. Он использует первый найденный файл из упорядоченного списка расположений:

Путь к файлу, заданный значением переменной окружения TRINO_CONFIG.
.trino_config в домашнем каталоге текущего пользователя.
$XDG_CONFIG_HOME/trino/config.

Например, можно создать отдельные файлы конфигурации с разными опциями аутентификации, такие как kerberos-cli.properties и ldap-cli.properties. Если они находятся в текущем каталоге, можно задать переменную окружения TRINO_CONFIG для одного запуска CLI, добавив ее перед командой trino:

TRINO_CONFIG=kerberos-cli.properties trino https://first-cluster.example.com:8443
TRINO_CONFIG=ldap-cli.properties trino https://second-cluster.example.com:8443

В предыдущем примере файлы конфигурации по умолчанию не используются.

Все поддерживаемые опции можно использовать в файле свойств конфигурации без префикса --. Опции, которые обычно не принимают аргумент, являются логическими, поэтому задавайте для них true или false. Например:

output-format-interactive=AUTO
timezone=Europe/Warsaw
user=trino-client
network-logging=BASIC
krb5-disable-remote-service-hostname-canonicalization=true

Пакетный режим#

Запуск Trino CLI с --execute, --file или передача запросов в стандартный ввод использует пакетный, неинтерактивный режим. В этом режиме CLI не сообщает о ходе выполнения и завершает работу после обработки переданных запросов. По умолчанию результаты печатаются в формате CSV. Можно настроить другие форматы и перенаправить вывод в файл.

Для дополнительной настройки CLI в пакетном режиме доступны следующие опции:

Опция	Описание
`--execute=<execute>`	Выполнить указанные операторы и выйти.
`-f`, `--file=<file>`	Выполнить операторы из файла и выйти.
`--ignore-errors`	Продолжать обработку в пакетном режиме при возникновении ошибки. По умолчанию выполнение завершается немедленно.
`--output-format=<format>`	Указать формат для вывода результатов запроса. По умолчанию — `CSV`.
`--progress`	Показывать ход выполнения запроса в пакетном режиме. Это не влияет на вывод, который, например, можно безопасно перенаправить в файл.

Примеры#

Рассмотрим следующую команду в показанном виде или с опцией --output-format=CSV, которая используется по умолчанию в неинтерактивном режиме:

trino --execute 'SELECT nationkey, name, regionkey FROM tpch.sf1.nation LIMIT 3'

Вывод выглядит так:

"0","ALGERIA","0"
"1","ARGENTINA","1"
"2","BRAZIL","1"

Вывод с опцией --output-format=JSON:

{"nationkey":0,"name":"ALGERIA","regionkey":0}
{"nationkey":1,"name":"ARGENTINA","regionkey":1}
{"nationkey":2,"name":"BRAZIL","regionkey":1}

Вывод с опцией --output-format=ALIGNED, которая используется по умолчанию в интерактивном режиме:

nationkey |   name    | regionkey
----------+-----------+----------
        0 | ALGERIA   |         0
        1 | ARGENTINA |         1
        2 | BRAZIL    |         1

Вывод с опцией --output-format=VERTICAL:

-[ RECORD 1 ]--------
nationkey | 0
name      | ALGERIA
regionkey | 0
-[ RECORD 2 ]--------
nationkey | 1
name      | ARGENTINA
regionkey | 1
-[ RECORD 3 ]--------
nationkey | 2
name      | BRAZIL
regionkey | 1

Предыдущая команда с --output-format=NULL не выводит результат. Однако если в запросе есть ошибка, например некорректное использование region вместо regionkey, команда завершается со статусом 1 и показывает сообщение об ошибке (на него формат вывода не влияет):

Query 20200707_170726_00030_2iup9 failed: line 1:25: Column 'region' cannot be resolved
SELECT nationkey, name, region FROM tpch.sf1.nation LIMIT 3

Протокол спулинга#

Trino CLI автоматически использует протокол спулинга для повышения пропускной способности клиентского взаимодействия с более высокими требованиями к передаче данных, если в кластере настроен Протокол спулинга.

При необходимости используйте опцию --encoding, чтобы настроить желаемую кодировку, отличную от значения по умолчанию в кластере. Доступные значения: json+zstd (рекомендуется) для JSON со сжатием Zstandard, json+lz4 для JSON со сжатием LZ4 и json для несжатого JSON.

Процесс CLI должен иметь сетевой доступ к объектному хранилищу спулинга.

Форматы вывода#

Trino CLI предоставляет опции --output-format и --output-format-interactive для управления отображением вывода. Доступные опции, показанные в следующей таблице, нужно вводить в верхнем регистре. Значение по умолчанию — ALIGNED в интерактивном режиме и CSV в неинтерактивном режиме.

Опции формата вывода#
Опция	Описание
`CSV`	Значения, разделенные запятыми; каждое значение заключено в кавычки. Без строки заголовка.
`CSV_HEADER`	Значения, разделенные запятыми и заключенные в кавычки, со строкой заголовка.
`CSV_UNQUOTED`	Значения, разделенные запятыми, без кавычек.
`CSV_HEADER_UNQUOTED`	Значения, разделенные запятыми, со строкой заголовка, но без кавычек.
`TSV`	Значения, разделенные табуляцией.
`TSV_HEADER`	Значения, разделенные табуляцией, со строкой заголовка.
`JSON`	Строки вывода выдаются как JSON-объекты с парами имя-значение.
`ALIGNED`	Вывод формируется как ASCII-таблица со значениями.
`VERTICAL`	Вывод формируется как ориентированные на записи строки сверху вниз, по одной строке на значение.
`AUTO`	То же, что `ALIGNED`, если вывод помещается в текущую ширину терминала, и `VERTICAL` в противном случае.
`MARKDOWN`	Вывод формируется как таблица Markdown.
`NULL`	Подавляет обычные результаты запроса. Это может быть полезно при разработке для проверки кода возврата shell-команды запроса или для проверки того, приводит ли запрос к сообщениям об ошибке.

Устранение неполадок#

Если что-то идет не так, отображается сообщение об ошибке:

$ trino
trino> select count(*) from tpch.tiny.nations;
Query 20200804_201646_00003_f5f6c failed: line 1:22: Table 'tpch.tiny.nations' does not exist
select count(*) from tpch.tiny.nations

Чтобы увидеть отладочную информацию, включая stack trace для ошибок, используйте опцию --debug:

$ trino --debug
trino> select count(*) from tpch.tiny.nations;
Query 20200804_201629_00002_f5f6c failed: line 1:22: Table 'tpch.tiny.nations' does not exist
io.trino.spi.TrinoException: line 1:22: Table 'tpch.tiny.nations' does not exist
at io.trino.sql.analyzer.SemanticExceptions.semanticException(SemanticExceptions.java:48)
at io.trino.sql.analyzer.SemanticExceptions.semanticException(SemanticExceptions.java:43)
...
at java.base/java.lang.Thread.run(Thread.java:834)
select count(*) from tpch.tiny.nations