ArrowStream

Documentación sobre el formato ArrowStream

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─┐
1. │ USD.CHF    │ 2000-05-30 17:23:44.000 │  1.688 │ 1.6885 │ 0.0005000829696655273 │
2. │ USD.CHF    │ 2000-05-30 17:23:46.000 │ 1.6885 │  1.689 │ 0.0004999637603759766 │
3. │ USD.CHF    │ 2000-05-30 17:23:48.000 │ 1.6886 │ 1.6891 │ 0.0005000829696655273 │
4. │ USD.CHF    │ 2000-05-30 17:23:49.000 │ 1.6888 │ 1.6893 │ 0.0004999637603759766 │
5. │ 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