全部產品
Search
文件中心

MaxCompute:使用UNLOAD命令

更新時間:Dec 03, 2025

MaxCompute支援將MaxCompute專案中的資料匯出至外部儲存(OSS、Hologres),以供其他計算引擎使用。本文介紹UNLOAD命令的使用方法及具體樣本。

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

功能介紹

MaxCompute支援使用unload命令將MaxCompute的資料匯出至OSSHologres外部儲存,OSS支援以CSV格式或其他開源格式儲存資料。其中:

  • MaxCompute的資料需要先匯出至OSS中,才可以通過OSS匯出至其他計算引擎,例如Amazon Redshift和BigQuery。

  • 重複匯出不會覆蓋已匯出的檔案,會追加新的匯出檔案。

適用範圍

  • 將MaxCompute資料匯出至Hologres中,不支援使用雙簽名授權模式。

  • 不支援將MaxCompute資料匯出至Hologres分區表中。

  • 匯出的開源格式檔案不支援添加尾碼名

授權

  1. 操作帳號已具備MaxCompute的相關許可權。

    執行UNLOAD操作前,操作帳號至少需要具備MaxCompute專案中待匯出表資料的讀取許可權(Select)。授權操作請參見MaxCompute許可權

  2. 操作帳號已具備外部儲存資料對應資料來源的相關許可權

    從MaxCompute匯出資料至外部儲存前,需要先對外部儲存(OSS或Hologres)授權,允許MaxCompute訪問外部儲存。UNLOAD命令的授權模式沿用了MaxCompute外部表格的授權模式,OSS和Hologres的授權方式如下:

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

    可以在HoloWeb的SQL編輯器中執行建表語句,詳情請參見串連HoloWeb並執行查詢。建表語句如下:

    CREATE TABLE mc_2_holo (id INT, name TEXT);

    資料接收表的欄位類型需與MaxCompute表欄位類型對應,詳情請參見MaxCompute與Hologres的資料類型映射

  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、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尾碼名。

使用樣本

  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.018 USD/GB/月,更多儲存計費資訊,請參見儲存費用(隨用隨付)。資料匯入MaxCompute後有5倍左右的壓縮率,計費依據的資料量是壓縮後的資料。

      • OSS儲存標準型單價為0.018 USD/GB/月,另有其他低頻訪問型、歸檔型、冷歸檔型儲存,請參見儲存費用

        如果匯出資料僅為了節省儲存費用,建議根據資料特徵測試估算壓縮率,根據匯出時的查詢語句估算UNLOAD費用,以及後續對匯出資料的訪問方式進行合理評估,避免因不必要的資料移轉產生額外費用。

    相關文檔

    • 若希望將外部儲存上的CSV格式或其他開源格式資料匯入至MaxCompute,參考LOAD

    • 瞭解建立、讀取和寫入OSS外部表格的文法及參數資訊,參考OSS外部表格

    • 瞭解更多Hologres外部表格相關資訊,參考Hologres外部表格

    常見問題

    Q:MaxCompute專案中的表資料匯出至外部儲存(OSS、Hologres)時,能否給每個欄位都帶上雙引號?例如:"雲原生MaxCompute"、"MaxCompute"、"Hello"。

    A:可以採用修改欄位資料或統一表格式兩種方式實現。

    • 修改表欄位:通過CONCAT手動連接字串。

    • 調整表格式:使用開來源資料解析器org.apache.hadoop.hive.serde2.OpenCSVSerde建立外部表格時,匯出的資料預設為每一個欄位添加雙引號。

      若使用內建文本資料解析器com.aliyun.odps.CsvStorageHandler/TsvStorageHandler建立OSS外部表格時,則不支援該輸出格式,且暫時沒有參數支援實現該功能。

    詳情參考OSS外部表格中資料解析器和參數相關表述。