clickhouse-client

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:

Кнопка подключения к сервису ClickHouse Cloud

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

Детали подключения к ClickHouse Cloud по протоколу Native TCP

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

Вы можете хранить параметры подключения для одного или нескольких серверов 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;

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

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

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

Вы можете отменить длительный запрос, нажав 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.

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 дней

ИИ будет:

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

Пример

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

Запуск генерации 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 автоматически попытается использовать переменные окружения:

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

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

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

# Использование 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
YAML

<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>

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-ключа
ai:
  provider: openai  # Будет использована переменная окружения OPENAI_API_KEY

# Без конфигурации — автоматический резервный вариант
# (Пустая или отсутствующая секция ai — будет использована OPENAI_API_KEY, затем ANTHROPIC_API_KEY)

# Переопределение только модели — использует переменную окружения для API-ключа
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:[email protected]: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

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

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

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

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

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

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

# эквивалентно:
clickhouse-client clickhouse://localhost/my_database -s

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

clickhouse-client clickhouse:

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

clickhouse-client clickhouse://my_user@

# Пустой пароль между : и @ означает, что пользователю будет предложено ввести пароль перед установкой соединения.
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
YAML

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

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` при подключении клиента к серверу.	-
`--password <password>`	Пароль пользователя базы данных. Вы также можете указать пароль для подключения в конфигурационном файле. Если вы не укажете пароль, клиент запросит его интерактивно.	-
`--port <port>`	Порт, на котором сервер принимает подключения. Порты по умолчанию: 9440 (TLS) и 9000 (без TLS). Примечание: клиент использует нативный протокол ClickHouse, а не 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` в неинтерактивном режиме (для бенчмарков).	-

Установка​

Запуск​

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

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

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

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

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

Псевдонимы​

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

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

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

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

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

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

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

Примеры​

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

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

Пример​

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

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

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

Параметры​

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

Ограничения​

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

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

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

Примечания​

Примеры​

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

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

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

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

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

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

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

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

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

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

Установка

Запуск

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

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

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

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

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

Псевдонимы

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

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

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

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

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

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

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

Примеры

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

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

Пример

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

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

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

Параметры

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

Ограничения

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

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

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

Примечания

Примеры

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

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

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

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

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

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

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

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

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

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