Tous les produits
Search

Ce produit

    ApsaraDB for ClickHouse:Importer des données depuis OSS

    Centre de documentation

    ApsaraDB for ClickHouse:Importer des données depuis OSS

    Dernière mise à jour :Aug 11, 2026

    Importez des données depuis Object Storage Service (OSS) vers Alibaba Cloud ClickHouse à l'aide d'un moteur de table ou d'une fonction de table pour interroger, analyser et traiter les journaux.

    Prérequis

    • Activez Object Storage Service (OSS). Pour plus d'informations, consultez la rubrique Activer OSS.

    • Un bucket a été créé dans la même région que Alibaba Cloud ClickHouse. Pour savoir comment créer un bucket, consultez la rubrique Créer un bucket.

    • Le compte utilisé pour accéder à OSS dispose d'autorisations de lecture sur les objets du bucket. Pour plus d'informations, consultez la rubrique Vue d'ensemble.

    Préparation des données

    Enregistrez les données de test suivantes sous le nom test.csv et téléchargez-les sur OSS. Le séparateur de colonne par défaut est une virgule (,). Pour obtenir des instructions de téléchargement, consultez la rubrique Télécharger des fichiers.

    1,yang,32,shanghai,http://example1.com
2,wang,22,beijing,http://example2.com
3,xiao,23,shenzhen,http://example3.com
4,jess,45,hangzhou,http://example4.com
5,jack,14,shanghai,http://example5.com
6,tomy,25,hangzhou,http://example6.com
7,lucy,45,shanghai,http://example7.com
8,tengyin,26,shanghai,http://example8.com
9,wangli,27,shenzhen,http://example9.com
10,xiaohua,37,shanghai,http://example10.com

    Étapes

    1. Connectez-vous au cluster Alibaba Cloud ClickHouse. Pour plus d'informations, consultez la rubrique Se connecter à un cluster.

    2. Créez une table locale nommée oss_test_tbl_local.

      Important

      • Le schéma de la table Alibaba Cloud ClickHouse doit correspondre au schéma de la table externe OSS et au format des données présentes dans OSS. Traitez soigneusement les champs nuls afin d'éviter les échecs d'analyse et les exceptions au niveau du cluster.

      • Sélectionnez l'instruction CREATE TABLE appropriée en fonction de la configuration des réplicas de votre cluster. Vous pouvez consulter la configuration des réplicas sur la page Cluster Information dans la section Cluster Properties de la console.

      • Choisissez un moteur de table selon vos besoins métier. Pour plus d'informations, consultez la rubrique Moteurs de table.

      Single-replica edition

      CREATE TABLE oss_test_tbl_local ON CLUSTER default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = MergeTree()
ORDER BY id;

      Double-replica edition

      CREATE TABLE oss_test_tbl_local ON CLUSTER default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = ReplicatedMergeTree('/clickhouse/tables/{database}/{table}/{shard}', '{replica}')
ORDER BY id;

    3. (Facultatif) Créez une table distribuée nommée oss_test_tbl_distributed.

      Remarque

      Créez une table distribuée si vous souhaitez répartir les données sur toutes les tables locales du cluster.

      CREATE TABLE oss_test_tbl_distributed ON CLUSTER default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = Distributed(default, default, oss_test_tbl_local, rand());

    4. Importez les données depuis OSS vers Alibaba Cloud ClickHouse.

      Alibaba Cloud ClickHouse prend en charge deux méthodes pour importer des données depuis OSS : les moteurs de table et les fonctions de table.

      Important

      Sélectionnez l'instruction appropriée en fonction de la version de votre cluster. Vous pouvez consulter la version sur la page Cluster Information dans la section Cluster Properties de la console.

      Méthode 1 : Utiliser un moteur de table

      1. Créez une table externe OSS nommée oss_test_tbl.

        Syntaxe pour les versions antérieures à 22,8

        CREATE TABLE <table_name> [ON CLUSTER cluster]
(
'col_name1' col_type1,
'col_name2' col_type2,
...
)
ENGINE = OSS('<oss-endpoint>', '<access-key-id>', '<access-key-secret>', '<oss-file-path>', '<file-format-name>');

        Syntaxe pour les versions 22,8 et ultérieures

        CREATE TABLE <table_name> [ON CLUSTER cluster]
