Hologres:EXTERNAL_FILES 関数

バージョン要件

ご利用の Hologres インスタンスは、V4.1 以降のバージョンである必要があります。それ以前のバージョンをご利用の場合は、スペックアップしてください。詳細については、「Instance upgrades」をご参照ください。

権限の構成

EXTERNAL_FILES を使用できるのは RAM ユーザーまたは Alibaba Cloud アカウントのみです。カスタムアカウントはサポートされていません。EXTERNAL_FILES を使用する前に、以下の手順を完了してください。EXTERNAL_FILES は RAM ロール経由で OSS にアクセスします。まず RAM ロールを作成し、Hologres サービスに付与します。その後、そのロールに OSS 権限を付与します。

ロールの作成

• RAM Roles で RAM コンソールにログインします。[Roles] ページで、[Create Role] をクリックします。

• ダイアログボックスで、[Trusted Entity Type] を [Cloud Service]、[Trusted Entity] を [Real-time Data Warehouse Hologres] に設定します。

• ロール名を入力して、作成を完了します。

OSS アクセス権限の構成

RAM ロールに OSS 権限を付与します。

• データの読み取り：AliyunOSSReadOnlyAccess 権限を付与します。

• データの書き込み：AliyunOSSFullAccess 権限を付与します。

SQL ユーザーに GrantAssumeRole 権限を付与

SQL を実行するユーザーが Alibaba Cloud アカウントでない場合、あらかじめ GrantAssumeRole 権限を付与する必要があります。

• RAM コンソールで権限ポリシーを作成します。[Policies] > [Create Policy] > [Script Editor] に移動し、以下の JSON を貼り付けます。Role_ARN は、EXTERNAL_FILES で使用する role_arn と同じ値に置き換えてください。Role ARN の確認方法については、「FAQ about RAM roles and STS tokens」をご参照ください。

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "hologram:GrantAssumeRole",
      "Resource": "<RoleARN>"
    }
  ]
}

次に、このポリシーをクエリを実行するユーザーにアタッチします。RAM ユーザーの場合は、[Users] > [Permissions] > [Add Permissions] に移動します。RAM ロールの場合は、[Roles] > [Permissions] > [Add Permissions] に移動します。

共通パラメーター

読み取りパラメーター

書き込みパラメーター

例 1：CSV ファイルのクエリ

OSS 内の CSV ファイルをクエリし、スキーマを自動推論します。

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/data/',
    format = 'csv',
    csv_skip_header = 'true',
    csv_delimiter = ',',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

CSV ファイルをクエリし、スキーマを手動で指定します。

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/data/',
    format = 'csv',
    csv_skip_header = 'true',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
) AS (id int, name text, amount decimal(10,2));

例 2：Parquet ファイルのクエリ

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/parquet_data/',
    format = 'parquet',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

例 3：ORC ファイルのクエリ

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/orc_data/',
    format = 'orc',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

例 4：Hologres テーブルへのデータインポート

-- 対象テーブルの作成
CREATE TABLE orders (
    order_id int,
    customer_name text,
    amount decimal(10,2),
    PRIMARY KEY(order_id)
);

-- OSS からのデータインポート
INSERT INTO orders 
SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/orders/',
    format = 'csv',
    csv_skip_header = 'true',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
) AS (order_id int, customer_name text, amount decimal(10,2));

例 5：OSS へのデータエクスポート

複数ファイルにデータをエクスポートします。

INSERT INTO EXTERNAL_FILES(
    path = 'oss://mybucket/export/',
    format = 'csv',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role',
    target_file_size_mb = '100'
) SELECT * FROM orders;

単一ファイルにデータをエクスポートします。

INSERT INTO EXTERNAL_FILES(
    path = 'oss://mybucket/export/',
    format = 'csv',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role',
    single_file = 'true'
) SELECT * FROM orders;

例 6：サーバーレスリソースグループの使用

SET hg_computing_resource = 'serverless';

SELECT * FROM EXTERNAL_FILES(
    path = 'oss://mybucket/data/',
    format = 'csv',
    oss_endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com',
    role_arn = 'acs:ram::123456789:role/hologres-role'
);

自動スキーマ推論

AS 句でスキーマを指定しない場合、Hologres は自動的にスキーマを推論します。

• Parquet/ORC：ファイルメタデータから推論します。

• ヘッダー付き CSV：先頭行（ヘッダー）とデータ内容から推論します。

• ヘッダーなし CSV：すべてのファイルが同一のスキーマを持つ必要があります。

Hologres は schema_deduce_file_num で指定された数のファイルをスキャンし、すべてのスキーマの和集合を取得します。

スキーマ推論動作

型マッピング

EXTERNAL_FILES が ORC または Parquet ファイルを読み取る際、ファイル内の型を PostgreSQL 型にマッピングします。以下にマッピングを示します。サポートされていない型は各表の下に記載されています。

ORC 型マッピング

Parquet 型マッピング