使用UNLOAD命令

MaxCompute支持您将MaxCompute项目中的数据导出至外部存储(OSS、Hologres),以供其他计算引擎使用。本文为您介绍UNLOAD命令的使用方法及具体示例。

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

功能介绍

MaxCompute支持使用unload命令将MaxCompute的数据导出至OSSHologres外部存储,OSS支持以CSV格式或其他开源格式存储数据。其中:

  • MaxCompute的数据需要先导出至OSS中,才可以通过OSS导出至其他计算引擎,例如Amazon RedshiftBigQuery。

  • 重复导出不会覆盖已导出的文件,会追加新的导出文件。

适用范围

  • MaxCompute数据导出至Hologres中,不支持使用双签名授权模式。

  • 不支持将MaxCompute数据导出至Hologres分区表中。

  • 导出的开源格式文件不支持添加后缀名

授权

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

    执行UNLOAD操作前,操作账号至少需要具备MaxCompute项目中待导出表数据的读取权限(Select)。授权操作请参见MaxCompute权限

  2. 操作账号已具备外部存储数据对应数据源的相关权限

    MaxCompute导出数据至外部存储前,需要先对外部存储(OSSHologres)授权,允许MaxCompute访问外部存储。UNLOAD命令的授权模式沿用了MaxCompute外部表的授权模式,OSSHologres的授权方式如下:

    • OSS:采用具备更高安全性的一键授权方式,角色名称定义为AliyunODPSDefaultRole。详情请参见STS模式授权

    • 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。

  1. 示例数据

    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   |
    +------------+-------------+-------------+------------+------------+
  2. 登录OSS管理控制台,创建OSS Bucket目录oss-unload-test/data_location/,示例地域为oss-cn-hangzhou。创建完成后如下图所示:

    image

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

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

    1. 示例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. 示例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。

  1. 示例数据

    data_test的数据如下:

    +------------+----------+
    | id         | name     |
    +------------+----------+
    | 3          | rgege    |
    | 4          | Gegegegr |
    +------------+----------+
  2. Hologres创建数据接收表mc_2_holo(所在数据库名称为test)。

    可以在HoloWebSQL编辑器中执行建表语句,详情请参见连接HoloWeb并执行查询。建表语句如下:

    CREATE TABLE mc_2_holo (id INT, name TEXT);

    数据接收表的字段类型需与MaxCompute字段类型对应,详情请参见MaxComputeHologres的数据类型映射

  3. 登录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'
    );
  4. 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、SEQUENCEFILETEXTFILE。

使用方法和MaxCompute外部表一致,请参见创建OSS外部表

'<tbproperty_name>'='<tbproperty_value>'

  • tbproperty_name为外部表扩展信息属性名称。

  • tbproperty_value为外部表扩展信息属性值。

例如开源数据支持导出SNAPPYLZO压缩格式,则设置压缩属性为:

  • 'mcfed.parquet.compression'='SNAPPY'

  • 'mcfed.parquet.compression'='LZO'

SNAPPYLZO压缩格式导出数据时,导出文件不支持显示.snappy.lzo后缀名。

使用示例

  1. 示例数据

    -- 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   |
    +------------+-------------+-------------+------------+------------+
  2. 登录OSS管理控制台,创建OSS Bucket目录oss-unload-test/data_location/,示例地域为oss-cn-hangzhou。创建完成后如下图所示:

    image

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

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

    1. 示例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. 示例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. 示例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路径查看导出结果:

    image

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

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

    1. 使用UNLOAD命令将数据导出到 OSS。

    2. 下载OSS数据到本地环境。

    3. 使用目标数据库的导入工具或命令完成数据加载。

    计费方式

    • 计算费用:UNLOAD命令本身不计费,UNLOAD命令中的查询子句需要扫描数据并使用计算资源计算结果,因此查询子句按照普通SQL作业计费。

    • 存储费用:通过OSS存储结构化数据在一些场景中可以节省存储费用,但需要提前做好费用估算。

      • MaxCompute存储费用为0.12/GB/月,更多存储计费信息,请参见存储费用。数据导入MaxCompute后有5倍左右的压缩率,计费依据的数据量是压缩后的数据。

      • OSS存储标准型单价为0.12/GB/月,另有其他低频访问型、归档型、冷归档型存储,请参见存储费用

        如果导出数据仅为了节省存储费用,建议根据数据特征测试估算压缩率,根据导出时的查询语句估算UNLOAD费用,以及后续对导出数据的访问方式进行合理评估,避免因不必要的数据迁移产生额外费用。

    相关文档

    • 若希望将外部存储上的CSV格式或其他开源格式数据导入至MaxCompute,参考LOAD

    • 了解创建、读取和写入OSS外部表的语法及参数信息,参考OSS外部表

    • 了解更多Hologres外部表相关信息,参考Hologres外部表

    常见问题

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

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

    • 修改表字段:通过CONCAT手动连接字符串。

    • 调整表格式:使用开源数据解析器org.apache.hadoop.hive.serde2.OpenCSVSerde创建外部表时,导出的数据默认为每一个字段添加双引号。

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

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