ApsaraDB for ClickHouse:OSS 外部テーブルによる OSS データへのアクセス

Enterprise Edition または Community-compatible Edition（22.8 以降）

Community-compatible Edition（21.8 以前）

1. データベースにログインします。

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

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

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

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

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 バケットにアクセスするための内部エンドポイント。詳細については、「リージョンとエンドポイント」をご参照ください。 重要 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 の漏洩リスクを軽減するため、AccessKey Secret は作成時のみ表示され、後から取得することはできません。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 でサポートされている大文字小文字を区別するファイル形式である必要があります。詳細については、「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（22.8 以降）

1. データベースにログインします。

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

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

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

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

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（21.8 以前）

1. データベースにログインします。

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

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

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

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

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 22.8 以降

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 から開始し、1 ずつ増分）+ ファイル形式名。

    たとえば、対象ファイルが test.csv の場合、最初の操作では test0.csv が作成され、2 回目の操作では test1.csv が作成されます。

  • この方法は、増分エクスポートまたは書き込みに適しており、既存のデータを上書きしません。

Community-compatible Edition 21.8 以前

データをエクスポートまたは書き込む際は、単一の OSS ファイルのみが使用されます。新しいデータは、元のファイルの内容を上書きします。十分に注意してください。

Enterprise Edition または Community-compatible Edition 22.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 互換エディション 21.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');