Arrow

Entrée	Sortie	Alias
✔	✔

Description

Apache Arrow propose deux formats de stockage en colonnes intégrés. ClickHouse prend en charge les opérations de lecture et d’écriture pour ces formats. Arrow est le format « mode fichier » d’Apache Arrow, conçu pour un accès aléatoire en mémoire.

Correspondance des types de données

Le tableau ci-dessous présente les types de données pris en charge et leur correspondance avec les types de données de ClickHouse dans les requêtes INSERT et SELECT.

Type de données Arrow (`INSERT`)	Type de données ClickHouse	Type de données 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 (Nanoseconde/Microseconde/Milliseconde/Seconde)	`DURATION`
`INT64`	Interval (Minute/Heure/Jour/Semaine/Mois/Trimestre/Année)	`INT64`

Les Array peuvent être imbriqués et accepter comme argument une valeur de type Nullable. Les types Tuple et Map peuvent également être imbriqués. Le type DICTIONARY est pris en charge pour les requêtes INSERT et, pour les requêtes SELECT, le paramètre output_format_arrow_low_cardinality_as_dictionary permet de restituer le type LowCardinality sous forme de type DICTIONARY. Notez qu’il peut y avoir des valeurs inutilisées dans le dictionnaire LowCardinality, ce qui peut se traduire par des valeurs inutilisées dans le DICTIONARY Arrow en sortie. Types de données Arrow non pris en charge :

JSON
ENUM.

Les types de données des colonnes de la table ClickHouse n’ont pas besoin de correspondre aux champs de données Arrow correspondants. Lors de l’insertion de données, ClickHouse interprète les types de données conformément au tableau ci-dessus, puis convertit les données dans le type de données défini pour la colonne de la table ClickHouse.

Exemple d’utilisation

Dans l’exemple ci-dessous, nous utilisons le jeu de données forex disponible dans le ClickHouse SQL playground.

Sélection des données

Nous sélectionnons une journée de taux de change EUR/USD dans le Playground et l’enregistrons dans un fichier local forex_eurusd.arrow. Nous interrogeons le Playground via l’interface HTTP, où le host est sql-clickhouse.clickhouse.com et l’utilisateur est demo (qui n’a pas de mot de passe) :

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

Lecture du fichier

Nous pouvons maintenant relire le fichier Arrow local avec clickhouse-local à l’aide de la fonction de table file. Le fichier est auto-descriptif, donc le format Arrow infère automatiquement le schéma :

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

Insertion de données

Pour charger un fichier Arrow dans une table ClickHouse, redirigez-le vers clickhouse-client avec FORMAT Arrow :

cat forex_eurusd.arrow | clickhouse-client --query="INSERT INTO some_table FORMAT Arrow"

Paramètres du format

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 du format de sortie Arrow. Codecs pris en charge : lz4_frame, zstd, none (non compressé)	`lz4_frame`
`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`	Produire le type LowCardinality en tant que type Arrow Dictionary	`0`
`output_format_arrow_record_batch_size`	Nombre cible de lignes par lot d’enregistrements lors de la combinaison de petits blocs. La mise en tampon peut accroître l’utilisation de la mémoire et retarder le premier lot jusqu’à la fin de la requête. `0` désactive la cible de lignes.	`0`
`output_format_arrow_record_batch_size_bytes`	Nombre cible d’octets de données de blocs accumulées par lot d’enregistrements. La mise en tampon peut accroître l’utilisation de la mémoire et retarder le premier lot jusqu’à la fin de la requête. `0` désactive la cible d’octets.	`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`	Ce qui doit être produit pour un type qui n’a pas d’équivalent Arrow (par ex. `JSON`, `Dynamic`, `QBit`, `AggregateFunction`) : `throw`, `text` (une valeur `serializeText` par ligne, dans le type Arrow qu’utiliserait une colonne `String`) ou `binary` (une valeur `serializeBinary` par ligne, sous forme de `Binary` Arrow). Une `AggregateFunction` est également `Binary` en mode `text`, car sa forme textuelle est l’état d’agrégat brut.	`binary`
`output_format_arrow_unsupported_types_as_binary`	Remplacé par `output_format_arrow_unsupported_types` : `0` signifie `throw`, `1` signifie `binary`. Consulté uniquement tant que ce paramètre conserve sa valeur par défaut.	`1`
`output_format_arrow_use_64_bit_indexes_for_dictionary`	Toujours utiliser des entiers 64 bits pour les index de dictionnaire au format Arrow	`0`
`output_format_arrow_use_signed_indexes_for_dictionary`	Utiliser des entiers signés pour les index de dictionnaire au format Arrow	`1`

Référence SQL

Types de données

Moteurs

Fonctions

Formats

Paramètres

Tables système

Lacs de données

Description

Correspondance des types de données

Exemple d’utilisation

Sélection des données

Lecture du fichier

Insertion de données

Paramètres du format

​Description

​Correspondance des types de données

​Exemple d’utilisation

​Sélection des données

​Lecture du fichier

​Insertion de données

​Paramètres du format

Description

Correspondance des types de données

Exemple d’utilisation

Sélection des données

Lecture du fichier

Insertion de données

Paramètres du format