Форматы ввода и вывода данных

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

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

Форматы ввода используются для:

Разбора данных, передаваемых в операторы INSERT
Выполнения запросов SELECT к таблицам с файловой поддержкой, таким как File, URL или HDFS
Чтения словарей

Выбор подходящего формата ввода имеет решающее значение для эффективной ингестии данных в ClickHouse. При наличии более 70 поддерживаемых форматов выбор наиболее производительного варианта может существенно повлиять на скорость вставки, использование CPU и памяти, а также общую эффективность системы. Чтобы упростить этот выбор, мы провели бенчмарк производительности ингестии для разных форматов и выделили ключевые выводы:

Формат Native — самый эффективный формат ввода, он обеспечивает лучшее сжатие, минимальное потребление ресурсов и минимальные накладные расходы на обработку на стороне сервера.
Сжатие крайне важно — LZ4 уменьшает размер данных при минимальных затратах CPU, тогда как ZSTD обеспечивает более высокую степень сжатия ценой дополнительной нагрузки на CPU.
Предварительная сортировка влияет умеренно, поскольку ClickHouse и без того сортирует эффективно.
Формирование батчей значительно повышает эффективность — более крупные батчи уменьшают накладные расходы на вставку и повышают пропускную способность.

Чтобы подробнее ознакомиться с результатами и рекомендуемыми практиками, прочитайте полный анализ бенчмарка. Полные результаты тестов доступны на онлайн-панели мониторинга FastFormats.

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

Поддерживаемые форматы вывода используются для:

Представления результатов запроса SELECT
Выполнения операций INSERT в таблицы с файловой поддержкой

Обзор форматов

Поддерживаемые форматы:

Формат	Вход	Выход
TabSeparated	✔	✔
TabSeparatedRaw	✔	✔
TabSeparatedWithNames	✔	✔
TabSeparatedWithNamesAndTypes	✔	✔
TabSeparatedRawWithNames	✔	✔
TabSeparatedRawWithNamesAndTypes	✔	✔
Template	✔	✔
TemplateIgnoreSpaces	✔	✗
CSV	✔	✔
CSVWithNames	✔	✔
CSVWithNamesAndTypes	✔	✔
CustomSeparated	✔	✔
CustomSeparatedIgnoreSpaces	✔	✗
CustomSeparatedIgnoreSpacesWithNames	✔	✗
CustomSeparatedIgnoreSpacesWithNamesAndTypes	✔	✗
CustomSeparatedWithNames	✔	✔
CustomSeparatedWithNamesAndTypes	✔	✔
HiveText	✔	✔
SQLInsert	✗	✔
Values	✔	✔
Vertical	✗	✔
JSON	✔	✔
JSONAsString	✔	✗
JSONAsObject	✔	✗
JSONStrings	✗	✔
JSONColumns	✔	✔
JSONColumnsWithMetadata	✔	✔
JSONCompact	✔	✔
JSONCompactStrings	✗	✔
JSONCompactColumns	✔	✔
JSONEachRow	✔	✔
JSONLines	✔	✔
PrettyJSONEachRow	✗	✔
JSONEachRowWithProgress	✗	✔
JSONStringsEachRow	✔	✔
JSONStringsEachRowWithProgress	✗	✔
JSONCompactEachRow	✔	✔
JSONCompactEachRowWithNames	✔	✔
JSONCompactEachRowWithNamesAndTypes	✔	✔
JSONCompactEachRowWithProgress	✗	✔
JSONCompactStringsEachRow	✔	✔
JSONCompactStringsEachRowWithNames	✔	✔
JSONCompactStringsEachRowWithNamesAndTypes	✔	✔
JSONCompactStringsEachRowWithProgress	✗	✔
JSONObjectEachRow	✔	✔
BSONEachRow	✔	✔
TSKV	✔	✔
Pretty	✗	✔
PrettyNoEscapes	✗	✔
PrettyMonoBlock	✗	✔
PrettyNoEscapesMonoBlock	✗	✔
PrettyCompact	✗	✔
PrettyCompactNoEscapes	✗	✔
PrettyCompactMonoBlock	✗	✔
PrettyCompactNoEscapesMonoBlock	✗	✔
PrettySpace	✗	✔
PrettySpaceNoEscapes	✗	✔
PrettySpaceMonoBlock	✗	✔
PrettySpaceNoEscapesMonoBlock	✗	✔
Prometheus	✗	✔
Protobuf	✔	✔
ProtobufSingle	✔	✔
ProtobufList	✔	✔
Avro	✔	✔
AvroConfluent	✔	✔
Parquet	✔	✔
ParquetMetadata	✔	✗
Arrow	✔	✔
ArrowStream	✔	✔
ORC	✔	✔
One	✔	✗
Npy	✔	✔
RowBinary	✔	✔
RowBinaryWithNames	✔	✔
RowBinaryWithNamesAndTypes	✔	✔
RowBinaryWithDefaults	✔	✗
RowBinaryWithNamesAndTypesAndDefaults	✔	✗
Native	✔	✔
Buffers	✔	✔
Null	✗	✔
Hash	✗	✔
XML	✗	✔
CapnProto	✔	✔
LineAsString	✔	✔
LineAsStringWithNames	✗	✔
LineAsStringWithNamesAndTypes	✗	✔
Regexp	✔	✗
RawBLOB	✔	✔
MsgPack	✔	✔
MySQLDump	✔	✗
MySQLWire	✗	✔
PostgreSQLWire	✗	✔
ODBCDriver2	✗	✔
GeoJSON	✔	✔
DWARF	✔	✗
Markdown	✗	✔
Form	✔	✗

Некоторыми параметрами обработки форматов можно управлять с помощью настроек ClickHouse. Подробнее см. раздел Настройки.

Дополнительные настройки для JSON описаны на странице Настройки формата JSON.

Схема формата

Имя файла, содержащего схему формата, задаётся настройкой format_schema. Эту настройку необходимо указать при использовании форматов Cap'n Proto и Protobuf. Схема формата представляет собой сочетание имени файла и имени типа сообщения в этом файле, разделённых двоеточием, например, schemafile.proto:MessageType. Если файл имеет стандартное для данного формата расширение (например, .proto для Protobuf), его можно опустить, и в этом случае схема формата будет выглядеть так: schemafile:MessageType.

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

Если вы вводите или выводите данные через HTTP-интерфейс, имя файла, указанное в схеме формата, должно находиться в каталоге, указанном в format_schema_path в конфигурации сервера.

Пропуск ошибок

Некоторые форматы, такие как CSV, TabSeparated, TSKV, JSONEachRow, Template, CustomSeparated и Protobuf, могут пропускать некорректную строку, если возникает ошибка разбора, и продолжать разбор с начала следующей строки. См. настройки input_format_allow_errors_num и input_format_allow_errors_ratio. Ограничения:

При ошибке разбора JSONEachRow пропускает все данные до символа новой строки (или EOF), поэтому для корректного подсчета ошибок строки должны разделяться символом \n.
Template и CustomSeparated используют разделитель после последнего столбца и разделитель между строками, чтобы находить начало следующей строки, поэтому пропуск ошибок работает только в том случае, если хотя бы один из них не пуст.