Arrow

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`
`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_record_batch_size`	Número objetivo de filas por record batch al combinar bloques pequeños. El almacenamiento en búfer puede aumentar el uso de memoria y retrasar el primer batch hasta que finalice la consulta. `0` desactiva el objetivo de filas.	`0`
`output_format_arrow_record_batch_size_bytes`	Número objetivo de bytes de datos de bloque acumulados por record batch. El almacenamiento en búfer puede aumentar el uso de memoria y retrasar el primer batch hasta que finalice la consulta. `0` desactiva el objetivo de bytes.	`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`	Qué escribir para un tipo que no tiene equivalente en Arrow (por ejemplo, `JSON`, `Dynamic`, `QBit`, `AggregateFunction`): `throw`, `text` (un valor `serializeText` por fila, en el tipo Arrow que usaría una columna `String`) o `binary` (un valor `serializeBinary` por fila, como `Binary` de Arrow). Un `AggregateFunction` también es `Binary` en modo `text`, ya que su forma textual es el estado de agregación sin procesar.	`binary`
`output_format_arrow_unsupported_types_as_binary`	Reemplazada por `output_format_arrow_unsupported_types`: `0` significa `throw`, `1` significa `binary`. Solo se tiene en cuenta mientras esa configuración conserve su valor predeterminado.	`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_signed_indexes_for_dictionary`	Usa enteros con signo para los índices de diccionario en formato Arrow	`1`

Referencia de SQL

Tipos de datos

Motores

Funciones

Formatos

Configuración

Tablas del sistema

Lagos de datos

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

​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

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