Автоматическая инференция схемы из входных данных
ClickHouse может автоматически определить структуру входных данных почти во всех поддерживаемых форумах ввода. В этом документе будет описано, когда используется инференция схемы, как она работает с различными форматами ввода и какие настройки могут её контролировать.
Использование
Инференция схемы используется, когда ClickHouse необходимо прочитать данные в определенном формате, а структура неизвестна.
Табличные функции file, s3, url, hdfs, azureBlobStorage.
Эти табличные функции имеют необязательный аргумент structure, указывающий структуру входных данных. Если этот аргумент не указан или установлен в auto, структура будет выведена из данных.
Пример:
Предположим, у нас есть файл hobbies.jsonl в формате JSONEachRow в директории user_files со следующим содержимым:
ClickHouse может читать эти данные, не указывая их структуру:
Примечание: формат JSONEachRow был автоматически определён по расширению файла .jsonl.
Вы можете увидеть автоматически определённую структуру с помощью запроса DESCRIBE:
Табличные движки File, S3, URL, HDFS, azureBlobStorage
Если список колонок не указан в запросе CREATE TABLE, структура таблицы будет автоматически выведена из данных.
Пример:
Используя файл hobbies.jsonl, мы можем создать таблицу с движком File с данными из этого файла:
clickhouse-local
clickhouse-local имеет необязательный параметр -S/--structure с структурой входных данных. Если этот параметр не указан или установлен в auto, структура будет выведена из данных.
Пример:
Используя файл hobbies.jsonl, мы можем выполнить запрос данных из этого файла с помощью clickhouse-local:
Использование структуры из таблицы вставки
Когда табличные функции file/s3/url/hdfs используются для вставки данных в таблицу,
существует возможность использовать структуру из таблицы вставки вместо извлечения её из данных.
Это может улучшить производительность вставки, так как инференция схемы может занять некоторое время. Также это будет полезно, когда таблица имеет оптимизированную схему, так что
конверсии между типами не будут выполнены.
Существует специальная настройка use_structure_from_insertion_table_in_table_functions которая контролирует это поведение. Она имеет 3 возможных значения:
- 0 - табличная функция извлечет структуру из данных.
- 1 - табличная функция будет использовать структуру из таблицы вставки.
- 2 - ClickHouse автоматически определит, возможно ли использовать структуру из таблицы вставки или использовать инференцию схемы. Значение по умолчанию.
Пример 1:
Давайте создадим таблицу hobbies1 со следующей структурой:
И вставим данные из файла hobbies.jsonl:
В этом случае все столбцы из файла будут вставлены в таблицу без изменений, поэтому ClickHouse будет использовать структуру из таблицы вставки вместо инференции схемы.
Пример 2:
Давайте создадим таблицу hobbies2 со следующей структурой:
И вставим данные из файла hobbies.jsonl:
В этом случае все колонки в запросе SELECT присутствуют в таблице, поэтому ClickHouse будет использовать структуру из таблицы вставки.
Обратите внимание, что это сработает только для форматов ввода, которые поддерживают чтение подмножества колонок, таких как JSONEachRow, TSKV, Parquet и т.д. (например, это не сработает для формата TSV).
Пример 3:
Давайте создадим таблицу hobbies3 со следующей структурой:
И вставим данные из файла hobbies.jsonl:
В этом случае колонка id используется в запросе SELECT, но в таблице этой колонки не существует (она имеет колонку с именем identifier),
поэтому ClickHouse не может использовать структуру из таблицы вставки, и будет использована инференция схемы.
Пример 4:
Давайте создадим таблицу hobbies4 со следующей структурой:
И вставим данные из файла hobbies.jsonl:
В этом случае выполняются некоторые операции над колонкой hobbies в запросе SELECT, чтобы вставить её в таблицу, поэтому ClickHouse не может использовать структуру из таблицы вставки, и будет использована инференция схемы.
Кеш инференции схемы
Для большинства форматов ввода инференция схемы читает некоторые данные, чтобы определить их структуру, и этот процесс может занять некоторое время. Чтобы предотвратить повторное извлечение одной и той же схемы каждый раз, когда ClickHouse читает данные из одного и того же файла, выводимая схема кэшируется и при повторном доступе к тому же файлу ClickHouse будет использовать схему из кеша.
Существует специальные настройки, которые контролируют этот кеш:
schema_inference_cache_max_elements_for_{file/s3/hdfs/url/azure}- максимальное количество закэшированных схем для соответствующей табличной функции. Значение по умолчанию -4096. Эти настройки должны быть установлены в конфигурации сервера.schema_inference_use_cache_for_{file,s3,hdfs,url,azure}- позволяет включить/выключить использование кеша для инференции схемы. Эти настройки могут быть использованы в запросах.
Схема файла может быть изменена путем модификации данных или изменения настроек формата. По этой причине кеш инференции схемы идентифицирует схему по источнику файла, имени формата, используемым настройкам формата и времени последней модификации файла.
Примечание: некоторые файлы, доступные по URL в табличной функции url, могут не содержать информации о последнем времени модификации; для этого случая существует специальная настройка
schema_inference_cache_require_modification_time_for_url. Отключение этой настройки позволяет использовать схему из кеша без времени последней модификации для таких файлов.
Существуют также системная таблица schema_inference_cache со всеми текущими схемами в кеше и системный запрос SYSTEM DROP SCHEMA CACHE [FOR File/S3/URL/HDFS]
который позволяет очистить кеш схемы для всех источников или для конкретного источника.
Примеры:
Давайте попробуем вывести структуру образца набора данных из s3 github-2022.ndjson.gz и посмотрим, как работает кеш инференции схемы:
Как видно, второй запрос был выполнен почти мгновенно.
Давайте попробуем изменить некоторые настройки, которые могут повлиять на выводимую схему:
Как видно, схема из кеша не была использована для того же файла, поскольку настройка, которая может повлиять на инференцию схемы, была изменена.
Давайте проверим содержимое таблицы system.schema_inference_cache:
Как видно, для одного и того же файла есть две разные схемы.
Мы можем очистить кеш схемы с помощью системного запроса:
Текстовые форматы
Для текстовых форматов ClickHouse читает данные построчно, извлекает значения колонок в соответствии с форматом,
а затем использует некоторые рекурсивные парсеры и эвристики, чтобы определить тип для каждого значения. Максимальное количество строк и байтов, прочитанных из данных при инференции схемы
контролируется настройками input_format_max_rows_to_read_for_schema_inference (по умолчанию 25000) и input_format_max_bytes_to_read_for_schema_inference (по умолчанию 32Mb).
По умолчанию все выведенные типы являются Nullable, но вы можете изменить это, установив schema_inference_make_columns_nullable (см. примеры в разделе настройки).
JSON форматы
В форматах JSON ClickHouse парсит значения согласно спецификации JSON и затем пытается найти наиболее подходящий тип данных для них.
Давайте посмотрим, как это работает, какие типы могут быть выведены и какие конкретные настройки могут быть использованы в форматах JSON.
Примеры
Здесь и далее будет использоваться табличная функция format в примерах.
Целые числа, дробные числа, булевы значения, строки:
Даты, Дата-время:
Массивы:
Если массив содержит null, ClickHouse будет использовать типы из других элементов массива:
Именованные кортежи:
При включении настройки input_format_json_try_infer_named_tuples_from_objects ClickHouse будет пытаться вывести именованный кортеж из JSON объектов во время инференции схемы.
Результирующий именованный кортеж будет содержать все элементы из всех соответствующих JSON объектов из образца данных.
Неименованные кортежи:
В форматах JSON массивы с элементами разных типов рассматриваются как неименованные кортежи.
Если некоторые значения равны null или пустые, мы используем типы соответствующих значений из других строк:
Карты:
В JSON мы можем прочитать объекты со значениями одного и того же типа как тип Map.
Примечание: это будет работать только при отключенных настройках input_format_json_read_objects_as_strings и input_format_json_try_infer_named_tuples_from_objects.
Тип JSON-объекта (если включена настройка allow_experimental_object_type):
Вложенные сложные типы:
Если ClickHouse не может определить тип для некоторого ключа, потому что данные содержат только нули/пустые объекты/пустые массивы, будет использован тип String, если включена настройка input_format_json_infer_incomplete_types_as_strings, иначе будет выброшено исключение:
Настройки JSON
input_format_json_try_infer_numbers_from_strings
Включение этой настройки позволяет выводить числа из строковых значений.
Эта настройка отключена по умолчанию.
Пример:
input_format_json_try_infer_named_tuples_from_objects
Включение этой настройки позволяет выводить именованные кортежи из JSON объектов. Результирующий именованный кортеж будет содержать все элементы из всех соответствующих JSON объектов из образца данных. Это может быть полезно, когда JSON данные не являются разреженными, поэтому образец данных будет содержать все возможные ключи объектов.
Эта настройка включена по умолчанию.
Пример
Результат:
input_format_json_use_string_type_for_ambiguous_paths_in_named_tuples_inference_from_objects
Включение этой настройки позволяет использовать тип String для неоднозначных путей при выводе именованных кортежей из JSON-объектов (когда input_format_json_try_infer_named_tuples_from_objects включен) вместо исключения.
Это позволяет читать JSON-объекты как именованные кортежи, даже если пути неоднозначны.
По умолчанию отключено.
Примеры
С отключенной настройкой:
Результат:
С включенной настройкой:
Результат:
input_format_json_read_objects_as_strings
Включение этой настройки позволяет читать вложенные JSON-объекты как строки. Эта настройка может быть использована для чтения вложенных JSON-объектов без использования типа JSON-объекта.
Эта настройка включена по умолчанию.
Примечание: включение этой настройки будет иметь эффект только если настройка input_format_json_try_infer_named_tuples_from_objects отключена.
input_format_json_read_numbers_as_strings
Включение этой настройки позволяет читать числовые значения как строки.
Эта настройка включена по умолчанию.
Пример
input_format_json_read_bools_as_numbers
Включение этой настройки позволяет читать значения Bool как числа.
Эта настройка включена по умолчанию.
Пример:
input_format_json_read_bools_as_strings
Включение этой настройки позволяет читать значения Bool как строки.
Эта настройка включена по умолчанию.
Пример:
input_format_json_read_arrays_as_strings
Включение этой настройки позволяет читать значения массивов JSON как строки.
Эта настройка включена по умолчанию.
Пример
input_format_json_infer_incomplete_types_as_strings
Включение этой настройки позволяет использовать тип String для ключей JSON, которые содержат только Null/{}/[] в образце данных во время вывода схемы.
В форматах JSON любое значение можно читать как String, если все соответствующие настройки включены (они все включены по умолчанию), и мы можем избежать ошибок, таких как Cannot determine type for column 'column_name' by first 25000 rows of data, most likely this column contains only Nulls or empty Arrays/Maps во время вывода схемы, используя тип String для ключей с неизвестными типами.
Пример:
Результат:
CSV
В формате CSV ClickHouse извлекает значения колонок из строки в соответствии с разделителями. ClickHouse ожидает, что все типы, кроме чисел и строк, будут заключены в двойные кавычки. Если значение заключено в двойные кавычки, ClickHouse пытается разобрать данные внутри кавычек с помощью рекурсивного парсера и затем пытается найти наиболее подходящий тип данных для него. Если значение не заключено в двойные кавычки, ClickHouse пытается разобрать его как число, и если значение не является числом, ClickHouse обрабатывает его как строку.
Если вы не хотите, чтобы ClickHouse пытался определять сложные типы с помощью некоторых парсеров и эвристики, вы можете отключить настройку input_format_csv_use_best_effort_in_schema_inference, и ClickHouse будет рассматривать все колонки как строки.
Если настройка input_format_csv_detect_header включена, ClickHouse будет пытаться обнаружить заголовок с именами колонок (и, возможно, типами) во время вывода схемы. Эта настройка включена по умолчанию.
Примеры:
Целые числа, числа с плавающей запятой, логические значения, строки:
Строки без кавычек:
Даты, Датавремена:
Массивы:
Если массив содержит null, ClickHouse будет использовать типы из других элементов массива:
Карты:
Вложенные массивы и карты:
Если ClickHouse не может определить тип внутри кавычек, потому что данные содержат только нулевые значения, ClickHouse будет рассматривать это как строку:
Пример с отключенной настройкой input_format_csv_use_best_effort_in_schema_inference:
Примеры автоматического обнаружения заголовка (когда input_format_csv_detect_header включен):
Только имена:
Имена и типы:
Обратите внимание, что заголовок может быть обнаружен только если есть хотя бы одна колонка с не строковым типом. Если все колонки имеют строковый тип, заголовок не обнаруживается:
CSV settings
input_format_csv_try_infer_numbers_from_strings
Включение этой настройки позволяет выводить числа из строковых значений.
Эта настройка отключена по умолчанию.
Пример:
TSV/TSKV
В форматах TSV/TSKV ClickHouse извлекает значение колонки из строки в соответствии с табличными разделителями и затем парсит извлеченное значение с помощью рекурсивного парсера, чтобы определить наиболее подходящий тип. Если тип не может быть определен, ClickHouse обрабатывает это значение как строку.
Если вы не хотите, чтобы ClickHouse пытался определять сложные типы с помощью некоторых парсеров и эвристики, вы можете отключить настройку input_format_tsv_use_best_effort_in_schema_inference, и ClickHouse будет рассматривать все колонки как строки.
Если настройка input_format_tsv_detect_header включена, ClickHouse будет пытаться обнаружить заголовок с именами колонок (и, возможно, типами) во время вывода схемы. Эта настройка включена по умолчанию.
Примеры:
Целые числа, числа с плавающей запятой, логические значения, строки:
Даты, Датавремена:
Массивы:
Если ClickHouse не может определить тип, потому что данные содержат только null, ClickHouse будет считать это строкой:
Пример с отключенной настройкой input_format_tsv_use_best_effort_in_schema_inference:
Примеры автоматического обнаружения заголовка (когда input_format_tsv_detect_header включен):
Только имена:
Имена и типы:
Обратите внимание, что заголовок может быть обнаружен только если есть хотя бы одна колонка с не строковым типом. Если все колонки имеют строковый тип, заголовок не обнаруживается:
Значения
В формате значений ClickHouse извлекает значение колонки из строки и затем парсит его с помощью рекурсивного парсера, аналогично тому, как парсятся литералы.
Примеры:
Целые числа, числа с плавающей запятой, логические значения, строки:
Даты, ДатаВремя:
Массивы:
Если массив содержит null, ClickHouse будет использовать типы из других элементов массива:
Кортежи:
Словари:
Вложенные массивы, кортежи и словари:
Если ClickHouse не может определить тип, потому что данные содержат только null, будет выброшено исключение:
Пример с отключенной настройкой input_format_tsv_use_best_effort_in_schema_inference:
Пользовательские разделители
В формате с пользовательскими разделителями ClickHouse сначала извлекает все значения колонок из строки в соответствии с заданными разделителями, а затем пытается определить тип данных для каждого значения в соответствии с правилом экранирования.
Если включена настройка input_format_custom_detect_header, ClickHouse попытается обнаружить заголовок с именами колонок (и, возможно, типами) при определении схемы. Эта настройка включена по умолчанию.
Пример
Пример автоматического обнаружения заголовка (когда включена input_format_custom_detect_header):
Шаблон
В формате Шаблон ClickHouse сначала извлекает все значения колонок из строки в соответствии с заданным шаблоном, а затем пытается определить тип данных для каждого значения в соответствии с его правилом экранирования.
Пример
Допустим, у нас есть файл resultset с следующим содержимым:
И файл row_format с следующим содержимым:
Затем мы можем выполнить следующие запросы:
Регулярные выражения
Аналогично Шаблону, в формате Регулярные выражения ClickHouse сначала извлекает все значения колонок из строки в соответствии с заданным регулярным выражением, а затем пытается определить тип данных для каждого значения в соответствии с указанным правилом экранирования.
Пример
Настройки для текстовых форматов
input_format_max_rows_to_read_for_schema_inference/input_format_max_bytes_to_read_for_schema_inference
Эти настройки контролируют количество данных, которые будут прочитаны при определении схемы. Чем больше строк/байтов было прочитано, тем больше времени затрачивается на определение схемы, но тем больше шанс правильно определить типы (особенно когда данные содержат много null).
Значения по умолчанию:
25000дляinput_format_max_rows_to_read_for_schema_inference.33554432(32 Mb) дляinput_format_max_bytes_to_read_for_schema_inference.
column_names_for_schema_inference
Список имен колонок, которые будут использоваться при определении схемы для форматов без явных имен колонок. Указанные имена будут использоваться вместо значений по умолчанию c1,c2,c3,.... Формат: column1,column2,column3,....
Пример
schema_inference_hints
Список имен колонок и типов, которые будут использоваться при определении схемы вместо автоматически определенных типов. Формат: 'column_name1 column_type1, column_name2 column_type2, ...'. Эта настройка может использоваться для указания типов колонок, которые не могли быть определены автоматически или для оптимизации схемы.
Пример
schema_inference_make_columns_nullable
Управляет тем, будут ли типы, выведенные при определении схемы, Nullable для форматов без информации о нулевых значениях.
Если настройка включена, все выведенные типы будут Nullable, если отключена, выведенный тип никогда не будет Nullable, если установлена на auto, выведенный тип будет Nullable, только если колонка содержит NULL в выборке, обработанной во время определения схемы, или метаданные файла содержат информацию о нулевых значениях колонки.
Включено по умолчанию.
Примеры
input_format_try_infer_integers
Если включено, ClickHouse будет пытаться определить целые числа вместо чисел с плавающей запятой при определении схемы для текстовых форматов.
Если все числа в колонке из выборочных данных являются целыми, тип результата будет Int64, если хотя бы одно число является числом с плавающей запятой, тип результата будет Float64.
Если выборочные данные содержат только целые числа и хотя бы одно целое число положительное и превышает Int64, ClickHouse будет определять UInt64.
Включено по умолчанию.
Примеры
input_format_try_infer_datetimes
Если включено, ClickHouse будет пытаться определить тип DateTime или DateTime64 из строковых полей при определении схемы для текстовых форматов.
Если все поля в колонке из выборочных данных были успешно разобраны как даты и времена, тип результата будет DateTime или DateTime64(9) (если какое-либо значение даты и времени имело дробную часть),
если хотя бы одно поле не было разобрано как дата и время, тип результата будет String.
Включено по умолчанию.
Примеры
input_format_try_infer_dates
Если включено, ClickHouse будет пытаться определить тип Date из строковых полей при определении схемы для текстовых форматов.
Если все поля в колонке из выборочных данных были успешно разобраны как даты, тип результата будет Date,
если хотя бы одно поле не было разобрано как дата, тип результата будет String.
Включено по умолчанию.
Примеры
input_format_try_infer_exponent_floats
Если включено, ClickHouse будет пытаться определить числа с плавающей запятой в экспоненциальной форме для текстовых форматов (за исключением JSON, в котором числа в экспоненциальной форме всегда определяются).
Выключено по умолчанию.
Пример
Самоописывающиеся форматы
Самаописательные форматы содержат информацию о структуре данных в самих данных, это может быть какой-то заголовок с описанием, бинарное дерево типов или какая-то таблица. Чтобы автоматически вывести схему из файлов в таких форматах, ClickHouse читает часть данных, содержащую информацию о типах, и преобразует её в схему таблицы ClickHouse.
Форматы с суффиксом -WithNamesAndTypes
ClickHouse поддерживает некоторые текстовые форматы с суффиксом -WithNamesAndTypes. Этот суффикс означает, что данные содержат два дополнительных ряда с именами колонок и типами перед фактическими данными. При определении схемы для таких форматов ClickHouse читает первые два ряда и извлекает имена и типы колонок.
Пример
Форматы JSON с метаданными
Некоторые форматы входных данных JSON (JSON, JSONCompact, JSONColumnsWithMetadata) содержат метаданные с названиями колонок и их типами. При выводе схемы для таких форматов ClickHouse читает эти метаданные.
Пример
Avro
В формате Avro ClickHouse считывает его схему из данных и преобразует ее в схему ClickHouse, используя следующие соответствия типов:
| Тип данных Avro | Тип данных ClickHouse |
|---|---|
boolean | Bool |
int | Int32 |
int (date) * | Date32 |
long | Int64 |
float | Float32 |
double | Float64 |
bytes, string | String |
fixed | FixedString(N) |
enum | Enum |
array(T) | Array(T) |
union(null, T), union(T, null) | Nullable(T) |
null | Nullable(Nothing) |
string (uuid) * | UUID |
binary (decimal) * | Decimal(P, S) |
Другие типы Avro не поддерживаются.
Parquet
В формате Parquet ClickHouse считывает его схему из данных и преобразует ее в схему ClickHouse, используя следующие соответствия типов:
| Тип данных Parquet | Тип данных ClickHouse |
|---|---|
BOOL | Bool |
UINT8 | UInt8 |
INT8 | Int8 |
UINT16 | UInt16 |
INT16 | Int16 |
UINT32 | UInt32 |
INT32 | Int32 |
UINT64 | UInt64 |
INT64 | Int64 |
FLOAT | Float32 |
DOUBLE | Float64 |
DATE | Date32 |
TIME (ms) | DateTime |
TIMESTAMP, TIME (us, ns) | DateTime64 |
STRING, BINARY | String |
DECIMAL | Decimal |
LIST | Array |
STRUCT | Tuple |
MAP | Map |
Другие типы Parquet не поддерживаются. По умолчанию все выведенные типы находятся в Nullable, но это можно изменить с помощью настройки schema_inference_make_columns_nullable.
Arrow
В формате Arrow ClickHouse считывает его схему из данных и преобразует ее в схему ClickHouse, используя следующие соответствия типов:
| Тип данных Arrow | Тип данных ClickHouse |
|---|---|
BOOL | Bool |
UINT8 | UInt8 |
INT8 | Int8 |
UINT16 | UInt16 |
INT16 | Int16 |
UINT32 | UInt32 |
INT32 | Int32 |
UINT64 | UInt64 |
INT64 | Int64 |
FLOAT, HALF_FLOAT | Float32 |
DOUBLE | Float64 |
DATE32 | Date32 |
DATE64 | DateTime |
TIMESTAMP, TIME32, TIME64 | DateTime64 |
STRING, BINARY | String |
DECIMAL128, DECIMAL256 | Decimal |
LIST | Array |
STRUCT | Tuple |
MAP | Map |
Другие типы Arrow не поддерживаются. По умолчанию все выведенные типы находятся в Nullable, но это можно изменить с помощью настройки schema_inference_make_columns_nullable.
ORC
В формате ORC ClickHouse считывает его схему из данных и преобразует ее в схему ClickHouse, используя следующие соответствия типов:
| Тип данных ORC | Тип данных ClickHouse |
|---|---|
Boolean | Bool |
Tinyint | Int8 |
Smallint | Int16 |
Int | Int32 |
Bigint | Int64 |
Float | Float32 |
Double | Float64 |
Date | Date32 |
Timestamp | DateTime64 |
String, Char, Varchar, BINARY | String |
Decimal | Decimal |
List | Array |
Struct | Tuple |
Map | Map |
Другие типы ORC не поддерживаются. По умолчанию все выведенные типы находятся в Nullable, но это можно изменить с помощью настройки schema_inference_make_columns_nullable.
Native
Нативный формат используется внутри ClickHouse и содержит схему в данных. При выводе схемы ClickHouse считывает схему из данных без каких-либо преобразований.
Форматы с внешней схемой
Такие форматы требуют схемы, описывающей данные в отдельном файле на специфическом языке схемы. Чтобы автоматически создать схему из файлов в таких форматах, ClickHouse читает внешнюю схему из отдельного файла и преобразует ее в схему таблицы ClickHouse.
Protobuf
При выводе схемы для формата Protobuf ClickHouse использует следующие соответствия типов:
| Тип данных Protobuf | Тип данных ClickHouse |
|---|---|
bool | UInt8 |
float | Float32 |
double | Float64 |
int32, sint32, sfixed32 | Int32 |
int64, sint64, sfixed64 | Int64 |
uint32, fixed32 | UInt32 |
uint64, fixed64 | UInt64 |
string, bytes | String |
enum | Enum |
repeated T | Array(T) |
message, group | Tuple |
CapnProto
При выводе схемы для формата CapnProto ClickHouse использует следующие соответствия типов:
| Тип данных CapnProto | Тип данных ClickHouse |
|---|---|
Bool | UInt8 |
Int8 | Int8 |
UInt8 | UInt8 |
Int16 | Int16 |
UInt16 | UInt16 |
Int32 | Int32 |
UInt32 | UInt32 |
Int64 | Int64 |
UInt64 | UInt64 |
Float32 | Float32 |
Float64 | Float64 |
Text, Data | String |
enum | Enum |
List | Array |
struct | Tuple |
union(T, Void), union(Void, T) | Nullable(T) |
Строго типизированные бинарные форматы
В таких форматах каждое сериализованное значение содержит информацию о своем типе (а возможно, и о своем названии), но нет информации о всей таблице.
При выводе схемы для таких форматов ClickHouse считывает данные строка за строкой (до input_format_max_rows_to_read_for_schema_inference строк или input_format_max_bytes_to_read_for_schema_inference байт) и извлекает
тип (а возможно имя) для каждого значения из данных, а затем преобразует эти типы в типы ClickHouse.
MsgPack
В формате MsgPack нет разделителей между строками, чтобы использовать вывод схемы для этого формата, вы должны указать количество колонок в таблице
с помощью настройки input_format_msgpack_number_of_columns. ClickHouse использует следующие соответствия типов:
Тип данных MessagePack (INSERT) | Тип данных ClickHouse |
|---|---|
int N, uint N, negative fixint, positive fixint | Int64 |
bool | UInt8 |
fixstr, str 8, str 16, str 32, bin 8, bin 16, bin 32 | String |
float 32 | Float32 |
float 64 | Float64 |
uint 16 | Date |
uint 32 | DateTime |
uint 64 | DateTime64 |
fixarray, array 16, array 32 | Array |
fixmap, map 16, map 32 | Map |
По умолчанию все выведенные типы находятся в Nullable, но это можно изменить с помощью настройки schema_inference_make_columns_nullable.
BSONEachRow
В формате BSONEachRow каждая строка данных представлена как BSON-документ. При выводе схемы ClickHouse считывает BSON-документы по одному и извлекает значения, названия и типы из данных, а затем преобразует эти типы в типы ClickHouse с помощью следующих соответствий типов:
| Тип BSON | Тип ClickHouse |
|---|---|
\x08 boolean | Bool |
\x10 int32 | Int32 |
\x12 int64 | Int64 |
\x01 double | Float64 |
\x09 datetime | DateTime64 |
\x05 binary с \x00 бинарным подтипом, \x02 строка, \x0E символ, \x0D JavaScript код | String |
\x07 ObjectId, | FixedString(12) |
\x05 binary с \x04 uuid подтипом, размер = 16 | UUID |
\x04 массив | Array/Tuple (если вложенные типы разные) |
\x03 документ | Named Tuple/Map (с ключами String) |
По умолчанию все выведенные типы находятся в Nullable, но это можно изменить с помощью настройки schema_inference_make_columns_nullable.
Форматы с постоянной схемой
Данные в таких форматах всегда имеют одну и ту же схему.
LineAsString
В этом формате ClickHouse считывает всю строку из данных в один столбец с типом данных String. Выведенный тип для этого формата всегда String, а название столбца line.
Пример
JSONAsString
В этом формате ClickHouse считывает весь JSON-объект из данных в один столбец с типом данных String. Выведенный тип для этого формата всегда String, а название столбца json.
Пример
JSONAsObject
В этом формате ClickHouse считывает весь JSON-объект из данных в один столбец с типом данных Object('json'). Выведенный тип для этого формата всегда String, а название столбца json.
Примечание: Этот формат работает только если allow_experimental_object_type включен.
Пример
Режимы вывода схемы
Вывод схемы из набора файлов данных может работать в 2 разных режимах: default и union.
Режим контролируется настройкой schema_inference_mode.
Режим по умолчанию
В режиме по умолчанию ClickHouse предполагает, что все файлы имеют одинаковую схему и пытается вывести схему, читая файлы по одному, пока это не удастся.
Пример:
Допустим, у нас есть 3 файла data1.jsonl, data2.jsonl и data3.jsonl со следующим содержимым:
data1.jsonl:
data2.jsonl:
data3.jsonl:
Давайте попытаемся использовать вывод схемы на этих 3 файлах:
Результат:
Как мы видим, у нас нет field3 из файла data3.jsonl.
Это происходит потому, что ClickHouse сначала попытался вывести схему из файла data1.jsonl, не смог, из-за только нулей для поля field2,
а затем пытался вывести схему из data2.jsonl и успешно, так что данные из файла data3.jsonl не были прочитаны.
Режим объединения
В режиме объединения ClickHouse предполагает, что файлы могут иметь разные схемы, поэтому он выводит схемы всех файлов, а затем объединяет их в общую схему.
Допустим, у нас есть 3 файла data1.jsonl, data2.jsonl и data3.jsonl со следующим содержимым:
data1.jsonl:
data2.jsonl:
data3.jsonl:
Давайте попытаемся использовать вывод схемы на этих 3 файлах:
Результат:
Как мы видим, у нас есть все поля из всех файлов.
Примечание:
- Поскольку некоторые из файлов могут не содержать некоторые колонки из результирующей схемы, режим объединения поддерживается только для форматов, которые поддерживают чтение подмножества колонок (такие как JSONEachRow, Parquet, TSVWithNames и др.) и не будет работать для других форматов (таких как CSV, TSV, JSONCompactEachRow и др.).
- Если ClickHouse не может вывести схему из одного из файлов, будет выброшено исключение.
- Если у вас много файлов, считывание схемы из всех них может занять много времени.
Автоматическое определение формата
Если формат данных не указан и не может быть определен по расширению файла, ClickHouse попытается определить формат файла по его содержимому.
Примеры:
Допустим, у нас есть data со следующим содержимым:
Мы можем просмотреть и выполнить запрос к этому файлу, не указывая формат или структуру:
ClickHouse может обнаружить только некоторый подмножество форматов, и это определение занимает некоторое время, поэтому всегда лучше явно указывать формат.