ArrowStream - ClickHouse Documentation

Entrada	Salida	Alias
✔	✔

Descripción

ArrowStream es el formato de Apache Arrow para el «modo stream». Está diseñado para procesar flujos en memoria.

Ejemplo de uso

En el siguiente ejemplo usamos el conjunto de datos forex, que está disponible en el Playground de SQL de ClickHouse. Puede conectarse a él de forma remota con clickhouse-client usando el host sql-clickhouse.clickhouse.com y el usuario demo (que no tiene contraseña). La tabla forex se encuentra en la base de datos forex, así que la seleccionamos como base de datos predeterminada:

clickhouse-client --secure --host sql-clickhouse.clickhouse.com --user demo --database forex

La tabla forex almacena tipos de cambio de divisas. Podemos comprobar su tamaño y el nivel de compresión en disco consultando system.columns:

Query

SELECT
    table,
    formatReadableSize(sum(data_compressed_bytes)) AS compressed_size,
    formatReadableSize(sum(data_uncompressed_bytes)) AS uncompressed_size,
    sum(data_compressed_bytes) / sum(data_uncompressed_bytes) AS compression_ratio
FROM system.columns
WHERE (database = 'forex') AND (table = 'forex')
GROUP BY table
ORDER BY table ASC

Response

   ┌─table─┬─compressed_size─┬─uncompressed_size─┬───compression_ratio─┐
1. │ forex │ 63.69 GiB       │ 280.48 GiB        │ 0.22708227109363446 │
   └───────┴─────────────────┴───────────────────┴─────────────────────┘

A diferencia del formato Arrow en “modo archivo”, que requiere el resultado completo antes de poder leerse, ArrowStream se entrega como una secuencia de lotes de registros que un consumidor puede leer de forma incremental a medida que llegan. Esto lo hace muy adecuado para transmitir el resultado de una consulta directamente a una herramienta de visualización o analítica sin materializar antes el conjunto de datos completo. Para transmitir el resultado, envíe la consulta a través de la interfaz HTTP de ClickHouse con una solicitud POST y lea la respuesta como un flujo Arrow. Desactivamos la compresión de la salida Arrow mediante la opción output_format_arrow_compression_method para que los consumidores puedan decodificar los lotes directamente a medida que se reciben. La salida de ArrowStream es binaria sin procesar, así que, en lugar de imprimirla en la terminal, la canalizamos a un consumidor. El flujo es autodescriptivo (lleva su propio esquema), así que aquí lo canalizamos directamente a clickhouse-local, que lee los lotes entrantes con --input-format ArrowStream y los consulta como una tabla. La tabla forex es grande, así que acotamos la consulta remota con un predicado WHERE y un LIMIT para que este ejemplo sea breve:

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 = 'USD' AND quote = 'CHF'
        ORDER BY datetime ASC
        LIMIT 5
        FORMAT ArrowStream
        SETTINGS output_format_arrow_compression_method='none'" \
  | clickhouse-local --input-format ArrowStream \
      --query "SELECT * FROM table ORDER BY last_update ASC FORMAT PrettyCompact"

Response

   ┌─base_quote─┬─────────────last_update─┬────bid─┬────ask─┬────────────────spread─┐
│ USD.CHF    │ 2000-05-30 17:23:44.000 │  1.688 │ 1.6885 │ 0.0005000829696655273 │
│ USD.CHF    │ 2000-05-30 17:23:46.000 │ 1.6885 │  1.689 │ 0.0004999637603759766 │
│ USD.CHF    │ 2000-05-30 17:23:48.000 │ 1.6886 │ 1.6891 │ 0.0005000829696655273 │
│ USD.CHF    │ 2000-05-30 17:23:49.000 │ 1.6888 │ 1.6893 │ 0.0004999637603759766 │
│ USD.CHF    │ 2000-05-30 17:24:45.000 │  1.689 │ 1.6895 │ 0.0004999637603759766 │
   └────────────┴─────────────────────────┴────────┴────────┴───────────────────────┘

El mismo flujo puede consumirse de forma incremental con cualquier client compatible con Arrow, que lo lee lote por lote en lugar de almacenar en un búfer todo el resultado. Por ejemplo, con la biblioteca Apache Arrow para JavaScript, un RecordBatchReader genera cada lote de registros en cuanto se transmite desde el servidor:

const reader = await RecordBatchReader.from(response);
await reader.open();
for await (const recordBatch of reader) {
    const batchTable = new Table(recordBatch);
    const ipcStream = tableToIPC(batchTable, 'stream');
    const bytes = new Uint8Array(ipcStream);
    table.update(bytes);
}

Para ver una guía completa sobre cómo transmitir datos ArrowStream desde ClickHouse a una visualización en tiempo real con Perspective, consulta la entrada del blog Visualizaciones en tiempo real en streaming con ClickHouse, Apache Arrow y Perspective.

Configuración del formato

ArrowStream comparte la misma configuración de formato que Arrow.

Setting	Description	Default
`input_format_arrow_allow_missing_columns`	Permite columnas faltantes al leer formatos de entrada Arrow	`1`
`input_format_arrow_case_insensitive_column_matching`	No distingue entre 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 del formato Arrow	`0`
`output_format_arrow_compression_method`	Método de compresión del formato de salida Arrow. Códecs compatibles: lz4_frame, zstd, none (sin comprimir)	`lz4_frame`
`output_format_arrow_date_as_uint16`	Escribe valores Date como números simples de 16 bits (se vuelven a leer como UInt16), en lugar de convertirlos al tipo Arrow DATE32 de 32 bits (se vuelven a leer como Date32).	`0`
`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 String de Arrow en lugar de Binary para columnas String	`1`
`output_format_arrow_unsupported_types_as_binary`	Genera los tipos sin conversión como datos binarios sin procesar. Si es false, esos tipos producirán la excepción UNKNOWN_TYPE.	`1`
`output_format_arrow_use_64_bit_indexes_for_dictionary`	Usa siempre enteros de 64 bits para los índices de diccionario en el formato Arrow	`0`
`output_format_arrow_use_signed_indexes_for_dictionary`	Usa enteros con signo para los índices de diccionario en el formato Arrow	`1`

​Descripción

​Ejemplo de uso

​Configuración del formato

Descripción

Ejemplo de uso

Configuración del formato