すべてのプロダクト
Search

このプロダクト

    ApsaraDB for ClickHouse:OSS からデータをインポートする

    ドキュメントセンター

    ApsaraDB for ClickHouse:OSS からデータをインポートする

    最終更新日:Apr 07, 2025

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

    前提条件

    • OSS がアクティブ化されていること。 OSS をアクティブ化する方法の詳細については、「OSS をアクティブ化する」(OSS コンソールを使用して開始するトピック内) をご参照ください。

    • バケットが作成されていること。バケットと ApsaraDB for ClickHouse クラスタは同じリージョンにデプロイされていること。バケットの作成方法の詳細については、「バケットを作成する」(OSS コンソールを使用して開始するトピック内) をご参照ください。

    • OSS バケットへのアクセスに使用する Alibaba Cloud アカウントに、バケット内のオブジェクトに対する読み取り権限が付与されていること。権限の付与方法の詳細については、「概要」をご参照ください。

    データの準備

    test.csv という名前の CSV ファイルに次のテストデータを保存し、ファイルを OSS にアップロードします。データをインポートする場合、ApsaraDB for ClickHouse クラスタでサポートされるデフォルトの列区切り文字はカンマ (,) です。データのアップロード方法の詳細については、「オブジェクトをアップロードする」(OSS コンソールを使用して開始するトピック内) をご参照ください。

    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 クラスタに接続します。詳細については、「ApsaraDB for ClickHouse クラスタに接続する」をご参照ください。

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

      重要

      • ApsaraDB for ClickHouse テーブルは、OSS 外部テーブルと同じスキーマを使用し、OSS 外部テーブルのデータ形式 (特に null フィールドの場合) と互換性がある必要があります。これにより、データ解析の失敗によって発生するクラスタの問題を防ぐことができます。

      • ローカルテーブルを作成するには、ApsaraDB for ClickHouse クラスタのエディションに基づいてステートメントを実行する必要があります。左側のナビゲーションウィンドウで [クラスタ情報] をクリックし、[クラスタのプロパティ] セクションでクラスタのエディションを確認できます。

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

      単一レプリカエディションのクラスタでローカルテーブルを作成するために使用するステートメント

      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 にデータをインポートできます。

      重要

      OSS 外部テーブルを作成するには、クラスタのカーネルバージョンに基づいてステートメントを実行する必要があります。左側のナビゲーションウィンドウで [クラスタ情報] をクリックし、[クラスタのプロパティ] セクションでクラスタのカーネルバージョンを確認できます。

      方法 1: テーブルエンジンを使用して OSS からデータをインポートする

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

        バージョン 22.8 より前のクラスタで OSS 外部テーブルを作成するために使用する構文

        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 以降のクラスタで OSS 外部テーブルを作成するために使用する構文

        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 内のデータを含む CSV ファイルのスキーマに対応している必要があります。

        BucketName

        バケットの名前。

        oss-endpoint

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

        重要

        バケットと ApsaraDB for ClickHouse クラスタが同じリージョンにデプロイされており、VPC (Virtual Private Cloud) 経由で OSS にアクセスできることを確認してください。

        file-name

        ファイルの名前。

        access-key-id

        OSS 内のデータへのアクセスに使用する AccessKey ID。詳細については、「AccessKey ペアを取得するにはどうすればよいですか。」をご参照ください。

        access-key-secret

        OSS 内のデータへのアクセスに使用する AccessKey シークレット。詳細については、「AccessKey ペアを取得するにはどうすればよいですか。」をご参照ください。

        oss-file-path

        アップロードした CSV ファイルのストレージパス。パスは oss://<bucket-name>/<path-to-file> 形式です。

        説明

        oss-file-path パラメータは、ワイルドカード文字を使用するあいまい一致をサポートしています。詳細については、このトピックの「ワイルドカード文字を使用して OSS 内のストレージパスをあいまい一致させる」セクションをご参照ください。

        file-format-name

        ファイルの形式。このトピックでは、CSV 形式が使用されます。

        ステートメントの例:

        バージョン 22.8 より前のクラスタで OSS 外部テーブルを作成するために使用するステートメントの例

        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 以降のクラスタで OSS 外部テーブルを作成するために使用するステートメントの例

        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 ステートメントの分散テーブルの名前をローカルテーブルの名前に置き換えます。

        INSERT INTO oss_test_tbl_distributed SELECT * FROM oss_test_tbl;

        インポートする CSV ファイルの列区切り文字としてカンマ (,) が使用されていない場合は、INSERT INTO ステートメントで format_csv_delimiter パラメータを使用して別の列区切り文字を指定する必要があります。たとえば、CSV ファイルの列区切り文字として縦棒 (|) が使用されている場合は、次のステートメントを実行します。

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

      方法 2: テーブル関数を使用して OSS からデータをインポートする

      バージョン 22.8 より前のクラスタに OSS からデータをインポートするために使用する構文OSS からバージョン 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 以降のクラスタに OSS からデータをインポートするために使用する構文

      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 より前のクラスタに OSS からデータをインポートするために使用するステートメントの例

      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 以降のクラスタに OSS からデータをインポートするために使用するステートメントの例

      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 ファイルの列区切り文字としてカンマ (,) が使用されていない場合は、INSERT INTO ステートメントで 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}: 最小値、最大値、またはその間の値と一致します。たとえば、file_{1..3} は file_1、file_2、または file_3 と一致します。

    • ?: ランダムな文字と一致します。たとえば、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