(
'col_name1' col_type1,
'col_name2' col_type2,
...
)
ENGINE = OSS('https://<BucketName>.<oss-endpoint>/<file-name>', '<access-key-id>', '<access-key-secret>', '<file-format-name>');

        Paramètres :

        Paramètre

        Description

        table_name

        Nom de la table.

        ON CLUSTER

        Crée une table locale sur chaque nœud. Définissez ce paramètre sur ON CLUSTER default.

        col_name1,col_name2

        Noms des colonnes.

        col_type1,col_type2

        Types de données des colonnes.

        Important

        Le schéma de la table externe OSS doit correspondre aux données présentes dans OSS.

        BucketName

        Nom du bucket.

        oss-endpoint

        Endpoint utilisé pour accéder à OSS. Pour plus d'informations, consultez la rubrique Régions et endpoints.

        Important

        Assurez-vous que le bucket et votre cluster Alibaba Cloud ClickHouse se trouvent dans la même région, et accédez à OSS via un réseau privé virtuel (VPC).

        file-name

        Nom du fichier.

        access-key-id

        AccessKey ID utilisé pour accéder aux données dans OSS. Pour savoir comment obtenir un AccessKey ID, consultez la rubrique Obtenir une paire AccessKey.

        access-key-secret

        AccessKey Secret utilisé pour accéder aux données dans OSS. Pour savoir comment obtenir un AccessKey Secret, consultez la rubrique Obtenir une paire AccessKey.

        oss-file-path

        Chemin de stockage du fichier. Le chemin est généralement au format oss://<bucket-name>/<path-to-file>.

        Remarque

        Le paramètre oss-file-path prend en charge la correspondance floue à l'aide de caractères génériques. Pour plus d'informations, consultez la rubrique Correspondance par caractère générique pour les chemins de stockage OSS.

        file-format-name

        Format du fichier. Cette rubrique utilise CSV comme exemple.

        Exemples d'instructions :

        Exemple pour les versions antérieures à 22,8

        CREATE TABLE oss_test_tbl on cluster default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = OSS('oss-cn-shanghai-internal.aliyuncs.com', 'LTAI****************', 'yourAccessKeySecret', 'oss://testBucketName/test.csv', 'CSV');

        Exemple pour les versions 22,8 et ultérieures

        CREATE TABLE oss_test_tbl on cluster default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = OSS('http://testBucketName.oss-cn-shanghai-internal.aliyuncs.com/test.csv', 'STS.****************', 'STS.****************','CSV')

      2. Importez les données de la table externe OSS oss_test_tbl vers la table distribuée oss_test_tbl_distributed.

        Remarque

        Si vous devez importer des données uniquement vers une table locale, remplacez le nom de la table distribuée par le nom de la table locale dans l'instruction INSERT.

        INSERT INTO oss_test_tbl_distributed SELECT * FROM oss_test_tbl;

        Si votre fichier CSV utilise un délimiteur autre qu'une virgule (,), utilisez le paramètre format_csv_delimiter dans l'instruction INSERT pour le spécifier. Par exemple, si le fichier utilise une barre verticale (|) comme délimiteur, exécutez l'instruction suivante :

        INSERT INTO oss_test_tbl_distributed SELECT * FROM oss_test_tbl settings format_csv_delimiter='|';

      Méthode 2 : Utiliser une fonction de table

      Syntaxe pour les versions antérieures à 22,8

      INSERT INTO <table_name> SELECT * FROM oss('<oss-endpoint>', '<access-key-id>', '<access-key-secret>', '<oss-file-path>', '<file-format-name>', '<col_name> <col_type>(,...)');

      Syntaxe pour les versions 22,8 et ultérieures

      INSERT INTO <table_name> SELECT * FROM oss('https://<BucketName>.<oss-endpoint>/<file-name>','<access-key-id>', '<access-key-secret>', '<file-format-name>', '<col_name> <col_type>(,...)');

      Pour plus d'informations sur les paramètres, consultez la section Descriptions des paramètres.

      Exemples d'instructions :

      Exemple pour les versions antérieures à 22,8

      INSERT INTO oss_test_tbl_distributed SELECT * FROM oss('oss-cn-shanghai-internal.aliyuncs.com', 'LTAI****************', 'yourAccessKeySecret', 'oss://testBucketName/test.csv', 'CSV', 'id UInt8, user_name String, age UInt16, city String, access_url String');

      Exemple pour les versions 22,8 et ultérieures

      INSERT INTO oss_test_tbl_distributed SELECT * FROM oss('http://testBucketName.oss-cn-shanghai-internal.aliyuncs.com/test.csv', 'STS.****************', 'STS.****************', 'CSV', 'id UInt8, user_name String, age UInt16, city String, access_url String');

      Si votre fichier CSV utilise un délimiteur autre qu'une virgule (,), utilisez le paramètre format_csv_delimiter dans l'instruction INSERT pour le spécifier. Par exemple, si le fichier utilise une barre verticale (|) comme délimiteur, exécutez l'instruction suivante :

      INSERT INTO oss_test_tbl_distributed SELECT * FROM oss('<oss-endpoint>', '<access-key-id>', '<access-key-secret>', '<oss-file-path>', '<file-format-name>',  '<col_name> <col_type>(,...)') settings format_csv_delimiter='|';

    5. Interrogez la table distribuée oss_test_tbl_distributed pour vérifier l'importation des données.

      SELECT * FROM oss_test_tbl_distributed;

      Résultat attendu :

      ┌─id─┬─user_name─┬──age──┬───city─────┬─────access_url────────┐
