Клиент ClickHouse

ClickHouse предоставляет штатный клиент командной строки для выполнения SQL‑запросов напрямую к серверу ClickHouse. Он поддерживает как интерактивный режим (для выполнения запросов в реальном времени), так и пакетный режим (для скриптов и автоматизации). Результаты запросов могут отображаться в терминале или экспортироваться в файл; поддерживаются все форматы вывода ClickHouse, такие как Pretty, CSV, JSON и другие.

Клиент предоставляет информацию о выполнении запросов в реальном времени с индикатором прогресса, количеством прочитанных строк, объёмом обработанных данных (в байтах) и временем выполнения запроса. Он поддерживает как параметры командной строки, так и файлы конфигурации.

Установка

Чтобы загрузить ClickHouse, выполните команду:

curl https://clickhouse.com/ | sh

Чтобы установить его, выполните:

sudo ./clickhouse install

Дополнительные варианты установки см. в разделе Install ClickHouse.

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

Запуск

Примечание

Если вы только скачали, но ещё не установили ClickHouse, используйте ./clickhouse client вместо clickhouse-client.

Чтобы подключиться к серверу ClickHouse, выполните следующую команду:

$ clickhouse-client --host server

ClickHouse client version 24.12.2.29 (official build).
Подключение к server:9000 как пользователь default.
Подключено к серверу ClickHouse версии 24.12.2.

:)

Укажите при необходимости дополнительные параметры подключения:

Option	Description
--port <port>	Порт, на котором сервер ClickHouse принимает подключения. Порты по умолчанию: 9440 (TLS) и 9000 (без TLS). Обратите внимание, что ClickHouse Client использует нативный протокол, а не HTTP(S).
-s [ --secure ]	Использовать ли TLS (обычно определяется автоматически).
-u [ --user ] <username>	Имя пользователя базы данных, под которым выполняется подключение. По умолчанию выполняется подключение от имени пользователя default.
--password <password>	Пароль пользователя базы данных. Пароль для подключения также можно указать в конфигурационном файле. Если вы не укажете пароль, клиент запросит его.
-c [ --config ] <path-to-file>	Расположение конфигурационного файла для ClickHouse Client, если он не находится в одном из стандартных мест. См. раздел Configuration Files.
--connection <name>	Имя преднастроенного подключения из configuration file.

Полный список параметров командной строки см. в разделе Command Line Options.

Подключение к ClickHouse Cloud

Информация о вашем сервисе ClickHouse Cloud доступна в консоли ClickHouse Cloud. Выберите сервис, к которому нужно подключиться, и нажмите Connect:

Выберите Native — после этого будут показаны детали подключения вместе с примером команды clickhouse-client:

Хранение подключений в файле конфигурации

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

Формат имеет следующий вид:

<config>
    <connections_credentials>
        <connection>
            <name>default</name>
            <hostname>hostname</hostname>
            <port>9440</port>
            <secure>1</secure>
            <user>default</user>
            <password>password</password>
            <!-- <history_file></history_file> -->
            <!-- <history_max_entries></history_max_entries> -->
            <!-- <accept-invalid-certificate>false</accept-invalid-certificate> -->
            <!-- <prompt></prompt> -->
        </connection>
    </connections_credentials>
</config>

См. раздел о файлах конфигурации для получения дополнительной информации.

Примечание

Чтобы сосредоточиться на синтаксисе запросов, в последующих примерах опущены параметры подключения (--host, --port и т. д.). Не забудьте добавить их, когда будете использовать команды.

Интерактивный режим

Использование интерактивного режима

Чтобы запустить ClickHouse в интерактивном режиме, достаточно выполнить:

clickhouse-client

Это откроет цикл Read-Eval-Print (REPL), в котором вы сможете интерактивно вводить SQL-запросы. После подключения вы увидите приглашение командной строки, где сможете вводить запросы:

Клиент ClickHouse версии 25.x.x.x
Подключение к localhost:9000 от имени пользователя default.
Подключено к серверу ClickHouse версии 25.x.x.x

hostname :)

В интерактивном режиме формат вывода по умолчанию — PrettyCompact. Вы можете изменить формат в секции FORMAT запроса или указав параметр командной строки --format. Чтобы использовать формат Vertical, вы можете указать --vertical или добавить \G в конце запроса. В этом формате каждое значение выводится на отдельной строке, что удобно для широких таблиц.

