HiveText

HiveText lee y escribe el formato de serialización de texto utilizado por las tablas de Apache Hive (el formato generado por LazySimpleSerDe de Hive). Es un formato de texto delimitado, similar a CSV, en el que los campos están separados por el delimitador predeterminado de Hive \x01 (Ctrl-A). El delimitador de campos se puede configurar mediante input_format_hive_text_fields_delimiter.

Cuando se utiliza como formato de entrada, los datos no tienen fila de encabezado: los valores se asignan por posición a las columnas de la tabla de destino, por lo que los nombres y tipos de las columnas se toman de la tabla (o de una estructura proporcionada explícitamente) en lugar de inferirse a partir de los datos. Durante la lectura, ClickHouse analiza fechas y horas en modo de máximo esfuerzo (consulte date_time_input_format), completa los campos finales omitidos con los valores predeterminados de las columnas y omite los campos que no reconoce.

Dentro de un campo, los valores se analizan usando las mismas reglas de escape que CSV en lugar de los delimitadores anidados de Hive. En particular, una columna de tipo Array se lee a partir de la representación entre corchetes (por ejemplo, "['a','b','c']"), no a partir de valores separados por el delimitador de colección de Hive \x02.

De forma predeterminada, se permite que las filas tengan un número variable de campos (consulte input_format_hive_text_allow_variable_number_of_columns): las filas con menos campos que la tabla completan las columnas faltantes con valores predeterminados, y en las filas con campos adicionales al final, esos campos extra se omiten.

Los ejemplos a continuación reemplazan el delimitador de campos predeterminado por una coma (,) mediante input_format_hive_text_fields_delimiter, para que los archivos de entrada sean más fáciles de leer.

Dado un archivo hive_data.txt con campos separados por comas:

1,3
3,5,9

Creamos una tabla que define los nombres de las columnas y sus tipos de datos, e insertamos el archivo en ella con FORMAT HiveText:

CREATE TABLE test_tbl (a UInt16, b UInt32, c UInt32) ENGINE = MergeTree ORDER BY a;

INSERT INTO test_tbl FROM INFILE 'hive_data.txt'
SETTINGS input_format_hive_text_fields_delimiter = ','
FORMAT HiveText;

SELECT * FROM test_tbl;

┌─a─┬─b─┬─c─┐
│ 1 │ 3 │ 0 │
│ 3 │ 5 │ 9 │
└───┴───┴───┘

Ten en cuenta que la primera fila, 1,3, solo tiene dos campos, por lo que la columna c faltante se rellena con su valor predeterminado 0.

Con el valor predeterminado input_format_hive_text_allow_variable_number_of_columns = 1, las filas que tienen más campos que la tabla simplemente omiten los campos adicionales al final:

1,2,3,4,5
6,7,8

CREATE TABLE test_extras (a UInt16, b UInt32, c UInt32) ENGINE = MergeTree ORDER BY a;

INSERT INTO test_extras FROM INFILE 'hive_extras.txt'
SETTINGS input_format_hive_text_fields_delimiter = ','
FORMAT HiveText;

SELECT * FROM test_extras ORDER BY a;

┌─a─┬─b─┬─c─┐
│ 1 │ 2 │ 3 │
│ 6 │ 7 │ 8 │
└───┴───┴───┘

En cambio, establecer input_format_hive_text_allow_variable_number_of_columns = 0 impone un número estricto de campos, y una fila con menos campos que la tabla provoca una excepción de análisis sintáctico.

