Автоматическое определение схемы из входных данных
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 в 1, во время определения схемы ClickHouse будет пытаться вызывать именованный кортеж из объектов JSON.
Результирующий именованный кортеж будет содержать все элементы из всех соответствующих объектов JSON из образца данных.
Неименованные кортежи:
В форматах JSON мы обрабатываем массивы с элементами различных типов как неименованные кортежи.
Если некоторые значения null или пустые, мы используем типы соответствующих значений из других строк:
Карты:
В JSON мы можем читать объекты с одинаковыми типами значений в качестве типа карты.
Примечание: это будет работать только когда настройки 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 не может определить тип внутри кавычек, потому что данные содержат только null, 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 будет пытаться обнаружить заголовок с именами столбцов (и, возможно, типами) во время вывода схемы. Эта настройка включена по умолчанию.
Примеры:
Целые числа, числа с плавающей точкой, логические значения, строки:
Даты, временные метки:
Массивы:
Если массив содержит null, ClickHouse будет использовать типы из других элементов массива:
Кортежи:
Карты:
Вложенные массивы, кортежи и карты:
Если ClickHouse не может определить тип, потому что данные содержат только null, ClickHouse будет рассматривать это как строку:
Пример с отключенной настройкой input_format_tsv_use_best_effort_in_schema_inference:
Примеры автоматического обнаружения заголовка (когда input_format_tsv_detect_header включена):
Только названия:
Названия и типы:
Обратите внимание, что заголовок может быть обнаружен только в том случае, если существует хотя бы один столбец с нестандартным типом. Если все столбцы имеют строковый тип, заголовок не обнаруживается:
Значения
В формате Values ClickHouse извлекает значение колонки из строки, а затем разбирает его с помощью рекурсивного разбора, аналогично тому, как разбираются литералы.
Примеры:
Целые числа, числа с плавающей запятой, булевые значения, строки:
Даты, ДатаВремя:
Массивы:
Если массив содержит null, ClickHouse будет использовать типы из других элементов массива:
Кортежи:
Карты:
Вложенные массивы, кортежи и карты:
Если ClickHouse не может определить тип, поскольку данные содержат только null, будет выброшено исключение:
Пример с отключенной настройкой input_format_tsv_use_best_effort_in_schema_inference:
CustomSeparated
В формате CustomSeparated 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_datetimes_only_datetime64
Если включено, ClickHouse всегда будет выводить DateTime64(9), когда включена настройка input_format_try_infer_datetimes, даже если значения даты и времени не содержат дробной части.
Отключено по умолчанию.
Примеры
Примечание: Парсинг дат и времен во время вывода схемы учитывает настройку date_time_input_format
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 может обнаружить только некоторый подмножество форматов, и это обнаружение занимает некоторое время; всегда лучше явно указывать формат.