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

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

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

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

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

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

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

Для детального разбора результатов и рекомендаций по лучшим практикам ознакомьтесь с полной аналитикой бенчмарка. Все результаты тестов доступны в онлайн-дашборде FastFormats.

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

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

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

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

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

Формат	Ввод	Вывод
TabSeparated	✔	✔
TabSeparatedRaw	✔	✔
TabSeparatedWithNames	✔	✔
TabSeparatedWithNamesAndTypes	✔	✔
TabSeparatedRawWithNames	✔	✔
TabSeparatedRawWithNamesAndTypes	✔	✔
Template	✔	✔
TemplateIgnoreSpaces	✔	✗
CSV	✔	✔
CSVWithNames	✔	✔
CSVWithNamesAndTypes	✔	✔
CustomSeparated	✔	✔
CustomSeparatedWithNames	✔	✔
CustomSeparatedWithNamesAndTypes	✔	✔
SQLInsert	✗	✔
Значения	✔	✔
Vertical	✗	✔
JSON	✔	✔
JSONAsString	✔	✗
JSONAsObject	✔	✗
JSONStrings	✔	✔
JSONColumns	✔	✔
JSONColumnsWithMetadata	✔	✔
JSONCompact	✔	✔
JSONCompactStrings	✗	✔
JSONCompactColumns	✔	✔
JSONEachRow	✔	✔
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	✔	✔
Один	✔	✗
Npy	✔	✔
RowBinary	✔	✔
RowBinaryWithNames	✔	✔
RowBinaryWithNamesAndTypes	✔	✔
RowBinaryWithDefaults	✔	✗
Native	✔	✔
Null	✗	✔
Hash	✗	✔
XML	✗	✔
CapnProto	✔	✔
LineAsString	✔	✔
LineAsStringWithNames	✔	✔
LineAsStringWithNamesAndTypes	✔	✔
Регулярные выражения	✔	✗
RawBLOB	✔	✔
MsgPack	✔	✔
MySQLDump	✔	✗
DWARF	✔	✗
Markdown	✗	✔
Форма	✔	✗

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

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

Имя файла, содержащего схему формата, задаётся настройкой 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 используют разделитель после последнего столбца и разделитель между строками, чтобы найти начало следующей строки, поэтому пропуск ошибок работает только в том случае, если хотя бы один из этих разделителей не пуст.