ArrowStream

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

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 :

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

   ┌─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"

   ┌─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.

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