В интерактивном режиме по умолчанию любой введённый запрос выполняется при нажатии Enter. Точка с запятой в конце запроса не обязательна.

Вы можете запустить клиент с параметром -m, --multiline. Чтобы ввести многострочный запрос, введите обратную косую черту \ перед переводом строки. После нажатия Enter вам будет предложено ввести следующую строку запроса. Чтобы выполнить запрос, завершите его точкой с запятой и нажмите Enter.

ClickHouse Client основан на replxx (аналог readline), поэтому он использует знакомые сочетания клавиш и ведёт историю. История по умолчанию записывается в ~/.clickhouse-client-history.

Чтобы выйти из клиента, нажмите Ctrl+D или введите одну из следующих команд вместо запроса:

• exit или exit;
• quit или quit;
• q, Q или :q
• logout или logout;

Информация об обработке запроса

Во время обработки запроса клиент показывает:

1. Прогресс выполнения, который по умолчанию обновляется не чаще 10 раз в секунду. Для быстрых запросов прогресс может не успеть отобразиться.
2. Отформатированный запрос после разбора, для отладки.
3. Результат в указанном формате.
4. Количество строк в результате, прошедшее время и среднюю скорость обработки запроса. Все объёмы относятся к несжатым данным.

Вы можете отменить длительный запрос, нажав Ctrl+C. Однако вам всё равно придётся немного подождать, пока сервер прервёт запрос. На некоторых этапах отменить запрос невозможно. Если вы не будете ждать и нажмёте Ctrl+C во второй раз, клиент завершит работу.

ClickHouse Client позволяет передавать внешние данные (внешние временные таблицы) для выполнения запросов. Дополнительные сведения см. в разделе Внешние данные для обработки запросов.

Псевдонимы

В интерактивной оболочке (REPL) можно использовать следующие псевдонимы:

• \l — SHOW DATABASES
• \d — SHOW TABLES
• \c <DATABASE> — USE DATABASE
• . — повторить последний запрос

Сочетания клавиш

• Alt (Option) + Shift + e — открыть редактор с текущим запросом. Можно указать редактор с помощью переменной окружения EDITOR. По умолчанию используется vim.
• Alt (Option) + # — закомментировать строку.
• Ctrl + r — нечеткий поиск по истории.

Полный список всех доступных сочетаний клавиш приведён в replxx.

Совет

Чтобы настроить корректную работу клавиши Meta (Option) в macOS:

iTerm2: перейдите в Preferences -> Profiles -> Keys -> Left Option key и нажмите Esc+

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

Использование пакетного режима

Вместо интерактивного использования ClickHouse Client вы можете запускать его в пакетном режиме. В пакетном режиме ClickHouse выполняет один запрос и сразу завершается — без интерактивного приглашения или цикла.

Вы можете задать один запрос следующим образом:

$ clickhouse-client "SELECT sum(number) FROM numbers(10)"
45

Вы также можете использовать параметр командной строки --query:

$ clickhouse-client --query "SELECT uniq(number) FROM numbers(10)"
10

Вы можете передать запрос в stdin:

$ echo "SELECT avg(number) FROM numbers(10)" | clickhouse-client
4.5

Если таблица messages уже существует, вы также можете вставлять данные из командной строки:

$ echo "Hello\nGoodbye" | clickhouse-client --query "INSERT INTO messages FORMAT CSV"

Когда указана опция --query, любой ввод данных добавляется к запросу после символа перевода строки.

Загрузка CSV-файла в удалённый сервис ClickHouse

В этом примере демонстрируется загрузка примерного набора данных из CSV-файла cell_towers.csv в существующую таблицу cell_towers в базе данных default:

clickhouse-client --host HOSTNAME.clickhouse.cloud \
  --port 9440 \
  --user default \
  --password PASSWORD \
  --query "INSERT INTO cell_towers FORMAT CSVWithNames" \
  < cell_towers.csv

Примеры вставки данных из командной строки

Существует несколько способов вставить данные из командной строки. Следующий пример вставляет две строки данных в формате CSV в таблицу ClickHouse в пакетном режиме:

