使用UNLOAD命令将MaxCompute数据导出至外部存储（OSS、Hologres）-云原生大数据计算服务 MaxCompute(MaxCompute)-阿里云帮助中心

本文为您介绍UNLOAD命令的使用方法及具体示例。

本文中的命令您可以在如下工具平台执行：

功能介绍

MaxCompute支持使用unload命令将MaxCompute的数据导出至什么是对象存储OSS、什么是实时数仓Hologres外部存储，OSS支持以CSV格式或其他开源格式存储数据。其中：

MaxCompute的数据需要先导出至OSS中，才可以通过OSS导出至其他计算引擎，例如Amazon Redshift和BigQuery。
重复导出不会覆盖已导出的文件，会追加新的导出文件。

适用范围

将MaxCompute数据导出至Hologres中，不支持使用双签名授权模式。
不支持将MaxCompute数据导出至Hologres分区表中。
导出的开源格式文件不支持添加后缀名。

授权

操作账号已具备MaxCompute的相关权限。

执行UNLOAD操作前，操作账号至少需要具备MaxCompute项目中待导出表数据的读取权限（Select）。授权操作请参见MaxCompute权限。
操作账号已具备外部存储数据对应数据源的相关权限。

从MaxCompute导出数据至外部存储前，需要先对外部存储（OSS或Hologres）授权，允许MaxCompute访问外部存储。UNLOAD命令的授权模式沿用了MaxCompute外部表的授权模式，OSS和Hologres的授权方式如下：
- OSS：采用具备更高安全性的一键授权方式，角色名称定义为AliyunODPSDefaultRole。详情请参见访问外部数据源授权方案。
- Hologres：创建一个RAM角色，为其授权允许MaxCompute访问的权限，并将角色添加至Hologres实例，完成授权，操作详情请参见创建Hologres外部表（STS模式）。

数据导出

导出内置Extractor数据（StorageHandler）

命令格式

UNLOAD FROM {<select_statement>|<table_name> [PARTITION (<pt_spec>)]} 
INTO 
LOCATION <external_location>
STORED BY <StorageHandler>
[WITH SERDEPROPERTIES ('<property_name>'='<property_value>',...)];

参数说明

外部存储：OSS

参数	是否必填	说明
select_statement	否	SELECT查询语句，从源表中查询需要插入目标OSS路径的数据。
table_name、 pt_spec	否	使用表名称或表名称加分区名称指定需要导出的数据。 pt_spec格式为： `(partition_col1 = partition_col_value1, partition_col2 = partition_col_value2, ...)` 该导出方式不产生查询语句，不会产生费用。
external_location	是	指定导出数据存储的目标OSS路径，格式为`'oss://<oss_endpoint>/<object>'`。
StorageHandler	是	指定内置的StorageHandler名称。固定取值只有以下两种： `com.aliyun.odps.CsvStorageHandler` `com.aliyun.odps.TsvStorageHandler` 二者为处理CSV、TSV格式文件的内置文本数据解析器，定义了如何读或写CSV、TSV文件。导出的文件默认添加`.csv`、`.tsv`后缀名。
'<property_name>'='<property_value>'	否	property_name为属性名称。 property_value为属性值。

更多信息，请参见OSS外部表。

外部存储：Hologres

参数	是否必填	说明
select_statement	否	SELECT查询语句，从源表中查询需要插入目标Hologres路径的数据。
table_name	否	使用表名称的方式指定需要导出的数据。该导出方式不产生查询语句，不会产生费用。
external_location	是	指定导出数据存储的目标Hologres路径。格式为`'jdbc:postgresql://<endpoint>:<port>/<database>?ApplicationName=MaxCompute&[currentSchema=<schema>&][useSSL={true\|false}&]table=<holo_table_name>/'`。
StorageHandler	是	指定内置的StorageHandler名称。固定取值为`com.aliyun.odps.jdbc.JdbcStorageHandler`，使用JdbcStorageHandler连接方式。
'<property_name>'='<property_value>'	否	property_name为属性名称。 property_value为属性值。数据导出至Hologres必填如下参数： 'odps.properties.rolearn'='<ram_arn>'：指定RAM角色的ARN信息，用于STS认证。您可以在RAM访问控制页面，单击目标RAM角色名称后，在基本信息区域获取。 'mcfed.mapreduce.jdbc.driver.class'='org.postgresql.Driver'：指定连接Hologres数据库的驱动程序。固定取值为`org.postgresql.Driver`。 'odps.federation.jdbc.target.db.type'='holo'：指定连接的数据库类型。固定取值为`holo`。

