ApsaraDB for ClickHouse:外部テーブルを使用した OSS データへのアクセス

Enterprise Edition または Community-compatible Edition v22.8 以降

Community-compatible Edition v21.8 以前

1. データベースへのログイン

   1. ApsaraDB for ClickHouse コンソールにログインします。

   2. クラスターリスト ページで、Community Edition インスタンスのリスト タブをクリックし、対象クラスターの ID をクリックします。

   3. クラスター情報 ページで、右上の ログインデータベース をクリックします。

   4. [インスタンスにログイン] ダイアログボックスで、データベースアカウントとパスワードを入力し、[ログイン] をクリックします。

2. OSS 外部テーブルの作成

   テーブルを作成するための構文は次のとおりです。

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

   パラメーター：

   パラメーター名	説明	例
   table_name	テーブル名。	oss_test_tb
   col_name1,col_name2	列名。	user_name
   col_type1,col_type2	列の型。 重要 OSS 外部テーブルの構造は、OSS データと一致している必要があります。	String
   oss-endpoint	VPC プライベートネットワーク経由で ECS インスタンスにアクセスするために使用されるエンドポイント。詳細については、「リージョンとエンドポイント」をご参照ください。 重要 OSS バケットとご利用の ApsaraDB for ClickHouse クラスターが同じリージョンにあることを確認してください。	oss-cn-hangzhou-internal.aliyuncs.com
   access-key-id	OSS データへのアクセスに使用される RAM ユーザーの AccessKey ID。	yourAccessKeyID
   access-key-secret	OSS データへのアクセスに使用される RAM ユーザーの AccessKey Secret。 既存の AccessKey を使用するか、新しい AccessKey を作成します。詳細については、「AccessKey の作成」をご参照ください。 重要 セキュリティ上の脅威を軽減するため、AccessKey Secret は作成時にのみ表示され、後から取得することはできません。安全な場所に保管してください。	yourAccessKeySecret
   oss-file-path	オブジェクトのストレージパス。形式は通常 oss://<bucket-name>/<path-to-file> です。 説明 oss-file-path パラメーターは、ワイルドカード文字を使用したあいまい一致をサポートしています。詳細については、「ワイルドカード文字を使用した OSS ストレージパスのあいまい一致」をご参照ください。	oss://ck-test-oss/test.csv
   file-format-name	ファイル形式 重要 このパラメーターは、「ClickHouse がサポートするファイル形式」に記載されているとおりに正確に指定する必要があります。名前は大文字と小文字が区別されます。	CSV

   例：

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

3. OSS データのクエリ

   SELECT * FROM oss_test_tb;

   結果は次のとおりです。

   +--------------+---------------------+---------------+----------------+----------------------+
   | id           | user_name           | age           | city           | access_url           |
   +--------------+---------------------+---------------+----------------+----------------------+
   | 1           | tick                | 32            | shanghai       | http://example.com   |
   +--------------+---------------------+---------------+----------------+----------------------+
   Returned rows: [1], Time elapsed: [183ms]

Enterprise Edition または Community-compatible Edition v22.8 以降

1. データベースへのログイン

   1. ApsaraDB for ClickHouse コンソールにログインします。

   2. クラスターリスト ページで、Community Edition インスタンスのリスト タブまたは Enterprise Edition インスタンスのリスト タブを選択し、対象クラスターの ID をクリックします。

   3. クラスター情報 ページで、右上の ログインデータベース をクリックします。

   4. [インスタンスにログイン] ダイアログボックスで、データベースアカウントとパスワードを入力し、[ログイン] をクリックします。

2. テーブル関数を使用したデータのクエリ

   構文：

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

   パラメーターは、OSS 外部テーブルを作成する場合と同じです。詳細については、「パラメーター」をご参照ください。

   例：

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

   結果は次のとおりです。

   +--------------+---------------------+---------------+----------------+----------------------+
   | id           | user_name           | age           | city           | access_url           |
   +--------------+---------------------+---------------+----------------+----------------------+
   | 1           | tick                | 32            | shanghai       | http://example.com   |
   +--------------+---------------------+---------------+----------------+----------------------+
   Returned rows: [1], Time elapsed: [183ms]

Community-compatible Edition v21.8 以前

1. データベースへのログイン

   1. ApsaraDB for ClickHouse コンソールにログインします。

   2. クラスターリスト ページで、Community Edition インスタンスのリスト タブをクリックし、対象クラスターの ID をクリックします。

   3. クラスター情報 ページで、右上の ログインデータベース をクリックします。

   4. [インスタンスにログイン] ダイアログボックスで、データベースアカウントとパスワードを入力し、[ログイン] をクリックします。

2. テーブル関数を使用したデータのクエリ

   構文：

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

   パラメーターは、OSS 外部テーブルを作成する場合と同じです。詳細については、「パラメーター」をご参照ください。

   例：

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

   結果は次のとおりです。

   +--------------+---------------------+---------------+----------------+----------------------+
   | id           | user_name           | age           | city           | access_url           |
   +--------------+---------------------+---------------+----------------+----------------------+
   | 1           | tick                | 32            | shanghai       | http://example.com   |
   +--------------+---------------------+---------------+----------------+----------------------+
   Returned rows: [1], Time elapsed: [183ms]

Enterprise Edition または Community-compatible Edition v22.8 以降

ClickHouse から OSS にデータをエクスポートする場合、または OSS に直接データを書き込む場合は、`s3_truncate_on_insert=1` または `s3_create_new_file_on_insert=1` のいずれかを設定する必要があります。これらのパラメーターを設定しない場合、または 0 に設定した場合、宛先パスにオブジェクトがすでに存在すると操作は失敗します。

• s3_truncate_on_insert=1：ApsaraDB for ClickHouse は、データをエクスポートまたは書き込む前に、宛先パスにオブジェクトが存在するかどうかを確認します。

  • ファイルがすでに存在する場合、ClickHouse は新しいデータでファイルを上書きします。

  • これは完全な上書きシナリオに適しています。この操作は元のデータを削除するため、慎重に使用してください。

• s3_create_new_file_on_insert=1：ClickHouse は、データをエクスポートまたは書き込む前に、宛先パスにオブジェクトが存在するかどうかを確認します。

  • 指定された名前のファイルがすでに存在する場合、ClickHouse は同じフォルダに新しいファイルを作成し、そこにデータを書き込みます。新しいファイル名は、オブジェクトファイル名 + 0から始まる増分番号 + ファイル形式名 の形式で命名されます。

    たとえば、OSS 外部テーブルの作成時に指定した宛先オブジェクトが test.csv の場合、最初の操作後の新しいオブジェクト名は test0.csv になります。2回目の操作後、新しいオブジェクト名は test1.csv になります。

  • この方法は、増分エクスポートまたは書き込みのシナリオに適しており、既存データの上書きを回避します。

Community-compatible Edition v21.8 以前

ClickHouse から OSS にデータをエクスポートする場合、または OSS に直接データを書き込む場合、使用される OSS オブジェクトは1つだけです。エクスポートまたは書き込まれたデータは、元のオブジェクトの内容を上書きします。この操作は慎重に行ってください。

Enterprise Edition または Community-compatible Edition v22.8 以降

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

CREATE TABLE oss_test_tb ON cluster default
(
id UInt8,
user_name String,
age UInt16,
city String,
access_url String
)
ENGINE = OSS('http://ck-test-oss.oss-cn-hangzhou-internal.aliyuncs.com/test.csv', 'LTAI****************', 'yourAccessKeySecret','CSV')

Community-compatible Edition v21.8 以前

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

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