echo -ne "1, 'some text', '2016-08-14 00:00:00'\n2, 'some more text', '2016-08-14 00:00:01'" | \
  clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

В приведённом ниже примере cat <<_EOF открывает here-документ, который будет считывать всё до тех пор, пока снова не встретит _EOF, после чего выведет это:

cat <<_EOF | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";
3, 'some text', '2016-08-14 00:00:00'
4, 'some more text', '2016-08-14 00:00:01'
_EOF

В примере ниже содержимое файла file.csv выводится на стандартный вывод (stdout) с помощью команды cat и через конвейер (pipe) передаётся в clickhouse-client как входные данные:

cat file.csv | clickhouse-client --database=test --query="INSERT INTO test FORMAT CSV";

В пакетном режиме формат данных по умолчанию — TabSeparated (см. форматы). Вы можете указать формат в предложении FORMAT запроса, как показано в примере выше.

Запросы с параметрами

Вы можете указать параметры в запросе и передать им значения с помощью опций командной строки. Это позволяет избежать необходимости формировать запрос с конкретными динамическими значениями на стороне клиента. Например:

$ clickhouse-client --param_parName="[1, 2]" --query "SELECT {parName: Array(UInt16)}"
[1,2]

Параметры можно задавать и из интерактивного сеанса:

$ clickhouse-client
Клиент ClickHouse версии 25.X.X.XXX (официальная сборка).

#highlight-next-line
:) SET param_parName='[1, 2]';

SET param_parName = '[1, 2]'

Query id: 7ac1f84e-e89a-4eeb-a4bb-d24b8f9fd977

ОК.

0 строк в наборе. Прошло: 0.000 сек.

#highlight-next-line
:) SELECT {parName:Array(UInt16)}

SELECT {parName:Array(UInt16)}

Query id: 0358a729-7bbe-4191-bb48-29b063c548a7

   ┌─_CAST([1, 2]⋯y(UInt16)')─┐
1. │ [1,2]                    │
   └──────────────────────────┘

1 строка в наборе. Прошло: 0.006 сек.

Синтаксис запроса

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

{<name>:<data type>}

Parameter	Description
name	Идентификатор подстановочного параметра. Соответствующая опция командной строки — --param_<name> = value.
data type	Тип данных параметра. Например, структура данных вида (integer, ('string', integer)) может иметь тип данных Tuple(UInt8, Tuple(String, UInt8)) (можно также использовать другие целочисленные типы). Также можно передавать в качестве параметров имя таблицы, имя базы данных и имена столбцов; в этом случае следует использовать тип данных Identifier.

Примеры

$ clickhouse-client --param_tuple_in_tuple="(10, ('dt', 10))" \
    --query "SELECT * FROM table WHERE val = {tuple_in_tuple:Tuple(UInt8, Tuple(String, UInt8))}"

$ clickhouse-client --param_tbl="numbers" --param_db="system" --param_col="number" --param_alias="top_ten" \
    --query "SELECT {col:Identifier} as {alias:Identifier} FROM {db:Identifier}.{tbl:Identifier} LIMIT 10"

Генерация SQL с помощью ИИ

ClickHouse Client включает встроенную поддержку ИИ для генерации SQL-запросов по описаниям на естественном языке. Эта функция помогает пользователям составлять сложные запросы без глубоких знаний SQL.

Помощь ИИ работает «из коробки», если у вас задана переменная среды OPENAI_API_KEY или ANTHROPIC_API_KEY. Для более продвинутой настройки см. раздел Конфигурация.

Использование

Чтобы использовать генерацию SQL с ИИ, добавьте префикс ?? к запросу на естественном языке:

:) ?? показать всех пользователей, совершивших покупки за последние 30 дней

ИИ будет:

1. Автоматически анализировать структуру вашей базы данных
2. Генерировать соответствующий SQL‑запрос на основе обнаруженных таблиц и столбцов
3. Сразу выполнять сгенерированный запрос

Пример

:) ?? подсчитать заказы по категориям продуктов

Запуск генерации SQL с обнаружением схемы...
──────────────────────────────────────────────────

🔍 list_databases
   ➜ system, default, sales_db

🔍 list_tables_in_database
   database: sales_db
   ➜ orders, products, categories