更多信息，请参见Hologres外部表。

使用示例

外部存储：OSS

将MaxCompute项目中表sale_detail的数据导出至OSS。

示例数据

表sale_detail的数据如下：

+------------+-------------+-------------+------------+------------+
| shop_name  | customer_id | total_price | sale_date  | region     |
+------------+-------------+-------------+------------+------------+
| s1         | c1          | 100.1       | 2013       | china      |
| s2         | c2          | 100.2       | 2013       | china      |
| s3         | c3          | 100.3       | 2013       | china      |
| null       | c5          | NULL        | 2014       | shanghai   |
| s6         | c6          | 100.4       | 2014       | shanghai   |
| s7         | c7          | 100.5       | 2014       | shanghai   |
+------------+-------------+-------------+------------+------------+

登录OSS管理控制台，创建OSS Bucket目录oss-unload-test/data_location/，示例地域为oss-cn-hangzhou。创建完成后，确认目录已存在。

OSS路径如下：oss://oss-cn-hangzhou-internal.aliyuncs.com/oss-unload-test/data_location。

登录MaxCompute客户端，执行UNLOAD命令，将sale_detail表的数据导出至OSS。

示例1：将sale_detail表中的数据导出为CSV格式并压缩为GZIP。命令如下：

-- 控制导出文件个数：设置单个Worker读取MaxCompute表数据的大小，单位为MB。
-- 由于MaxCompute表有压缩，导出到OSS的数据一般会膨胀4倍左右。
SET odps.stage.mapper.split.size=256;
-- 导出数据
UNLOAD FROM  
(SELECT * FROM sale_detail)
INTO
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/oss-unload-test/data_location'
STORED BY 'com.aliyun.odps.CsvStorageHandler'
WITH SERDEPROPERTIES (
  'odps.properties.rolearn'='acs:ram::<uid>:role/AliyunODPSDefaultRole', 
  'odps.text.option.gzip.output.enabled'='true');

其中，UNLOAD FROM (SELECT * FROM sale_detail)等效于UNLOAD FROM sale_detail。

示例2：将sale_detail表中分区为sale_date='2013'，region='china'的数据导出为TSV格式并压缩为GZIP。命令如下：

-- 控制导出文件个数：设置单个Worker读取MaxCompute表数据的大小，单位为MB。
-- 由于MaxCompute表有压缩，导出到OSS的数据一般会膨胀4倍左右。
SET odps.stage.mapper.split.size=256;
-- 导出数据。
UNLOAD FROM sale_detail PARTITION (sale_date='2013',region='china')
INTO
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/oss-unload-test/data_location'
STORED BY 'com.aliyun.odps.TsvStorageHandler'
WITH SERDEPROPERTIES (
  'odps.properties.rolearn'='acs:ram::<uid>:role/AliyunODPSDefaultRole', 
  'odps.text.option.gzip.output.enabled'='true');

两个示例中出现的参数'odps.text.option.gzip.output.enabled'='true'用于指定导出文件为GZIP压缩格式，当前仅支持GZIP压缩格式。更多参数信息，请参见OSS外部表。

外部存储：Hologres

将MaxCompute项目中，表data_test的数据导出至Hologres。

示例数据

表data_test的数据如下：

+------------+----------+
| id         | name     |
+------------+----------+
| 3          | rgege    |
| 4          | Gegegegr |
+------------+----------+

在Hologres创建数据接收表mc_2_holo（所在数据库名称为test）。

