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

ClickHouse позволяет отправлять на сервер данные, которые необходимы для обработки запроса, вместе с запросом SELECT. Эти данные помещаются во временную таблицу (см. раздел «Временные таблицы») и могут использоваться в запросе (например, в операторах IN).

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

Если вам нужно выполнить более одного запроса с большим объёмом внешних данных, не используйте эту возможность. Лучше заранее загрузить данные в БД.

Внешние данные могут быть загружены с помощью клиента командной строки (в неинтерактивном режиме) или с использованием HTTP-интерфейса.

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

--external --file=... [--name=...] [--format=...] [--types=...|--structure=...]

У вас может быть несколько таких секций — по числу передаваемых таблиц.

–external – Обозначает начало секции. –file – Путь к файлу с дампом таблицы или -, что означает stdin. Из stdin может быть получена только одна таблица.

Следующие параметры являются необязательными: –name – Имя таблицы. Если параметр не указан, используется _data. –format – Формат данных в файле. Если параметр не указан, используется TabSeparated.

Один из следующих параметров является обязательным: –types – Список типов столбцов, разделённых запятыми. Например: UInt64,String. Столбцы будут иметь имена _1, _2, ... –structure – Структура таблицы в формате UserID UInt64, URL String. Определяет имена и типы столбцов.

Файлы, указанные в параметре 'file', будут разобраны с использованием формата, указанного в 'format', и типов данных, указанных в 'types' или 'structure'. Таблица будет загружена на сервер и доступна там как временная таблица с именем из параметра 'name'.

Примеры:

$ echo -ne "1\n2\n3\n" | clickhouse-client --query="SELECT count() FROM test.visits WHERE TraficSourceID IN _data" --external --file=- --types=Int8
849897
$ cat /etc/passwd | sed 's/:/\t/g' | clickhouse-client --query="SELECT shell, count() AS c FROM passwd GROUP BY shell ORDER BY c DESC" --external --file=- --name=passwd --structure='login String, unused String, uid UInt16, gid UInt16, comment String, home String, shell String'
/bin/sh 20
/bin/false      5
/bin/bash       4
/usr/sbin/nologin       1
/bin/sync       1

При использовании HTTP-интерфейса внешние данные передаются в формате multipart/form-data. Каждая таблица передаётся как отдельный файл. Имя таблицы берётся из имени файла. В query_string передаются параметры name_format, name_types и name_structure, где name — это имя таблицы, к которой относятся эти параметры. Значения параметров такие же, как при использовании клиентской программы командной строки.

Пример:

$ cat /etc/passwd | sed 's/:/\t/g' > passwd.tsv

$ curl -F '[email protected];' 'http://localhost:8123/?query=SELECT+shell,+count()+AS+c+FROM+passwd+GROUP+BY+shell+ORDER+BY+c+DESC&passwd_structure=login+String,+unused+String,+uid+UInt16,+gid+UInt16,+comment+String,+home+String,+shell+String'
/bin/sh 20
/bin/false      5
/bin/bash       4
/usr/sbin/nologin       1
/bin/sync       1

Для распределённой обработки запросов временные таблицы отправляются на все удалённые серверы.