🔍 get_schema_for_table
   database: sales_db
   table: orders
   ➜ CREATE TABLE orders (order_id UInt64, product_id UInt64, quantity UInt32, ...)

✨ SQL-запрос успешно сгенерирован!
──────────────────────────────────────────────────

SELECT 
    c.name AS category,
    COUNT(DISTINCT o.order_id) AS order_count
FROM sales_db.orders o
JOIN sales_db.products p ON o.product_id = p.product_id
JOIN sales_db.categories c ON p.category_id = c.category_id
GROUP BY c.name
ORDER BY order_count DESC

Конфигурация

Для генерации SQL-запросов с помощью ИИ необходимо настроить поставщика ИИ в конфигурационном файле клиента ClickHouse. Вы можете использовать OpenAI, Anthropic или любой совместимый с OpenAI API-сервис.

Резервный механизм на основе переменных окружения

Если конфигурация ИИ не указана в конфигурационном файле, ClickHouse Client автоматически попытается использовать переменные окружения:

1. Сначала проверяется переменная окружения OPENAI_API_KEY
2. Если она не найдена, проверяется переменная окружения ANTHROPIC_API_KEY
3. Если ни одна из них не найдена, функции ИИ будут отключены

Это позволяет быстро выполнить настройку без конфигурационных файлов:

# Использование OpenAI \{#using-openai}
export OPENAI_API_KEY=your-openai-key
clickhouse-client

# Использование Anthropic \{#using-anthropic}
export ANTHROPIC_API_KEY=your-anthropic-key
clickhouse-client

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

Для более тонкого управления настройками ИИ задайте их в файле конфигурации ClickHouse Client, который находится по одному из следующих путей:

• $XDG_CONFIG_HOME/clickhouse/config.xml (или ~/.config/clickhouse/config.xml, если XDG_CONFIG_HOME не задан) (формат XML)
• $XDG_CONFIG_HOME/clickhouse/config.yaml (или ~/.config/clickhouse/config.yaml, если XDG_CONFIG_HOME не задан) (формат YAML)
• ~/.clickhouse-client/config.xml (формат XML, устаревший путь)
• ~/.clickhouse-client/config.yaml (формат YAML, устаревший путь)
• Или укажите произвольный путь с помощью --config-file

XML

<config>
    <ai>
        <!-- Обязательно: ваш API-ключ (или задайте через переменную окружения) -->
        <api_key>your-api-key-here</api_key>

        <!-- Обязательно: тип провайдера (openai, anthropic) -->
        <provider>openai</provider>

        <!-- Используемая модель (значения по умолчанию зависят от провайдера) -->
        <model>gpt-4o</model>

        <!-- Необязательно: пользовательская конечная точка API для сервисов, совместимых с OpenAI -->
        <!-- <base_url>https://openrouter.ai/api</base_url> -->

        <!-- Настройки исследования схемы -->
        <enable_schema_access>true</enable_schema_access>

        <!-- Параметры генерации -->
        <temperature>0.0</temperature>
        <max_tokens>1000</max_tokens>
        <timeout_seconds>30</timeout_seconds>
        <max_steps>10</max_steps>

        <!-- Необязательно: пользовательский системный промпт -->
        <!-- <system_prompt>You are an expert ClickHouse SQL assistant...</system_prompt> -->
    </ai>
</config>

YAML

ai:
  # Обязательно: ваш API-ключ (или задайте через переменную окружения)
  api_key: your-api-key-here

  # Обязательно: тип провайдера (openai, anthropic)
  provider: openai

  # Используемая модель
  model: gpt-4o

  # Необязательно: пользовательская конечная точка API для сервисов, совместимых с OpenAI
  # base_url: https://openrouter.ai/api

  # Включить доступ к схеме — позволяет ИИ запрашивать информацию о базах данных и таблицах
  enable_schema_access: true

  # Параметры генерации
  temperature: 0.0      # Управляет степенью случайности (0.0 = детерминированно)
  max_tokens: 1000      # Максимальная длина ответа
  timeout_seconds: 30   # Тайм-аут запроса
  max_steps: 10         # Максимальное количество шагов исследования схемы

  # Необязательно: пользовательский системный промпт
  # system_prompt: |
  #   You are an expert ClickHouse SQL assistant. Convert natural language to SQL.
  #   Focus on performance and use ClickHouse-specific optimizations.
  #   Always return executable SQL without explanations.

