すべてのプロダクト
Search

このプロダクト

    ApsaraDB for ClickHouse:OSS からのインポート

    ドキュメントセンター

    ApsaraDB for ClickHouse:OSS からのインポート

    最終更新日:Mar 10, 2026

    テーブルエンジンまたはテーブル関数を使用して、Object Storage Service (OSS) から ApsaraDB for ClickHouse にデータをインポートできます。これにより、ログクエリ、分析、処理などの操作を実行できます。このトピックでは、OSS から ApsaraDB for ClickHouse にデータをインポートする方法について説明します。

    前提条件

    • OSS サービスが有効化されていること。詳細については、「OSS の有効化」をご参照ください。

    • バケットが作成されていること。バケットは ApsaraDB for ClickHouse クラスターと同じリージョンにある必要があります。詳細については、「バケットの作成」をご参照ください。

    • OSS へのアクセスに使用するアカウントに、OSS オブジェクトに対する読み取り権限があること。詳細については、「権限とアクセスの制御の概要」をご参照ください。

    データ準備

    次のテストデータを test.csv という名前のファイルとして保存し、そのファイルを OSS にアップロードします。ApsaraDB for ClickHouse は、データインポートのデフォルトの列区切り文字としてカンマ (,) を使用します。ファイルのアップロード方法の詳細については、「ファイルのアップロード」をご参照ください。

    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

    操作手順

    1. ApsaraDB for ClickHouse クラスターに接続します。詳細については、「クラスターへの接続」をご参照ください。

    2. oss_test_tbl_local という名前のローカルテーブルを作成します。

      重要

      • ApsaraDB for ClickHouse テーブルのスキーマは、OSS 外部テーブルのスキーマと一致し、OSS のデータ形式と互換性がある必要があります。データ解析の失敗によるクラスターの例外を防ぐために、Null 許容フィールドには特に注意してください。

      • ご利用のクラスターのレプリカ構成に基づいて、適切な CREATE TABLE 文を選択してください。レプリカ構成は、コンソールの [クラスター情報] ページの [クラスタープロパティ] セクションで確認できます。

      • 要件に基づいてテーブルエンジンを選択してください。テーブルエンジンの詳細については、「テーブルエンジン」をご参照ください。

      単一レプリカクラスター

      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;

      デュアルレプリカクラスター

      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. (任意) oss_test_tbl_distributed という名前の分散テーブルを作成します。

      説明

      コレクション内のすべてのローカルテーブルに同時にデータを分散させたい場合は、分散テーブルを作成します。

      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. OSS から ApsaraDB for ClickHouse にデータをインポートします。

      テーブルエンジンまたはテーブル関数を使用して、OSS から ApsaraDB for ClickHouse にデータをインポートできます。

      重要

      ご利用のクラスターのバージョンに基づいて、適切な CREATE TABLE 文を選択してください。バージョンは、コンソールの [クラスター情報] ページの [クラスタープロパティ] セクションで確認できます。

      方法 1：テーブルエンジンを使用したデータインポート

      1. oss_test_tbl という名前の OSS 外部テーブルを作成します。

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

        バージョン 22.8 以降の構文

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

        パラメーターは次のとおりです。

        パラメーター名

        説明

        table_name

        テーブルの名前です。

        ON CLUSTER cluster

        各ノードにローカルテーブルを作成します。値は ON CLUSTER default に固定されます。

        col_name1, col_name2

        カラムの名前です。

        col_type1, col_type2

        カラムのデータの型です。

        重要

        OSS 外部テーブルのスキーマとデータの型は、OSS 内のデータと一致している必要があります。

        BucketName

        バケットの名前です。

        oss-endpoint

        OSS にアクセスするために使用するエンドポイントです。エンドポイントの取得方法の詳細については、「リージョンとエンドポイント」をご参照ください。

        重要

        バケットと ApsaraDB for ClickHouse クラスターが同じリージョンにあることを確認してください。OSS へのアクセスには Alibaba Cloud VPC を使用します。

        file-name

        ファイルの名前です。

        access-key-id

        OSS 内のデータにアクセスするために使用する AccessKey ID です。AccessKey ペアの取得方法の詳細については、「AccessKey ペアの取得」をご参照ください。

        access-key-secret

        OSS 内のデータにアクセスするために使用する AccessKey Secret です。AccessKey ペアの取得方法の詳細については、「AccessKey ペアの取得」をご参照ください。

        oss-file-path

        ファイルのストレージパスです。パスは通常、`oss://<bucket-name>/<path-to-file>` のフォーマットです。

        説明

        `oss-file-path` パラメーターは、ワイルドカードを使用したあいまい一致をサポートしています。詳細については、「ワイルドカードを使用した OSS ストレージパスのあいまい一致」をご参照ください。

        file-format-name

        ファイルのフォーマットです。このトピックでは、フォーマットは CSV です。

        例：

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

        バージョン 22.8 以降の例

        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. OSS 外部テーブル oss_test_tbl から分散テーブル oss_test_tbl_distributed にデータをインポートします。

        説明

        OSS からローカルテーブルにのみデータをインポートする必要がある場合は、インポート文の分散テーブル名をローカルテーブル名に置き換えてください。

        INSERT INTO oss_test_tbl_distributed SELECT * FROM oss_test_tbl;

        インポートされた CSV ファイルがカンマ (,) 以外の列区切り文字を使用している場合は、インポート文で format_csv_delimiter を使用して区切り文字を指定する必要があります。たとえば、CSV ファイルの列が縦棒 (|) で区切られている場合は、次のコマンドを実行します：

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

      方法 2：テーブル関数を使用したデータインポート

      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>(,...)');

      バージョン 22.8 以降の構文

      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>(,...)');

      パラメーターの詳細については、「パラメーターの説明」をご参照ください。

      例：

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

      バージョン 22.8 以降の例

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

      インポートされた CSV ファイルがカンマ (,) 以外の列区切り文字を使用している場合は、インポート文で format_csv_delimiter を使用して区切り文字を指定する必要があります。たとえば、CSV ファイルの列が縦棒 (|) で区切られている場合は、次の文を使用します。

      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. 分散テーブル oss_test_tbl_distributed のデータをクエリして、OSS からのデータが ApsaraDB for ClickHouse にインポートされたことを確認します。

      SELECT * FROM oss_test_tbl_distributed;

      次の結果が返されます：

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

    ワイルドカードを使用した OSS ストレージパスのあいまい一致

    OSS は、同じ命名規則に従う複数の小さなファイルを保存することがよくあります。これらのファイルの分析を簡素化するために、oss-file-path パラメーターは、次のワイルドカードによるあいまい一致をサポートしています。

    • *：任意のファイル名またはフォルダ名に一致します。たとえば、/dir/* は /dir フォルダ内のすべてのファイルに一致します。

    • {x, y, z}：中括弧内のいずれかの値に一致します。たとえば、file_{x,y,z} は file_x、file_y、または file_z に一致します。

    • {num1..num2}：num1 から num2 までの展開された範囲内の任意の値に一致します。たとえば、file_{1..3} は file_1、file_2、または file_3 に一致します。

    • ?：任意の 1 文字に一致します。たとえば、file_? は file_a、file_b、および file_c に一致します。

    例

    アップロードのフォルダ構造は次のとおりです。

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

    oss-file-path パラメーターの値の例をいくつか示します。

    • 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