Descripción
Apache Parquet es un formato de almacenamiento columnar muy extendido en el ecosistema de Hadoop. ClickHouse admite operaciones de lectura y escritura en este formato.Correspondencia de tipos de datos
La tabla siguiente muestra cómo se corresponden los tipos de datos de Parquet con los tipos de datos de ClickHouse.
Al escribir un archivo Parquet, los tipos de datos que no tienen un tipo de Parquet correspondiente se convierten al tipo disponible más cercano:
Los arrays pueden estar anidados y pueden tener un valor de tipo
Nullable como argumento. Los tipos Tuple y Map también pueden estar anidados.
Enteros anchos
De forma predeterminada, ClickHouse escribeInt128, UInt128, Int256 y UInt256 como valores FIXED_LEN_BYTE_ARRAY(16/32) sin anotaciones en orden little-endian. Esta representación heredada sigue siendo la predeterminada para que los archivos puedan leerse con versiones anteriores de ClickHouse.
Establezca output_format_parquet_wide_integer_as_decimal = 1 para usar en su lugar la representación estándar DECIMAL de Parquet:
La representación decimal proporciona ordenamiento numérico para las estadísticas estándar de fragmentos de columna y los índices de página de Parquet, lo que permite a ClickHouse usar la poda de mínimos/máximos de grupos de filas y páginas. ClickHouse lee ambas codificaciones. Para una precisión decimal de 39, la inferencia de esquema devuelve
Decimal(39, 0), respaldado por Decimal256; especifique una estructura explícita Int128 o UInt128 para recuperar un tipo de entero ancho. La precisión decimal 77 o 78 supera el rango de Decimal256 de ClickHouse, por lo que leer esos archivos requiere una estructura explícita compatible Int256 o UInt256. Con una estructura explícita de entero ancho, ClickHouse acepta valores decimales estándar almacenados como BYTE_ARRAY o FIXED_LEN_BYTE_ARRAY de cualquier ancho válido, y verifica el rango de cada valor después de eliminar la extensión de signo.
Algunos clientes de Parquet admiten precisión decimal solo hasta 38, mientras que los tipos decimales de alto nivel de Arrow admiten precisión solo hasta 76. Dichos clientes pueden rechazar la representación de precisión 77/78 aunque su esquema y ancho físico de 33 bytes cumplan con Parquet. Mantenga la configuración deshabilitada cuando los archivos deban leerse con versiones anteriores de ClickHouse o clientes con límites decimales menores.
Los tipos de datos de las columnas de una tabla de ClickHouse pueden diferir de los campos correspondientes de los datos Parquet insertados. Al insertar datos, ClickHouse interpreta los tipos de datos según la tabla anterior y luego convierte los datos al tipo de dato establecido para la columna de la tabla de ClickHouse. P. ej., una columna Parquet UINT_32 puede leerse en una columna IPv4 de ClickHouse.
Para algunos tipos de Parquet no hay un tipo de ClickHouse que coincida estrechamente. Los leemos de la siguiente manera:
TIMESTAMPconisAdjustedToUTC=falsees una hora local de reloj (campos de año, mes, día, hora, minuto, segundo y fracción de segundo en una zona horaria local, independientemente de qué zona horaria específica se considere local), igual que SQLTIMESTAMP WITHOUT TIME ZONE. Sin embargo, ClickHouse lo lee como si fuera una marca temporal UTC. P. ej.,2025-09-29 18:42:13.000(que representa la hora de un reloj local) se convierte en2025-09-29 18:42:13.000(DateTime64(3, 'UTC'), que representa un punto en el tiempo). Si se convierte a String, muestra el año, mes, día, hora, minuto, segundo y fracción de segundo correctos, que luego pueden interpretarse como pertenecientes a alguna zona horaria local en lugar de UTC. Aunque resulte contraintuitivo, cambiar el tipo deDateTime64(3, 'UTC')aDateTime64(3)no ayudaría, ya que ambos tipos representan un punto en el tiempo en lugar de una lectura de reloj, peroDateTime64(3)se formatearía incorrectamente usando la zona horaria local.INTERVALactualmente se lee comoFixedString(12)con la representación binaria sin procesar del intervalo de tiempo, tal como está codificada en el archivo Parquet.
Tipos geo (GeoParquet)
ClickHouse admite la lectura y escritura de columnas de geometría conforme a la especificación GeoParquet. Las columnas de geometría se almacenan como payloadsBYTE_ARRAY codificados en WKB (o en WKT al leer), con una clave JSON geo en los metadatos de Parquet a nivel de archivo que describe la codificación, el tipo de geometría y el CRS de cada columna de geometría.
Comportamiento de lectura
Al leer, las columnas de geometría se asignan a los tipos de datos geo correspondientes de ClickHouse:- Una columna declarada como
Point,MultiPoint,LineString,Polygon,MultiLineStringoMultiPolygonse lee como el tipo geo correspondiente de ClickHouse. - Una columna con varios tipos de geometría o con tipos de geometría desconocidos se lee como el tipo
Geometry, que es unVariantde todos los tipos geo compatibles. - Si el tipo de columna solicitado es
String, se ignoran los metadatos de GeoParquet y se devuelve el payload de geometría codificada sin procesar, tal cual: bytes WKB o WKT, según la codificación que declare la columna de GeoParquet. Esto también se aplica si la configuracióninput_format_parquet_allow_geoparquet_parserestá establecida en0.
Comportamiento de escritura
Al escribir, las columnas de nivel superior de tipoPoint, MultiPoint, LineString, Polygon, MultiLineString o MultiPolygon se codifican como BYTE_ARRAY (WKB) y se añaden los metadatos JSON geo correspondientes al pie de página del archivo Parquet. Un Geometry Variant de nivel superior también se codifica como un payload BYTE_ARRAY de WKB (sus subvalores se convierten a WKB y se almacenan como una columna Nullable(String)), pero no se emiten metadatos geo para él, por lo que el resultado no se reconoce como una columna de geometría GeoParquet al leerlo. Otros tipos relacionados con geo, como Ring, se escriben usando su representación subyacente nativa, sin metadatos GeoParquet. Este comportamiento puede deshabilitarse por completo configurando output_format_parquet_geometadata en 0, en cuyo caso incluso los tipos geo compatibles se escriben usando su representación subyacente nativa (Point como Tuple(Float64, Float64), LineString como Array(Point), Polygon como Array(Array(Point)), etc.) y no se emiten metadatos GeoParquet.
Las columnas de geometría deben aparecer en la raíz del esquema o anidadas dentro de Tuple (struct); no se admite anidarlas dentro de Array o Map. Nullable tampoco se admite para las columnas geo.
Ejemplo de uso
Inserción de datos
Utiliza un archivo Parquet con los siguientes datos, llamadofootball.parquet:
Leer datos
Lea los datos con el formatoParquet:
motor de tabla HDFS.