Клиент ClickHouse

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

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

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

curl https://clickhouse.com/ | sh

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

sudo ./clickhouse install

См. Установка ClickHouse, чтобы ознакомиться с другими вариантами установки.

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

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

$ clickhouse-client --host server

ClickHouse client version 24.12.2.29 (official build).
Connecting to server:9000 as user default.
Connected to ClickHouse server version 24.12.2.

:)

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

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

Сведения о вашем сервисе 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>

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

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

clickhouse-client

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

ClickHouse client version 25.x.x.x
Connecting to localhost:9000 as user default.
Connected to ClickHouse server version 25.x.x.x

hostname :)

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

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

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

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

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

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

Вы можете просмотреть документацию по любой функции, движку таблицы, типу данных, формату, настройке и другому компоненту системы, не выходя из клиента. Введите help, а затем имя (также работают эквивалентные формы /help, man и /man):

help domainWithoutWWW

Поиск регистронезависимый и выполняется по таблице system.documentation. Подходящая документация отображается в терминале из Markdown — с полужирным и курсивным текстом, таблицами и блоками кода с подсветкой синтаксиса. Если одно и то же имя используется несколькими компонентами (например, file, который является и функцией, и движком таблицы), показываются все варианты.

Если точных совпадений нет, client выводит список похожих имен (с учетом возможных опечаток), а также компонентов, в документации которых упоминается это слово:

help maxx_threads

Ввод команды help выводит краткую справку по использованию.

Клиент сам выполняет несколько команд с префиксом /, не отправляя их на сервер:

При вводе / в начале строки отображается список команд в виде подсказок, а по мере ввода имени этот список сужается; клавиша Tab дополняет вводимую команду и также используется для дополнения команд при отключённых подсказках. Отправленный отдельно / не является командой: как в Oracle SQL*Plus, он повторяет последний ввод. Если имя команды указано с ошибкой, вместо выполнения его как запроса будет показано сообщение об ошибке и список команд, которые могли иметься в виду:

:) /hepl

Exception on client:
Code: 36. DB::Exception: Unknown command `/hepl`. Maybe you meant: ['/help']. Type `/` at the beginning of the line to see all the commands. (BAD_ARGUMENTS)

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

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

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

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

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

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

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

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

Вместо интерактивной работы с клиентом ClickHouse его можно запускать в пакетном режиме. В пакетном режиме 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-файл с тестовым набором данных 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 начинает конструкцию heredoc, которая считывает всё до следующего появления _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, а затем через конвейер передаётся на вход 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 client version 25.X.X.XXX (official build).

:) SET param_parName='[1, 2]';

SET param_parName = '[1, 2]'

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

Ok.

0 rows in set. Elapsed: 0.000 sec.

:) SELECT {parName:Array(UInt16)}

SELECT {parName:Array(UInt16)}

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

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

1 row in set. Elapsed: 0.006 sec.

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

{<name>:<data type>}

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

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

ИИ-поддержка работает сразу после настройки переменной окружения OPENAI_API_KEY или ANTHROPIC_API_KEY. Более подробную информацию о расширенной настройке см. в разделе Configuration.

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

:) ?? show all users who made purchases in the last 30 days

ИИ будет:

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

:) ?? count orders by product category

Starting AI SQL generation with schema discovery...
──────────────────────────────────────────────────

🔍 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 query generated successfully!
──────────────────────────────────────────────────

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 или любой API-сервис с поддержкой совместимости с OpenAI.

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

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

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

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

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

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

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

<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` отправляется модели только если задан здесь.
             По умолчанию он не передаётся, потому что некоторые модели отклоняют этот параметр. */}
        {/* <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` отправляется модели только если задан здесь; по умолчанию не передаётся,
  # потому что некоторые модели отклоняют этот параметр.
  # temperature: 0.0    # Управляет случайностью (0.0 = детерминированный результат)
  max_tokens: 1000      # Максимальная длина ответа
  timeout_seconds: 30   # Тайм-аут запроса
  max_steps: 10         # Максимальное число шагов при исследовании схемы

  # Необязательно: пользовательский системный промпт
  # system_prompt: |
  #   Вы — экспертный помощник по ClickHouse SQL. Преобразуйте естественный язык в SQL.
  #   Сосредоточьтесь на производительности и используйте оптимизации, специфичные для ClickHouse.
  #   Всегда возвращайте исполняемый SQL без объяснений.

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

ai:
  provider: openai  # Use 'openai' for compatibility
  api_key: your-openrouter-api-key
  base_url: https://openrouter.ai/api/v1
  model: anthropic/claude-3.5-sonnet  # Use OpenRouter model naming

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

# Minimal config - uses environment variable for API key
ai:
  provider: openai  # Will use OPENAI_API_KEY env var

# No config at all - automatic fallback
# (Empty or no ai section - will try OPENAI_API_KEY then ANTHROPIC_API_KEY)

# Only override model - uses env var for API key
ai:
  provider: openai
  model: gpt-3.5-turbo

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

1. Определение схемы

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

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

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

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

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

3. Выполнение

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

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

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

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

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

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

Компонент хоста может быть как именем хоста, так и адресом IPv4 или IPv6. Адреса IPv6 должны быть заключены в []:

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

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

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

Для query_parameters допустимы следующие ключи:

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

Символы вне 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

# эквивалентно:
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

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

Query 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 использует первый найденный из следующих файлов:

• Файл, указанный параметром -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

<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, а также строка подключения (если она указана), имеют приоритет над переменными окружения.

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

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

$ clickhouse-client --max_threads 1

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