Использование API, совместимых с OpenAI (например, OpenRouter):

ai:
  provider: openai  # Используйте 'openai' для обеспечения совместимости
  api_key: your-openrouter-api-key
  base_url: https://openrouter.ai/api/v1
  model: anthropic/claude-3.5-sonnet  # Используйте схему именования моделей OpenRouter

Примеры минимальных конфигураций:

# Минимальная конфигурация — использует переменную окружения для API-ключа \{#minimal-config-uses-environment-variable-for-api-key}
ai:
  provider: openai  # Будет использована переменная окружения OPENAI_API_KEY

# Без конфигурации — автоматический резервный вариант \{#no-config-at-all-automatic-fallback}
# (Пустая или отсутствующая секция ai — будет использована OPENAI_API_KEY, затем ANTHROPIC_API_KEY) \{#empty-or-no-ai-section-will-try-openai_api_key-then-anthropic_api_key}

# Переопределение только модели — использует переменную окружения для API-ключа \{#only-override-model-uses-env-var-for-api-key}
ai:
  provider: openai
  model: gpt-3.5-turbo

Параметры

Обязательные параметры

• api_key - Ваш API-ключ для сервиса ИИ. Можно не указывать, если он задан через переменную окружения:
  • OpenAI: OPENAI_API_KEY
  • Anthropic: ANTHROPIC_API_KEY
  • Примечание: API-ключ в конфигурационном файле имеет приоритет над переменной окружения
• provider - Провайдер ИИ: openai или anthropic
  • Если не указан, используется автоматический выбор на основе доступных переменных окружения

Конфигурация модели

• model - Используемая модель (по умолчанию: провайдер-зависимая)
  • OpenAI: gpt-4o, gpt-4, gpt-3.5-turbo и т.д.
  • Anthropic: claude-3-5-sonnet-20241022, claude-3-opus-20240229 и т.д.
  • OpenRouter: используйте их схему наименования моделей, например anthropic/claude-3.5-sonnet

Настройки подключения

• base_url - Пользовательский API-эндпоинт для сервисов, совместимых с OpenAI (необязательно)
• timeout_seconds - Тайм-аут запроса в секундах (по умолчанию: 30)

Исследование схемы

• enable_schema_access - Разрешить ИИ исследовать схемы баз данных (по умолчанию: true)
• max_steps - Максимальное число шагов вызова инструментов для исследования схемы (по умолчанию: 10)

Параметры генерации

• temperature - Контролирует степень случайности: 0.0 = детерминированно, 1.0 = более творчески (по умолчанию: 0.0)
• max_tokens - Максимальная длина ответа в токенах (по умолчанию: 1000)
• system_prompt - Пользовательские инструкции для ИИ (необязательно)

Как это работает

AI-генератор SQL использует многошаговый процесс:

Анализ схемы

AI использует встроенные инструменты для исследования вашей базы данных

• Составляет список доступных баз данных
• Обнаруживает таблицы в соответствующих базах данных
• Изучает структуры таблиц с помощью операторов CREATE TABLE

Генерация запроса

На основе обнаруженной схемы AI генерирует SQL, который:

• Соответствует вашему запросу на естественном языке
• Использует корректные имена таблиц и столбцов
• Применяет подходящие соединения и агрегации

Выполнение

Сгенерированный SQL автоматически выполняется, и результаты отображаются

Ограничения

• Требуется активное подключение к Интернету
• Использование API подчиняется ограничениям по частоте и стоимости со стороны поставщика ИИ
• Сложные запросы могут потребовать нескольких уточнений
• ИИ имеет доступ только для чтения к информации о схеме, но не к самим данным

Безопасность

• API-ключи никогда не передаются на серверы ClickHouse
• ИИ видит только информацию о схеме (имена таблиц/столбцов и их типы), но не реальные данные
• Все сгенерированные запросы учитывают ваши текущие права доступа к базе данных

Строка подключения

Использование

ClickHouse Client также поддерживает альтернативный способ подключения к серверу ClickHouse — с помощью строки подключения, аналогичной MongoDB, PostgreSQL, MySQL. Строка подключения имеет следующий синтаксис:

