Arrow - ClickHouse Documentation

Entrada	Salida	Alias
✔	✔

Descripción

Apache Arrow incluye dos formatos integrados de almacenamiento columnar. ClickHouse admite operaciones de lectura y escritura en estos formatos. Arrow es el formato de Apache Arrow en “modo de archivo”, diseñado para el acceso aleatorio en memoria.

Correspondencia entre tipos de datos

La siguiente tabla muestra los tipos de datos admitidos y cómo se corresponden con los tipos de datos de ClickHouse en las consultas INSERT y SELECT.

Tipo de dato de Arrow (`INSERT`)	Tipo de dato de ClickHouse	Tipo de dato de Arrow (`SELECT`)
`BOOL`	Bool	`BOOL`
`UINT8`, `BOOL`	UInt8	`UINT8`
`INT8`	Int8/Enum8	`INT8`
`UINT16`	UInt16	`UINT16`
`INT16`	Int16/Enum16	`INT16`
`UINT32`	UInt32	`UINT32`
`INT32`	Int32	`INT32`
`UINT64`	UInt64	`UINT64`
`INT64`	Int64	`INT64`
`FLOAT`, `HALF_FLOAT`	Float32	`FLOAT32`
`DOUBLE`	Float64	`FLOAT64`
`DATE32`	Date32	`UINT16`
`DATE64`	DateTime	`UINT32`
`TIMESTAMP`	DateTime64	`TIMESTAMP`
`TIME32`, `TIME64`	Time64	`TIME32`, `TIME64`
`STRING`, `BINARY`	String	`BINARY`
`STRING`, `BINARY`, `FIXED_SIZE_BINARY`	FixedString	`FIXED_SIZE_BINARY`
`DECIMAL`	Decimal	`DECIMAL`
`DECIMAL256`	Decimal256	`DECIMAL256`
`LIST`	Array	`LIST`
`STRUCT`	Tuple	`STRUCT`
`MAP`	Map	`MAP`
`UINT32`	IPv4	`UINT32`
`FIXED_SIZE_BINARY`, `BINARY`	IPv6	`FIXED_SIZE_BINARY`
`FIXED_SIZE_BINARY`, `BINARY`	Int128/UInt128/Int256/UInt256	`FIXED_SIZE_BINARY`
`DURATION`	Interval (Nanosegundo/Microsegundo/Milisegundo/Segundo)	`DURATION`
`INT64`	Interval (Minuto/Hora/Día/Semana/Mes/Trimestre/Año)	`INT64`

Los tipos Array pueden anidarse y pueden tener como argumento un valor de tipo Nullable. Los tipos Tuple y Map también pueden anidarse. El tipo DICTIONARY es compatible con las consultas INSERT, y para las consultas SELECT existe la configuración output_format_arrow_low_cardinality_as_dictionary, que permite generar el tipo LowCardinality como un tipo DICTIONARY. Tenga en cuenta que puede haber valores no utilizados en el diccionario LowCardinality, lo que puede dar lugar a valores no utilizados en el DICTIONARY de Arrow en la salida. Tipos de datos de Arrow no compatibles:

JSON
ENUM.

Los tipos de datos de las columnas de la tabla de ClickHouse no tienen que coincidir con los campos de datos de Arrow correspondientes. Al insertar datos, ClickHouse interpreta los tipos de datos según la tabla anterior y luego convierte los datos al tipo de dato definido para la columna de la tabla de ClickHouse.

Ejemplo de uso

En el ejemplo siguiente, usamos el conjunto de datos forex disponible en el Playground de SQL de ClickHouse.

Selección de datos

Seleccionamos un día de cotizaciones de EUR/USD del Playground de SQL y lo guardamos en un archivo local forex_eurusd.arrow. Consultamos el Playground de SQL a través de la interfaz HTTP, donde el host es sql-clickhouse.clickhouse.com y el usuario es demo (que no tiene contraseña):

curl "https://sql-clickhouse.clickhouse.com:8443/?user=demo&database=forex" \
    --data-binary "
        SELECT
            concat(base, '.', quote) AS base_quote,
            datetime AS last_update,
            CAST(bid, 'Float32') AS bid,
            CAST(ask, 'Float32') AS ask,
            ask - bid AS spread
        FROM forex
        WHERE base = 'EUR' AND quote = 'USD'
            AND datetime >= '2020-01-01' AND datetime < '2020-01-02'
        ORDER BY datetime ASC
        FORMAT Arrow
        SETTINGS output_format_arrow_compression_method='zstd'" > forex_eurusd.arrow