Cuando se utiliza como formato de salida, HiveText escribe cada fila sin comillas: los campos de nivel superior se separan mediante el delimitador de campos (\x01 de forma predeterminada) y las filas se separan mediante el delimitador de filas (\n de forma predeterminada, configurable mediante format_hive_text_rows_delimiter). Los valores de tipos anidados (Array, Map y Tuple) se escriben sin corchetes y se separan mediante el separador de Hive correspondiente a su nivel de anidamiento, tal como lo hace LazySimpleSerDe de Hive. Los tres primeros separadores son el delimitador de campos configurable, input_format_hive_text_collection_items_delimiter (\x02 de forma predeterminada, utilizado para elementos de arrays, entradas de maps y elementos de tuplas) y input_format_hive_text_map_keys_delimiter (\x03 de forma predeterminada, utilizado entre una clave de map y su valor); para niveles más profundos se utilizan de forma predeterminada caracteres de control consecutivos (\x04, \x05, y así sucesivamente, hasta ocho niveles). Un árbol de tipos anidado con la profundidad suficiente para requerir un separador más allá de esos ocho niveles se rechaza con una excepción NOT_IMPLEMENTED, ya que LazySimpleSerDe de Hive tampoco dispone de un separador para ello. Los tipos de datos que no tienen una representación textual natural en Hive no son compatibles con la salida y generan una excepción NOT_IMPLEMENTED. Esto incluye AggregateFunction, Dynamic, Variant, LowCardinality y Object, así como los tipos basados en números Enum, Time, Time64 e Interval — Hive no dispone de un tipo equivalente para estos últimos, por lo que se rechazan en lugar de escribirse como sus valores numéricos subyacentes sin procesar. Los tipos numéricos de gran tamaño Int128, UInt128, Int256 y UInt256 se rechazan por la misma razón: el entero de mayor tamaño de Hive es BIGINT (64 bits), e incluso DECIMAL de Hive, con una precisión máxima de 38, no puede contener su rango de valores. Del mismo modo, los valores Decimal con una precisión superior a 38 (es decir, Decimal256) superan la precisión máxima de DECIMAL de Hive y se rechazan. Asimismo, las claves de Map deben ser de tipo primitivo: Hive declara los maps como MAP<primitive_type, data_type>, por lo que un Map cuyo tipo de clave sea Array, Map o Tuple (algo que ClickHouse permite) se rechaza con una excepción NOT_IMPLEMENTED, porque ningún esquema de Hive podría volver a leer esos valores. El literal de map vacío map() se rechaza por la misma razón: su tipo es Map(Nothing, Nothing), y Nothing no es un tipo que pueda figurar en una declaración MAP<key_type, data_type> de Hive. Todas estas comprobaciones se aplican de antemano a los tipos de columna declarados, antes de que se escriba cualquier fila: una consulta cuyo encabezado contenga un tipo no compatible en cualquier parte de su árbol de tipos se rechaza incluso cuando los valores reales nunca llegarían a la serialización no compatible (por ejemplo, un Nullable de un tipo no compatible que contenga únicamente valores NULL, o un Array/Map vacío con un tipo de elemento no compatible), porque el esquema declarado del archivo seguiría sin poder corresponder a ninguna tabla de Hive.

Date, Date32, DateTime y DateTime64 siempre se escriben en el formato de texto simple de fecha y timestamp de Hive (yyyy-MM-dd y yyyy-MM-dd HH:mm:ss[.fffffffff]), independientemente de la configuración date_time_output_format, para que Hive pueda analizar la salida incluso cuando esa configuración sea unix_timestamp o iso.

Por la misma razón, los valores Bool siempre se escriben como true/false, independientemente de las configuraciones bool_true_representation y bool_false_representation, y los valores NULL siempre se escriben como la secuencia nula predeterminada de Hive, \N, independientemente de la configuración format_csv_null_representation. Esto permite que LazySimpleSerDe de Hive lea la salida independientemente de estas configuraciones de texto genéricas. De forma análoga, el formato de entrada HiveText siempre interpreta \N como NULL, también independientemente de la configuración format_csv_null_representation, por lo que la conversión de ida y vuelta de escalares de nivel superior no depende de ella.

Los valores no finitos de Float32 y Float64 se escriben con las grafías de Java que usa Hive: NaN, Infinity y -Infinity, en lugar de los tokens habituales de ClickHouse nan/inf/-inf, para que el analizador de FLOAT/DOUBLE de Hive los vuelva a leer como los mismos valores en lugar de NULL.

SELECT '20240305', tuple(123567, 'e01001', map('action1', 33333, 'act2', 5555)) FORMAT HiveText;