可以在HoloWeb的SQL编辑器中执行建表语句，详情请参见连接HoloWeb并执行查询。建表语句如下：
```
CREATE TABLE mc_2_holo (id INT, name TEXT);
```
数据接收表的字段类型需与MaxCompute表字段类型对应，详情请参见MaxCompute与Hologres的数据类型映射。

登录MaxCompute客户端，执行UNLOAD命令，将data_test表的数据导出至Hologres。命令示例如下：

UNLOAD FROM  
(SELECT * FROM data_test) 
INTO 
LOCATION 'jdbc:postgresql://hgprecn-cn-5y**********-cn-hangzhou-internal.hologres.aliyuncs.com:80/test?ApplicationName=MaxCompute&currentSchema=public&useSSL=false&table=mc_2_holo/'  
STORED BY 'com.aliyun.odps.jdbc.JdbcStorageHandler'
WITH SERDEPROPERTIES ( 
  'odps.properties.rolearn'='acs:ram::13**************:role/aliyunodpsholorole',
  'mcfed.mapreduce.jdbc.driver.class'='org.postgresql.Driver', 
  'odps.federation.jdbc.target.db.type'='holo'
);

在Hologres中查询导出数据：
```
SELECT * FROM mc_2_holo;
```
返回结果示例如下：
```
id	name
4	Gegegegr
3	rgege
```

导出其他开源格式数据

命令格式

UNLOAD FROM {<select_statement>|<table_name> [PARTITION (<pt_spec>)]}
INTO 
LOCATION <external_location>
[ROW FORMAT SERDE '<serde_class>' 
  [WITH SERDEPROPERTIES ('<property_name>'='<property_value>',...)]
]
STORED AS <file_format>
[PROPERTIES ('<tbproperty_name>'='<tbproperty_value>')];

参数说明

参数	是否必填	说明
select_statement	否	SELECT查询语句，从源表中查询需要插入目标OSS路径的数据。
table_name、 pt_spec	否	使用表名称或表名称加分区名称指定需要导出的数据。 pt_spec格式为： `(partition_col1 = partition_col_value1, partition_col2 = partition_col_value2, ...)` 该导出方式不产生查询语句，不会产生费用。
external_location	是	指定导出数据存储的目标OSS路径，格式为`'oss://<oss_endpoint>/<object>'`。
serde_class	否	使用方法和MaxCompute外部表一致，请参见创建OSS外部表。
'<property_name>'='<property_value>'	否	property_name为属性名称。 property_value为属性值。支持的属性和MaxCompute外部表一致，请参见创建OSS外部表。
file_format	是	指定导出数据文件格式。例如ORC、PARQUET、RCFILE、SEQUENCEFILE和TEXTFILE。使用方法和MaxCompute外部表一致，请参见创建OSS外部表。
'<tbproperty_name>'='<tbproperty_value>'	否	tbproperty_name为外部表扩展信息属性名称。 tbproperty_value为外部表扩展信息属性值。例如开源数据支持导出SNAPPY或LZO压缩格式，则设置压缩属性为： `'mcfed.parquet.compression'='SNAPPY'` `'mcfed.parquet.compression'='LZO'` 以SNAPPY或LZO压缩格式导出数据时，导出文件不支持显示`.snappy`或`.lzo`后缀名。

使用示例

示例数据

-- sale_detail表数据。
+------------+-------------+-------------+------------+------------+
| shop_name  | customer_id | total_price | sale_date  | region     |
+------------+-------------+-------------+------------+------------+
| s1         | c1          | 100.1       | 2013       | china      |
| s2         | c2          | 100.2       | 2013       | china      |
| s3         | c3          | 100.3       | 2013       | china      |
| null       | c5          | NULL        | 2014       | shanghai   |
| s6         | c6          | 100.4       | 2014       | shanghai   |
| s7         | c7          | 100.5       | 2014       | shanghai   |
+------------+-------------+-------------+------------+------------+

登录OSS管理控制台，创建OSS Bucket目录oss-unload-test/data_location/，示例地域为oss-cn-hangzhou。创建完成后，确认目录已存在。

OSS路径如下：oss://oss-cn-hangzhou-internal.aliyuncs.com/oss-unload-test/data_location。