Leer de nuevo el archivo

Ahora podemos volver a leer el archivo Arrow local con clickhouse-local usando la función de tabla file. El archivo es autodescriptivo, por lo que el formato Arrow infiere el esquema automáticamente:

clickhouse-local --query "
    SELECT *
    FROM file('forex_eurusd.arrow', Arrow)
    ORDER BY last_update ASC
    LIMIT 5
    FORMAT PrettyCompact"

Response

   ┌─base_quote─┬─────────────last_update─┬─────bid─┬─────ask─┬────────────────spread─┐
│ EUR.USD    │ 2020-01-01 17:00:00.065 │  1.1212 │ 1.12172 │ 0.0005199909210205078 │
│ EUR.USD    │ 2020-01-01 17:00:10.447 │  1.1212 │ 1.12192 │ 0.0007200241088867188 │
│ EUR.USD    │ 2020-01-01 17:00:10.498 │ 1.12117 │ 1.12161 │ 0.0004400014877319336 │
│ EUR.USD    │ 2020-01-01 17:00:12.579 │  1.1212 │ 1.12161 │ 0.0004100799560546875 │
│ EUR.USD    │ 2020-01-01 17:00:12.630 │  1.1212 │ 1.12172 │ 0.0005199909210205078 │
   └────────────┴─────────────────────────┴─────────┴─────────┴───────────────────────┘

Insertar datos

Para cargar un archivo Arrow en una tabla de ClickHouse, páselo por una tubería a clickhouse-client con FORMAT Arrow:

cat forex_eurusd.arrow | clickhouse-client --query="INSERT INTO some_table FORMAT Arrow"

Configuración del formato

Configuración	Descripción	Predeterminado
`input_format_arrow_allow_missing_columns`	Permite columnas ausentes al leer formatos de entrada Arrow	`1`
`input_format_arrow_case_insensitive_column_matching`	Ignora las mayúsculas y minúsculas al hacer coincidir columnas de Arrow con columnas de CH.	`0`
`input_format_arrow_import_nested`	Configuración obsoleta; no hace nada.	`0`
`input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference`	Omite las columnas con tipos no compatibles durante la inferencia de esquema para el formato Arrow	`0`
`input_format_arrow_use_native_reader`	Usa el lector nativo de ClickHouse para los formatos `Arrow` y `ArrowStream` en lugar de la biblioteca Apache Arrow. Establécelo en `0` para usar el lector de la biblioteca Apache Arrow.	`1`
`output_format_arrow_compression_method`	Método de compresión para el formato de salida Arrow. Codecs compatibles: lz4_frame, zstd, none (sin comprimir)	`lz4_frame`
`output_format_arrow_fixed_string_as_fixed_byte_array`	Usa el tipo Arrow FIXED_SIZE_BINARY en lugar de Binary para columnas FixedString.	`1`
`output_format_arrow_low_cardinality_as_dictionary`	Habilita la salida del tipo LowCardinality como tipo Diccionario de Arrow	`0`
`output_format_arrow_string_as_string`	Usa el tipo Arrow String en lugar de Binary para columnas String	`1`
`output_format_arrow_unsupported_types_as_binary`	Genera como datos binarios sin procesar un tipo que no tiene equivalente en Arrow (por ejemplo, `BFloat16`, `AggregateFunction`). Si es false, ese tipo genera una excepción. Se aplica tanto al escritor nativo como al de la biblioteca Apache Arrow.	`1`
`output_format_arrow_use_64_bit_indexes_for_dictionary`	Usa siempre enteros de 64 bits para los índices de diccionario en formato Arrow	`0`
`output_format_arrow_use_native_writer`	Usa el escritor nativo de ClickHouse para los formatos `Arrow` y `ArrowStream` en lugar de la biblioteca Apache Arrow. Establécelo en `0` para usar el escritor de la biblioteca Apache Arrow.	`1`
`output_format_arrow_use_signed_indexes_for_dictionary`	Usa enteros con signo para los índices de diccionario en formato Arrow	`1`

​Descripción

​Correspondencia entre tipos de datos

​Ejemplo de uso

​Selección de datos

​Leer de nuevo el archivo

​Insertar datos

​Configuración del formato