Hologres：檔案讀取函數（EXTERNAL_FILES）

版本要求

執行個體需為 Hologres V4.1 及以上版本。若執行個體為 V4.1 以下版本，請參見執行個體升級。

許可權配置

EXTERNAL_FILES 僅支援 RAM 子帳號或主帳號使用，暫不支援自訂帳號。使用前需完成以下配置：EXTERNAL_FILES 通過 RAM 角色訪問 OSS，因此需先建立角色並授權給 Hologres 服務，再為角色授予 OSS 相關許可權。

建立角色

• 登入阿里雲 RAM 存取控制管控台，進入角色列表，點擊建立角色。

• 在彈窗中選擇信任主體類型為「雲端服務」，信任主體名稱選擇「即時數倉 Hologres」。

• 填寫角色名稱並完成建立。

配置 OSS 存取權限

為 RAM 角色配置 OSS 許可權：

• 讀取資料：授予 AliyunOSSReadOnlyAccess 許可權。

• 寫入資料：授予 AliyunOSSFullAccess 許可權。

授予運行 SQL 的使用者 GrantAssumeRole 許可權

若執行使用者非主帳號，需先授予該使用者 GrantAssumeRole 許可權：

• 在 RAM 存取控制中建立權限原則（權限原則 → 建立權限原則 → 指令碼編輯），粘貼以下內容，其中 Role_ARN 需與 EXTERNAL_FILES 使用的 role_arn 相同。如何尋找 Role_ARN 請參見RAM 角色與 STS 常見問題。

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

然後將該策略授權給執行查詢的使用者（RAM 使用者：使用者 → 許可權管理 → 新增授權；RAM 角色：角色 → 許可權管理 → 新增授權）。

通用參數

讀取參數

寫入參數

樣本 1：查詢 CSV 檔案

查詢 OSS 上的 CSV 檔案，自動推斷 Schema：

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 檔案，手動指定 Schema：

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：使用 Serverless 資源群組

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

自動推斷 Schema

當不使用 AS 子句指定 Schema 時，系統會自動推斷：

• Parquet/ORC：根據檔案中繼資料自動推斷。

• 帶表頭的 CSV：根據首行表頭及資料內容推斷。

• 不帶表頭的 CSV：要求所有檔案 Schema 一致。

推斷時會掃描 schema_deduce_file_num 指定數量的檔案，取所有檔案 Schema 的並集。

Schema 推斷行為

類型映射

EXTERNAL_FILES 讀取 ORC/Parquet 時，會將檔案類型映射為 PostgreSQL 類型，對應關係如下。不支援的類型見各表下方說明。

ORC 類型映射

Parquet 類型映射