│  1 │  yang     │   32  │  shanghai  │  http://example1.com  │
│  2 │  wang     │   22  │  beijing   │  http://example2.com  │
│  3 │  xiao     │   23  │  shenzhen  │  http://example3.com  │
│  4 │  jess     │   45  │  hangzhou  │  http://example4.com  │
│  5 │  jack     │   14  │  shanghai  │  http://example5.com  │
│  6 │  tomy     │   25  │  hangzhou  │  http://example6.com  │
│  7 │  lucy     │   45  │  shanghai  │  http://example7.com  │
│  8 │  tengyin  │   26  │  shanghai  │  http://example8.com  │
│  9 │  wangli   │   27  │  shenzhen  │  http://example9.com  │
│ 10 │  xiaohua  │   37  │  shanghai  │  http://example10.com │
└────┴───────────┴───────┴────────────┴───────────────────────┘

    Correspondance par caractère générique pour les chemins de stockage OSS

    Pour simplifier l'analyse de plusieurs petits fichiers partageant une convention de nommage, le paramètre oss-file-path prend en charge les caractères génériques suivants :

    • * : Correspond à tout nom de fichier ou de répertoire. Par exemple, /dir/* correspond à tous les fichiers du répertoire /dir.

    • {x,y,z} : Correspond à toute valeur incluse entre les accolades. Par exemple, file_{x,y,z} correspond à file_x, file_y ou file_z.

    • {num1..num2} : Correspond à toute valeur dans la plage étendue de num1 à num2. Par exemple, file_{1..3} correspond à file_1, file_2 et file_3.

    • ? : Correspond à un seul caractère quelconque. Par exemple, file_? correspond à file_a, file_b, file_c, etc.

    Exemple

    Les fichiers téléchargés utilisent la structure de répertoire suivante.

    oss://testBucketName/
               doc-data/
                    oss-import/
                        small_files/
                            access_log_csv_1.txt
                            access_log_csv_2.txt
                            access_log_csv_3.txt

    Exemples :

    • oss://testBucketName/doc-data/oss-import/small_files/*

    • oss://testBucketName/doc-data/oss-import/small_files/access*

    • oss://testBucketName/doc-data/oss-import/small_files/access_log_csv_{1,2,3}.txt

    • oss://testBucketName/doc-data/oss-import/*/access_log_csv_{1,2,3}.txt

    • oss://testBucketName/doc-data/oss-import//

    • oss://testBucketName/doc-data/oss-import/*/access_log_csv_{1..3}.txt

    • oss://testBucketName/doc-data/oss-import/*/access_log_csv_?.txt