ArrowStream

Documentation du format ArrowStream

Entrée	Sortie	Alias
✔	✔

​

Description

ArrowStream est le format « mode flux » d’Apache Arrow. Il est conçu pour le traitement des flux en mémoire.

​

Exemple d’utilisation

Dans l’exemple ci-dessous, nous utilisons le dataset forex, disponible dans le ClickHouse SQL playground. Vous pouvez vous y connecter à distance avec clickhouse-client, en utilisant l’hôte sql-clickhouse.clickhouse.com et l’utilisateur demo (qui n’a pas de mot de passe). La table forex se trouve dans la base de données forex ; nous la sélectionnons donc comme base de données par défaut :

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

La table forex stocke les taux de change. Nous pouvons examiner sa taille et son taux de compression sur disque en interrogeant 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 │
   └───────┴─────────────────┴───────────────────┴─────────────────────┘

Contrairement au format Arrow en “mode fichier”, qui nécessite d’attendre le résultat complet avant de pouvoir le lire, ArrowStream est fourni sous la forme d’une séquence de lots d’enregistrements qu’un consommateur peut lire de façon incrémentielle, au fur et à mesure de leur arrivée. Il se prête donc particulièrement bien au streaming d’un résultat de la requête directement vers un outil de visualisation ou d’analyse, sans devoir d’abord matérialiser l’ensemble du jeu de données.

Pour diffuser le résultat, envoyez la requête via l’interface HTTP de ClickHouse avec une requête POST et lisez la réponse comme un flux Arrow. Nous désactivons la compression de la sortie Arrow via le paramètre output_format_arrow_compression_method afin que les consommateurs puissent décoder directement les lots à mesure de leur réception.

La sortie ArrowStream est du binaire brut, donc au lieu de l’afficher dans le terminal, nous la redirigeons vers un consommateur. Le flux est auto-descriptif (il transporte son propre schéma), donc ici nous le redirigeons directement vers clickhouse-local, qui lit les lots entrants avec --input-format ArrowStream et permet de les interroger comme une table. La table forex est volumineuse, nous limitons donc la requête distante avec un prédicat WHERE et un LIMIT afin de garder cet exemple concis :

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 │
   └────────────┴─────────────────────────┴────────┴────────┴───────────────────────┘

Le même flux peut être consommé progressivement par n’importe quel client compatible avec Arrow, qui le lit lot par lot plutôt que de mettre en mémoire tampon l’intégralité du résultat. Par exemple, en utilisant la bibliothèque JavaScript Apache Arrow, un RecordBatchReader produit chaque lot d’enregistrements dès qu’il est diffusé en streaming par le serveur :

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);
}

Pour un guide complet sur la diffusion en continu de données ArrowStream de ClickHouse vers une visualisation en temps réel avec Perspective, consultez l’article de blog Visualisations en temps réel en streaming avec ClickHouse, Apache Arrow et Perspective.

​

Paramètres du format

ArrowStream utilise les mêmes paramètres de format que le format Arrow.

Paramètre	Description	Valeur par défaut
input_format_arrow_allow_missing_columns	Autoriser les colonnes manquantes lors de la lecture des formats d’entrée Arrow	1
input_format_arrow_case_insensitive_column_matching	Ignorer la casse lors de la correspondance entre les colonnes Arrow et les colonnes CH.	0
input_format_arrow_import_nested	Paramètre obsolète, sans effet.	0
input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference	Ignorer les colonnes dont les types ne sont pas pris en charge lors de l’inférence de schéma pour le format Arrow	0
output_format_arrow_compression_method	Méthode de compression pour le format de sortie Arrow. Codecs pris en charge : lz4_frame, zstd, none (non compressé)	lz4_frame
output_format_arrow_date_as_uint16	Écrire les valeurs Date comme de simples nombres 16 bits (relus comme UInt16), au lieu de les convertir en type Arrow DATE32 32 bits (relu comme Date32).	0
output_format_arrow_fixed_string_as_fixed_byte_array	Utiliser le type Arrow FIXED_SIZE_BINARY au lieu de Binary pour les colonnes FixedString.	1
output_format_arrow_low_cardinality_as_dictionary	Sortir le type LowCardinality sous forme de type Arrow Dictionary	0
output_format_arrow_string_as_string	Utiliser le type Arrow String au lieu de Binary pour les colonnes String	1
output_format_arrow_unsupported_types_as_binary	Produire sous forme de données binaires brutes les types qui n’ont pas de conversion. Si false, ces types déclenchent une exception UNKNOWN_TYPE.	1
output_format_arrow_use_64_bit_indexes_for_dictionary	Toujours utiliser des entiers 64 bits pour les indices de dictionnaire au format Arrow	0
output_format_arrow_use_signed_indexes_for_dictionary	Utiliser des entiers signés pour les indices de dictionnaire au format Arrow	1