登录MaxCompute客户端，执行UNLOAD命令，将sale_detail表的数据导出至OSS。

示例1：将sale_detail表中的数据导出为PARQUET格式并压缩为SNAPPY。

-- 控制导出文件个数：设置单个Worker读取MaxCompute表数据的大小，单位为MB。
-- 由于MaxCompute表有压缩，导出到OSS的数据一般会膨胀4倍左右。
SET odps.stage.mapper.split.size=256;
-- 导出数据
UNLOAD FROM 
(SELECT * FROM sale_detail) 
INTO  
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/oss-unload-test/data_location' 
ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe' 
WITH SERDEPROPERTIES ('odps.properties.rolearn'='acs:ram::<uid>:role/AliyunODPSDefaultRole') 
STORED AS PARQUET 
PROPERTIES('mcfed.parquet.compression'='SNAPPY');

示例2：将sale_detail表中分区为sale_date='2013'，region='china'的数据导出为PARQUET格式并压缩为SNAPPY。

-- 控制导出文件个数：设置单个Worker读取MaxCompute表数据的大小，单位为MB。
-- 由于MaxCompute表有压缩，导出到OSS的数据一般会膨胀4倍左右。
SET odps.stage.mapper.split.size=256;
--导出数据。
UNLOAD FROM sale_detail PARTITION (sale_date='2013',region='china') 
INTO 
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/oss-unload-test/data_location' 
ROW FORMAT SERDE 'org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe' 
WITH SERDEPROPERTIES ('odps.properties.rolearn'='acs:ram::<uid>:role/AliyunODPSDefaultRole') 
STORED AS PARQUET 
PROPERTIES('mcfed.parquet.compression'='SNAPPY');

示例3：将sale_detail表中的数据导出为txt文件并指定逗号为分隔符。

SET odps.sql.allow.fullscan=true; 
UNLOAD FROM (SELECT * FROM sale_detail)
INTO
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/oss-unload-test/data_location'
ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe'
WITH SERDEPROPERTIES ('field.delim'=',')
STORED AS TEXTFILE
PROPERTIES('odps.external.data.enable.extension'='true');

设置导出文件前后缀和扩展名

使用UNLOAD命令将MaxCompute的表导出为文件时，可以自定义文件的前缀、后缀，以及默认生成对应文件格式的扩展名。

命令格式

内置解析器导出CSV、TSV等格式文件。

UNLOAD FROM  {<select_statement>|<table_name> [PARTITION (<pt_spec>)]}
INTO 
LOCATION <external_location> 
[STORED BY <StorageHandler>]
[WITH SERDEPROPERTIES ('<property_name>'='<property_value>',...)];

导出ORC、Parquet等开源格式文件。

UNLOAD FROM {<select_statement>|<table_name> [PARTITION (<pt_spec>)]} 
INTO 
LOCATION <external_location> 
[ROW FORMAT SERDE '<serde_class>' 
  [WITH SERDEPROPERTIES ('<property_name>'='<property_value>',...)] 
] 
STORED AS <file_format> 
[PROPERTIES('<tbproperty_name>'='<tbproperty_value>')];

参数说明

property_name tbproperty_name	使用场景	说明	property_value
odps.external.data.output.prefix （兼容odps.external.data.prefix）	添加输出文件的自定义前缀名。	仅包含数字，字母和下划线（a-z、A-Z、0-9、_）。长度在1-10之间。	符合条件的字符组合，例如`'mc_'`。
odps.external.data.enable.extension	显示输出文件的扩展名。	True表示显示输出文件的扩展名，反之不显示扩展名。默认不展示。	True False
odps.external.data.output.suffix	添加输出文件的自定义后缀名。	仅包含数字，字母和下划线（a-z、A-Z、0-9、_）。	符合条件的字符组合，例如`'_hangzhou'`。
odps.external.data.output.explicit.extension	添加输出文件的自定义扩展名。	仅包含数字，字母和下划线（a-z、A-Z、0-9、_）。长度在1-10之间。优先级高于参数`odps.external.data.enable.extension`。	符合条件的字符组合，例如`'jsonl'`。

