Utiliser les formats natif et binaire dans ClickHouse

Page expliquant comment utiliser les formats natif et binaire dans ClickHouse

ClickHouse prend en charge plusieurs formats binaires, qui offrent de meilleures performances et une utilisation plus efficace de l’espace. Les formats binaires sont également fiables en matière d’encodage des caractères, puisque les données sont enregistrées sous forme binaire.

Nous allons utiliser la table some_data table et les données pour cette démonstration ; n’hésitez pas à reproduire cela sur votre instance ClickHouse.

​

Exportation au format Native de ClickHouse

Le format de données le plus efficace pour exporter et importer des données entre des nœuds ClickHouse est le format Native. L’exportation s’effectue à l’aide de la clause INTO OUTFILE :

SELECT * FROM some_data
INTO OUTFILE 'data.clickhouse' FORMAT Native

Cela créera le fichier data.clickhouse au format Native.

​

Importation depuis le format Native

Pour importer des données, nous pouvons utiliser file() pour les petits fichiers ou à des fins d’exploration :

DESCRIBE file('data.clickhouse', Native);

┌─name──┬─type───┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ path  │ String │              │                    │         │                  │                │
│ month │ Date   │              │                    │         │                  │                │
│ hits  │ UInt32 │              │                    │         │                  │                │
└───────┴────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘

Lorsque vous utilisez la fonction file(), avec ClickHouse Cloud, vous devez exécuter les commandes dans clickhouse client sur la machine où se trouve le fichier. Vous pouvez également utiliser clickhouse-local pour explorer les fichiers localement.

En production, nous utilisons FROM INFILE pour importer des données :

INSERT INTO sometable
FROM INFILE 'data.clickhouse'
FORMAT Native

​

Compression du format Native

Nous pouvons également activer la compression lors de l’export de données au format Native (ainsi que dans la plupart des autres formats) au moyen d’une clause COMPRESSION :

SELECT * FROM some_data
INTO OUTFILE 'data.clickhouse'
COMPRESSION 'lz4'
FORMAT Native

Nous avons utilisé la compression LZ4 pour l’export. Il faudra la spécifier lors de l’import des données :

INSERT INTO sometable
FROM INFILE 'data.clickhouse'
COMPRESSION 'lz4'
FORMAT Native

​

Exportation vers RowBinary

Un autre format binaire pris en charge est RowBinary, qui permet d’importer et d’exporter des données sous forme de lignes encodées en binaire :

SELECT * FROM some_data
INTO OUTFILE 'data.binary' FORMAT RowBinary

Cela génère le fichier data.binary au format binaire par lignes.

​

Explorer les fichiers RowBinary

L’inférence automatique du schéma n’est pas prise en charge pour ce format. Pour l’explorer avant le chargement, nous devons donc définir explicitement le schéma :

SELECT *
FROM file('data.binary', RowBinary, 'path String, month Date, hits UInt32')
LIMIT 5

┌─path───────────────────────────┬──────month─┬─hits─┐
│ Bangor_City_Forest             │ 2015-07-01 │   34 │
│ Alireza_Afzal                  │ 2017-02-01 │   24 │
│ Akhaura-Laksam-Chittagong_Line │ 2015-09-01 │   30 │
│ 1973_National_500              │ 2017-10-01 │   80 │
│ Attachment                     │ 2017-09-01 │ 1356 │
└────────────────────────────────┴────────────┴──────┘

Vous pouvez utiliser RowBinaryWithNames, qui ajoute également une ligne d’en-tête contenant la liste des colonnes. RowBinaryWithNamesAndTypes ajoute aussi une ligne d’en-tête supplémentaire contenant les types de colonnes.

​

Importation à partir de fichiers RowBinary

Pour charger des données depuis un fichier RowBinary, nous pouvons utiliser la clause FROM INFILE :

INSERT INTO sometable
FROM INFILE 'data.binary'
FORMAT RowBinary

​

Importation d’une valeur binaire unique avec RawBLOB

Supposons que nous voulions lire l’intégralité d’un fichier binaire et l’enregistrer dans un champ d’une table. C’est précisément dans ce cas que le format RawBLOB peut être utilisé. Ce format ne peut être utilisé directement qu’avec une table à une seule colonne :

CREATE TABLE images(data String) ENGINE = Memory

Enregistrons un fichier image dans la table images :

cat image.jpg | clickhouse-client -q "INSERT INTO images FORMAT RawBLOB"

Nous pouvons vérifier la longueur du champ data, qui sera égale à la taille du fichier d’origine :

SELECT length(data) FROM images

┌─length(data)─┐
│         6121 │
└──────────────┘

​

Export des données RawBLOB

Ce format peut également être utilisé pour exporter des données à l’aide d’une clause INTO OUTFILE :

SELECT * FROM images LIMIT 1
INTO OUTFILE 'out.jpg'
FORMAT RawBLOB

Notez que nous avons dû utiliser LIMIT 1, car exporter plus d’une valeur créera un fichier corrompu.

​

MessagePack

ClickHouse prend en charge l’importation et l’exportation au format MessagePack via MsgPack. Pour exporter au format MessagePack :

SELECT *
FROM some_data
INTO OUTFILE 'data.msgpk'
FORMAT MsgPack

Pour importer des données à partir d’un fichier MessagePack :

INSERT INTO sometable
FROM INFILE 'data.msgpk'
FORMAT MsgPack

​

Protocol Buffers

Pour travailler avec Protocol Buffers, nous devons d’abord définir un fichier de schéma :

syntax = "proto3";

message MessageType {
  string path = 1;
  date month = 2;
  uint32 hits = 3;
};

Le chemin d’accès à ce fichier de schéma (schema.proto dans notre cas) est défini dans l’option de configuration format_schema pour le format Protobuf :

SELECT * FROM some_data
INTO OUTFILE 'proto.bin'
FORMAT Protobuf
SETTINGS format_schema = 'schema:MessageType'

Cela enregistre les données dans le fichier proto.bin. ClickHouse prend également en charge l’importation de données Protobuf ainsi que de messages imbriqués. Vous pouvez utiliser ProtobufSingle pour traiter un seul message Protocol Buffer (dans ce cas, les délimiteurs de longueur sont omis).

​

Cap’n Proto

Un autre format de sérialisation binaire populaire pris en charge par ClickHouse est Cap’n Proto. Comme avec le format Protobuf, nous devons définir un fichier de schéma (schema.capnp) dans notre exemple :

@0xec8ff1a10aa10dbe;

struct PathStats {
  path @0 :Text;
  month @1 :UInt32;
  hits @2 :UInt32;
}

Nous pouvons maintenant importer et exporter au format CapnProto avec ce schéma :

SELECT
    path,
    CAST(month, 'UInt32') AS month,
    hits
FROM some_data
INTO OUTFILE 'capnp.bin'
FORMAT CapnProto
SETTINGS format_schema = 'schema:PathStats'

Notez que nous avons dû convertir la colonne Date en UInt32 afin d’aligner les types correspondants.

​

Autres formats

ClickHouse prend en charge de nombreux formats, textuels comme binaires, afin de couvrir divers scénarios et plateformes. Découvrez d’autres formats ainsi que différentes façons de les utiliser dans les articles suivants :

• Formats CSV et TSV
• Parquet
• Formats JSON
• Regex et Template
• Formats natifs et binaires
• Formats SQL

Consultez également clickhouse-local — un outil portable complet pour travailler sur des fichiers locaux ou distants sans démarrer ClickHouse server.