clickhouse:[//[user[:password]@][hosts_and_ports]][/database][?query_parameters]

Компонент (все необязательные)	Описание	Значение по умолчанию
user	Имя пользователя базы данных.	default
password	Пароль пользователя базы данных. Если указан символ : и пароль не задан, клиент запросит пароль у пользователя.	-
hosts_and_ports	Список хостов и необязательных портов host[:port] [, host:[port]], ....	localhost:9000
database	Имя базы данных.	default
query_parameters	Список пар «ключ–значение» param1=value1[,&param2=value2], .... Для некоторых параметров значение не требуется. Имена параметров и значений чувствительны к регистру.	-

Примечания

Если имя пользователя, пароль или база данных указаны в строке подключения, их нельзя указывать с помощью --user, --password или --database (и наоборот).

Компонент host может быть либо именем хоста, либо адресом IPv4 или IPv6. Адреса IPv6 должны указываться в квадратных скобках:

clickhouse://[2001:db8::1234]

Строки подключения могут содержать несколько хостов. ClickHouse Client будет пытаться подключиться к этим хостам по порядку (слева направо). После установления соединения попытки подключиться к оставшимся хостам не выполняются.

Строка подключения должна быть указана как первый аргумент clickHouse-client. Строку подключения можно комбинировать с произвольным количеством других параметров командной строки, за исключением --host и --port.

Для query_parameters поддерживаются следующие ключи:

Ключ	Описание
secure (или s)	Если указан, клиент будет подключаться к серверу по защищённому соединению (TLS). См. --secure в параметрах командной строки.

Процентное кодирование

Символы, отличные от US-ASCII, пробелы и специальные символы в следующих параметрах должны быть закодированы с использованием процентного кодирования:

• user
• password
• hosts
• database
• query parameters

Примеры

Подключитесь к localhost через порт 9000 и выполните запрос SELECT 1.

clickhouse-client clickhouse://localhost:9000 --query "SELECT 1"

Подключитесь к localhost под пользователем john с паролем secret, используя хост 127.0.0.1 и порт 9000

clickhouse-client clickhouse://john:secret@127.0.0.1:9000

Подключитесь к localhost под пользователем default (хост с IPv6-адресом [::1], портом 9000).

clickhouse-client clickhouse://[::1]:9000

Подключитесь к localhost на порту 9000 в многострочном режиме.

clickhouse-client clickhouse://localhost:9000 '-m'

Подключитесь к localhost на порту 9000 от имени пользователя default.

clickhouse-client clickhouse://default@localhost:9000

# эквивалентно: \{#equivalent-to}
clickhouse-client clickhouse://localhost:9000 --user default

Подключитесь к localhost на порту 9000 и используйте в качестве базы данных по умолчанию my_database.

clickhouse-client clickhouse://localhost:9000/my_database

# эквивалентно: \{#equivalent-to}
clickhouse-client clickhouse://localhost:9000 --database my_database

Подключитесь к localhost на порту 9000, по умолчанию используя базу данных my_database, указанную в строке подключения, и защищённое соединение с помощью сокращённого параметра s.

clickhouse-client clickhouse://localhost/my_database?s

# эквивалентно: \{#equivalent-to}
clickhouse-client clickhouse://localhost/my_database -s

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

clickhouse-client clickhouse:

Подключитесь к хосту по умолчанию, используя порт по умолчанию, под пользователем my_user и без пароля.

clickhouse-client clickhouse://my_user@

# Пустой пароль между : и @ означает, что пользователю будет предложено ввести пароль перед установкой соединения. \{#using-a-blank-password-between-and-means-to-asking-the-user-to-enter-the-password-before-starting-the-connection}
clickhouse-client clickhouse://my_user:@

Подключитесь к localhost, используя адрес электронной почты в качестве имени пользователя. Символ @ кодируется в %40.

clickhouse-client clickhouse://some_user%40some_mail.com@localhost:9000

Подключитесь к одному из следующих хостов: 192.168.1.15, 192.168.1.25.

clickhouse-client clickhouse://192.168.1.15,192.168.1.25

Формат ID запроса

В интерактивном режиме ClickHouse Client показывает ID для каждого запроса. По умолчанию ID имеет следующий формат:

ID запроса: 927f137d-00f1-4175-8914-0dd066365e96

Пользовательский формат можно задать в конфигурационном файле внутри тега query_id_formats. Заполнитель {query_id} в строке формата заменяется на идентификатор запроса. Внутри тега можно указать несколько строк формата. Эту возможность можно использовать для генерации URL-адресов, чтобы упростить профилирование запросов.

Пример

<config>
  <query_id_formats>
    <speedscope>http://speedscope-host/#profileURL=qp%3Fid%3D{query_id}</speedscope>
  </query_id_formats>
</config>

При указанной выше конфигурации идентификатор запроса отображается в следующем формате:

speedscope:http://speedscope-host/#profileURL=qp%3Fid%3Dc8ecc783-e753-4b38-97f1-42cddfb98b7d

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

ClickHouse Client использует первый найденный файл из следующего списка:

• Файл, заданный параметром -c [ -C, --config, --config-file ].
• ./clickhouse-client.[xml|yaml|yml]
• $XDG_CONFIG_HOME/clickhouse/config.[xml|yaml|yml] (или ~/.config/clickhouse/config.[xml|yaml|yml], если переменная окружения XDG_CONFIG_HOME не установлена)
• ~/.clickhouse-client/config.[xml|yaml|yml]
• /etc/clickhouse-client/config.[xml|yaml|yml]

См. пример файла конфигурации в репозитории ClickHouse: clickhouse-client.xml

XML

<config>
    <user>username</user>
    <password>password</password>
    <secure>true</secure>
    <openSSL>
      <client>
        <caConfig>/etc/ssl/cert.pem</caConfig>
      </client>
    </openSSL>
</config>

YAML

user: username
password: 'password'
secure: true
openSSL:
  client:
    caConfig: '/etc/ssl/cert.pem'

Параметры переменных окружения

Имя пользователя, пароль и хост могут быть заданы через переменные окружения CLICKHOUSE_USER, CLICKHOUSE_PASSWORD и CLICKHOUSE_HOST. Аргументы командной строки --user, --password или --host, а также строка подключения (если указана) имеют приоритет над переменными окружения.

Параметры командной строки

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

Общие параметры

Параметр	Описание	Значение по умолчанию
-c [ -C, --config, --config-file ] <path-to-file>	Путь к конфигурационному файлу клиента, если он не находится в одном из стандартных расположений. См. Configuration Files.	-
--help	Вывести краткую справку по использованию и завершить работу. Используйте совместно с --verbose, чтобы отобразить все возможные параметры, включая настройки запроса.	-
--history_file <path-to-file>	Путь к файлу, содержащему историю команд.	-
--history_max_entries	Максимальное количество записей в файле истории.	1000000 (1 миллион)
--prompt <prompt>	Указать пользовательскую строку приглашения.	display_name сервера
--verbose	Увеличить детализацию вывода.	-
-V [ --version ]	Вывести версию и завершить работу.	-

Параметры подключения

Параметр	Описание	Значение по умолчанию
--connection <name>	Имя предварительно настроенных параметров подключения из конфигурационного файла. См. Учетные данные подключения.	-
-d [ --database ] <database>	База данных, используемая по умолчанию для этого подключения.	Текущая база данных из настроек сервера (по умолчанию default)
-h [ --host ] <host>	Имя хоста сервера ClickHouse, к которому выполняется подключение. Может быть именем хоста или IPv4/IPv6-адресом. Можно передать несколько хостов, указав параметр несколько раз.	localhost
--jwt <value>	Использовать JSON Web Token (JWT) для аутентификации. Авторизация JWT на стороне сервера доступна только в ClickHouse Cloud.	-
--no-warnings	Отключить показ предупреждений из system.warnings при подключении клиента к серверу.	-
--no-server-client-version-message	Скрывать сообщение о несовпадении версий сервера и клиента при подключении клиента к серверу.	-
--password <password>	Пароль пользователя базы данных. Пароль для подключения также можно указать в конфигурационном файле. Если пароль не указан, клиент запросит его интерактивно.	-
--port <port>	Порт, на котором сервер принимает подключения. Порты по умолчанию: 9440 (TLS) и 9000 (без TLS). Примечание: клиент использует нативный протокол, а не HTTP(S).	9440, если указан --secure, иначе 9000. Всегда по умолчанию 9440, если имя хоста оканчивается на .clickhouse.cloud.
-s [ --secure ]	Использовать ли TLS. Включается автоматически при подключении к порту 9440 (безопасный порт по умолчанию) или к ClickHouse Cloud. Вам может потребоваться настроить ваши CA-сертификаты в конфигурационном файле. Доступные параметры конфигурации такие же, как для настройки TLS на стороне сервера.	Автоматически включается при подключении к порту 9440 или ClickHouse Cloud
--ssh-key-file <path-to-file>	Файл, содержащий приватный SSH-ключ для аутентификации на сервере.	-
--ssh-key-passphrase <value>	Парольная фраза для приватного SSH-ключа, указанного в --ssh-key-file.	-
-u [ --user ] <username>	Пользователь базы данных, от имени которого выполняется подключение.	default

Примечание

Вместо параметров --host, --port, --user и --password клиент также поддерживает строки подключения.

Параметры запросов

Опция	Описание
--param_<name>=<value>	Значение подстановки для параметра запроса с параметрами.
-q [ --query ] <query>	Запрос для выполнения в пакетном режиме. Может быть указан несколько раз (--query "SELECT 1" --query "SELECT 2") или один раз с несколькими запросами, разделёнными точкой с запятой (--query "SELECT 1; SELECT 2;"). В последнем случае INSERT‑запросы с форматами, отличными от VALUES, должны быть разделены пустыми строками. Один запрос также можно передать без параметра --query: clickhouse-client "SELECT 1" Нельзя использовать вместе с --queries-file.
--queries-file <path-to-file>	Путь к файлу, содержащему запросы. --queries-file может быть указан несколько раз, например: --queries-file queries1.sql --queries-file queries2.sql. Нельзя использовать вместе с --query.
-m [ --multiline ]	Если указана опция, разрешает многострочные запросы (запрос не отправляется при нажатии Enter). Запросы будут отправляться только когда они заканчиваются точкой с запятой.

Настройки запроса

Настройки запроса можно задать в клиенте как параметры командной строки, например:

$ clickhouse-client --max_threads 1

Список настроек см. в разделе Settings.

Параметры форматирования

Параметр	Описание	По умолчанию
-f [ --format ] <format>	Использовать указанный формат для вывода результата. Список поддерживаемых форматов см. в разделе Форматы входных и выходных данных.	TabSeparated
--pager <command>	Передавать весь вывод этой команде через конвейер. Обычно используется less (например, less -S для отображения широких результирующих наборов) или аналогичная программа.	-
-E [ --vertical ]	Использовать формат Vertical для вывода результата. То же самое, что и --format Vertical. В этом формате каждое значение выводится на отдельной строке, что удобно при отображении широких таблиц.	-

Подробности выполнения

Опция	Описание	Значение по умолчанию
--enable-progress-table-toggle	Включить переключение таблицы прогресса нажатием сочетания клавиш Ctrl+Space. Применимо только в интерактивном режиме при включённой печати таблицы прогресса.	enabled
--hardware-utilization	Выводить информацию об использовании аппаратных ресурсов в индикаторе прогресса.	-
--memory-usage	Если указано, выводить использование памяти в stderr в неинтерактивном режиме. Возможные значения: • none — не выводить использование памяти • default — выводить количество байт • readable — выводить использование памяти в удобочитаемом формате	-
--print-profile-events	Выводить пакеты ProfileEvents.	-
--progress	Выводить прогресс выполнения запроса. Возможные значения: • tty|on|1|true|yes — вывод в терминал в интерактивном режиме • err — вывод в stderr в неинтерактивном режиме • off|0|false|no — отключить вывод прогресса	tty в интерактивном режиме, off в неинтерактивном (пакетном) режиме
--progress-table	Выводить таблицу прогресса с изменяющимися метриками во время выполнения запроса. Возможные значения: • tty|on|1|true|yes — вывод в терминал в интерактивном режиме • err — вывод в stderr в неинтерактивном режиме • off|0|false|no — отключить таблицу прогресса	tty в интерактивном режиме, off в неинтерактивном (пакетном) режиме
--stacktrace	Выводить трассировки стека исключений.	-
-t [ --time ]	Выводить время выполнения запроса в stderr в неинтерактивном режиме (для бенчмарков).	-