其他参数请参见内置Extractor参数说明、其他开源格式数据参数说明。

扩展名

各外部表通过参数odps.external.data.enable.extension=true自动生成的扩展名如下。

文件格式	SERDE	后缀
SEQUENCEFILE	org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe	.sequencefile
TEXTFILE	org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe	.txt
RCFILE	org.apache.hadoop.hive.serde2.columnar.LazyBinaryColumnarSerDe	.rcfile
ORC	org.apache.hadoop.hive.ql.io.orc.OrcSerde	.orc
PARQUET	org.apache.hadoop.hive.ql.io.parquet.serde.ParquetHiveSerDe	.parquet
AVRO	org.apache.hadoop.hive.serde2.avro.AvroSerDe	.avro
JSON	org.apache.hive.hcatalog.data.JsonSerDe	.json

使用示例

导出text格式文件，添加前缀为mc_，后缀为_hangzhou，并自动生成扩展名txt。

UNLOAD FROM (SELECT * FROM sale_detail) 
INTO 
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/oss-unload-test/data_location' 
ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe'
STORED AS TEXTFILE
PROPERTIES (
    'odps.external.data.output.prefix'='mc_', 
    'odps.external.data.output.suffix'='_beijing',
    'odps.external.data.enable.extension'='true');

在指定导出数据存储的目标OSS路径查看导出结果：

导出的文件名示例为 mc_20251120162614634grey9oeujm16_M1_1_0_0-0_TableSink1_hangzhou.txt。

通过OSS将数据导出至下游系统

MaxCompute可以借助OSS作为中间过渡格式，将数据导出到多种不被直接支持的数据库中（例如，时序数据库InfluxDB）。具体实现步骤如下：

使用UNLOAD命令将数据导出到 OSS。
下载OSS数据到本地环境。
使用目标数据库的导入工具或命令完成数据加载。

计费方式

计算费用：UNLOAD命令本身不计费，UNLOAD命令中的查询子句需要扫描数据并使用计算资源计算结果，因此查询子句按照普通SQL作业计费。
存储费用：通过OSS存储结构化数据在一些场景中可以节省存储费用，但需要提前做好费用估算。
- MaxCompute存储费用为0.12元/GB/月，更多存储计费信息，请参见存储费用。数据导入MaxCompute后有5倍左右的压缩率，计费依据的数据量是压缩后的数据。
- OSS存储标准型单价为0.12元/GB/月，另有其他低频访问型、归档型、冷归档型存储，请参见存储费用。
  
  如果导出数据仅为了节省存储费用，建议根据数据特征测试估算压缩率，根据导出时的查询语句估算UNLOAD费用，以及后续对导出数据的访问方式进行合理评估，避免因不必要的数据迁移产生额外费用。

常见问题

Q：MaxCompute项目中的表数据导出至外部存储（OSS、Hologres）时，能否给每个字段都带上双引号？例如："云原生大数据计算服务"、"MaxCompute"、"Hello"。

A：可以采用修改字段数据或统一表格式两种方式实现。

修改表字段：通过CONCAT手动连接字符串。
调整表格式：使用开源数据解析器org.apache.hadoop.hive.serde2.OpenCSVSerde创建外部表时，导出的数据默认为每一个字段添加双引号。

若使用内置文本数据解析器com.aliyun.odps.CsvStorageHandler/TsvStorageHandler创建OSS外部表时，则不支持该输出格式，且暂时没有参数支持实现该功能。

详情参考OSS外部表中数据解析器和参数相关表述。

功能介绍

适用范围

授权

数据导出

导出内置Extractor数据（StorageHandler）

命令格式

参数说明

外部存储：OSS

外部存储：Hologres

使用示例

外部存储：OSS

外部存储：Hologres

导出其他开源格式数据

命令格式

参数说明

使用示例

设置导出文件前后缀和扩展名

命令格式

参数说明

扩展名

使用示例

通过OSS将数据导出至下游系统

计费方式

相关文档

常见问题