文件读取函数（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 类型映射