MaxCompute：Tunnel命令

命令格式

tunnel <subcommand> [options] [args]

可選項說明：

Available subcommands:
    upload (u)
    download (d)
    resume (r)
    show (s)
    purge (p)
    help (h)
    upsert(us)

參數說明

• upload：上傳資料到MaxCompute的表中。支援檔案的上傳，每一次上傳只支援資料上傳到一張表或表的一個分區。分區表一定要指定上傳的分區，多級分區一定要指定到末級分區。

  -- 將log.txt（在MaxCompute用戶端的bin目錄中）中的資料上傳至專案空間test_project的表test_table（二級分區表）中的p1="b1",p2="b2"分區。
  tunnel upload log.txt test_project.test_table/p1="b1",p2="b2";
  
  -- 將log.txt中的資料上傳至表test_table中。scan參數表示需要掃描log.txt中的資料是否符合test_table的定義，如果不符合報錯，並停止上傳資料。
  tunnel upload  log.txt  test_table --scan=true;
  
  -- 將其他路徑下的log.txt中的資料上傳至專案空間test_project的表test_table（二級分區表）中的p1="b1",p2="b2"分區。
  tunnel upload D:\test\log.txt test_project.test_table/p1="b1",p2="b2";

• download：從MaxCompute的表中下載資料。只支援下載到單個檔案，每一次下載只支援下載一張表或一個分區到一個檔案。分區表一定要指定下載的分區，多級分區一定要指定到末級分區。

  -- 將test_project.test_table表（二級分區表）中的資料下載到test_table.txt檔案中。
  tunnel download  test_project.test_table/p1="b1",p2="b2"  test_table.txt;
  -- 將test_project.test_table表（二級分區表）中的資料下載到其他路徑下。
  tunnel download  test_project.test_table/p1="b1",p2="b2"  D:\test\test_table.txt;

• resume：因為網路或Tunnel服務的原因出錯，支援續傳檔案或目錄。如果上傳資料失敗，通過resume命令進行斷點續傳，僅支援上傳資料的續傳。每次上傳、下載資料被稱為一個Session。在resume後指定session id完成續傳。

  tunnel resume;

• show：查看歷史運行資訊。

  --顯示前5次上傳或下載資料的詳細命令。
  tunnel show history -n 5;
  --顯示最後一次上傳或下載資料的日誌。
  tunnel show log;

• purge：清理Session目錄，預設清理3天內的日誌。

  --清理前5天的日誌。
  tunnel purge 5;

• help：輸出Tunnel協助資訊。

• upsert：結合Update和Insert語義，進行資料寫入，僅Transaction Table 2.0類型表支援。

  若目標表中未找到匹配資料，則會插入新資料；若資料已存在，則會進行資料更新。

  -- 將log.txt（在MaxCompute用戶端的bin目錄中）中的資料上傳至專案空間test_project的表test_table（二級分區表）中的p1="b1",p2="b2"分區。
  tunnel upsert log.txt test_project.test_table/p1="b1",p2="b2";

命令功能

命令格式

tunnel upload [options] <path> <[project.]table[/partition]>

格式說明：

Available options:
 -acp,-auto-create-partition <ARG>   auto create target partition if not
                                     exists, default false
 -bs,-block-size <ARG>               block size in MiB, default 100
 -c,-charset <ARG>                   specify file charset, default ignore.
                                     set ignore to download raw data
 -cf,-csv-format <ARG>               use csv format (true|false), default
                                     false. When uploading in csv format,
                                     file splitting not supported.
 -cp,-compress <ARG>                 compress, default true
 -dbr,-discard-bad-records <ARG>     specify discard bad records
                                     action(true|false), default false
 -dfp,-date-format-pattern <ARG>     specify date format pattern, default
                                     yyyy-MM-dd HH:mm:ss
 -fd,-field-delimiter <ARG>          specify field delimiter, support
                                     unicode, eg \u0001. default ","
 -h,-header <ARG>                    if local file should have table
                                     header, default false
 -mbr,-max-bad-records <ARG>         max bad records, default 1000
 -ni,-null-indicator <ARG>           specify null indicator string,
                                     default ""(empty string)
 -ow,-overwrite <true | false>       overwrite specified table or
                                     partition, default: false
 -rd,-record-delimiter <ARG>         specify record delimiter, support
                                     unicode, eg \u0001. default "\r\n"
 -s,-scan <ARG>                      specify scan file
                                     action(true|false|only), default true
 -sd,-session-dir <ARG>              set session dir, default
                                     D:\software\odpscmd_public\plugins\dship
 -ss,-strict-schema <ARG>            specify strict schema mode. If false,
                                     extra data will be abandoned and
                                     insufficient field will be filled
                                     with null. Default true
 -t,-threads <ARG>                   number of threads, default 1
 -te,-tunnel_endpoint <ARG>          tunnel endpoint
 -time,-time <ARG>                   keep track of upload/download elapsed
                                     time or not. Default false
 -tz,-time-zone <ARG>                time zone, default local timezone:
                                     Asia/Shanghai
Example:
    tunnel upload log.txt test_project.test_table/p1="b1",p2="b2"

參數說明

• 必選參數

  • path

    上傳資料檔案的路徑以及名稱。

    資料檔案的歸檔路徑有兩種選擇：您可以將檔案直接歸檔至MaxCompute用戶端的bin目錄中，此時path需要設定為檔案名稱.尾碼名；也可以將檔案歸檔至其他路徑下，例如D盤的test檔案夾，path需要設定為D:\test\檔案名稱.尾碼名。

    說明

    macOS系統中path值只能使用絕對路徑，例如檔案歸檔在MaxCompute用戶端的bin目錄中，此時path需要設定為D:\MaxCompute\bin\檔案名稱.尾碼名。

  • [project.]table[/partition]

    目標表表名。如果是分區表，需要指定至最末級分區。如果不是當前空間的表，需要指定表所在的空間名。

• 選擇性參數

  • -acp

    如果指定分區不存在，自動建立目標資料分割。預設值為False。

  • -bs

    指定每次上傳至Tunnel的資料區塊大小。預設值為100 MiB（1 MiB＝1024×1024 Byte）。

  • -c

    指定本機資料檔案編碼。預設不設定，下載來源資料。

  • -cf

    指定是否為CSV檔案，預設值為False。

    說明

    Upload僅支援TXT、CSV格式檔案，預設上傳TXT檔案。如果上傳CSV檔案，需要指定-cf參數，同時請下載最新版本的MaxCompute用戶端。

  • -cp

    指定是否在本地壓縮資料後再上傳，減少網路流量。預設值為True。

  • -dbr

    指定是否忽略髒資料（多列、少列、列資料類型不匹配等情況）。預設值為False。

    • True：忽略全部不符合表定義的資料，預設忽略條數為1000條，如果想更改忽略條數，需要加上-mbr參數。

    • False：如果遇到髒資料，則給出錯誤提示資訊，目標表內的未經處理資料不會被汙染。

  • -dfp

    指定DATETIME類型資料格式，預設為yyyy-MM-dd HH:mm:ss。如果您想指定時間格式到毫秒層級，可以使用tunnel upload -dfp 'yyyy-MM-dd HH:mm:ss.SSS'。DATETIME資料類型詳情請參見資料類型版本說明。

  • -fd

    指定本機資料檔案的列分割符。預設值為英文逗號（,）。

  • -h

    指定待上傳的資料檔案是否可以包含表頭。預設值為False，表示上傳的資料檔案中不可以包含表頭。如果值為True，表示上傳的資料檔案中可以包含表頭，會跳過表頭從第二行開始上傳資料。

  • -mbr

    此參數需要配合-dbr參數使用，當-dbr設定為true時，設定此參數才有意義。指定可容忍的髒資料量。超過此資料量時，終止上傳。預設值為1000條。

  • -ni

    指定NULL資料標識符。預設值為空白字串。

  • -ow

    指定上傳資料是否覆蓋表或分區。預設值為False，上傳資料為累加方式。樣本如下。

    --建立分區表
    CREATE TABLE IF NOT EXISTS sale_detail(
          shop_name     STRING,
          customer_id   STRING,
          total_price   DOUBLE)
    PARTITIONED BY (sale_date STRING,region STRING);
    
    alter table sale_detail add partition (sale_date='201312', region='hangzhou');
    
    --本地準備好資料檔案d:\data.txt，檔案內容如下：
    shopx,x_id,100
    shopy,y_id,200
    
    --上傳資料到分區表
    tunnel upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou;
    
    --查詢sale_detail表
    select * from sale_detail;
    
    --返回結果
    +------------+-------------+-------------+------------+------------+
    | shop_name  | customer_id | total_price | sale_date  | region     |
    +------------+-------------+-------------+------------+------------+
    | shopx      | x_id        | 100.0       | 201312     | hangzhou   |
    | shopy      | y_id        | 200.0       | 201312     | hangzhou   |
    +------------+-------------+-------------+------------+------------+
    
    --在本地修改data.txt的資料，檔案內容如下：
    shopx,x_id,300
    shopy,y_id,400
    
    --覆蓋上傳
    tunnel upload -ow true data.txt sale_detail/sale_date=201312,region=hangzhou;
    
    --查詢sale_detail表
    select * from sale_detail;
    
    --返回結果
    +------------+-------------+-------------+------------+------------+
    | shop_name  | customer_id | total_price | sale_date  | region     |
    +------------+-------------+-------------+------------+------------+
    | shopx      | x_id        | 300.0       | 201312     | hangzhou   |
    | shopy      | y_id        | 400.0       | 201312     | hangzhou   |
    +------------+-------------+-------------+------------+------------+

  • -rd

    指定本機資料檔案的行分割符。預設值為\r\n。

  • -s

    指定是否掃描本機資料檔案。預設值為True。

    • True：先掃描資料，若資料格式正確，再匯入資料。

    • False：不掃描資料，直接匯入資料。

    • Only：僅掃描本機資料，掃描結束後不繼續匯入資料。

  • -sd

    指定Session目錄。

  • -ss

    指定嚴格架構模式。預設值為True。如果為False，多餘的資料將被丟棄，不足的欄位將填充NULL。

  • -t

    指定Threads的數量。預設值為1。

  • -te

    指定Tunnel的Endpoint。

  • -time

    指定是否跟蹤上傳所用時間。預設值為False。

  • -tz

    指定時區。預設值為本地時區，例如Asia/Shanghai。時區資訊請參考時區列表。

顯示記錄。

• 命令格式

  tunnel show history [-n <number>];

  -n <number>：tunnel執行的次數。

• 命令樣本

  樣本1：顯示記錄，預設儲存500條資料。

  tunnel show history;

  返回結果：

  20230505xxxxxxxxxxxxxx0b0d5b3c  bad     'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -dbr true -time true'
  20230505xxxxxxxxxxxxxx0ad720a3  failed  'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -time true'
  20230505xxxxxxxxxxxxxx0ad5ca68  bad     'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -dbr true'
  ......

  樣本2：顯示前5次上傳或下載資料的詳細命令。

  tunnel show history -n 5;

  返回結果：

  20230505xxxxxxxxxxxxxx0aa48c4b  success 'download sale_detail/sale_date=201312,region=hangzhou result.txt'
  20230505xxxxxxxxxxxxxx0aa6165c  success 'download sale_detail/sale_date=201312,region=hangzhou result.txt'
  20230505xxxxxxxxxxxxxx0af11472  failed  'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -s false'
  20230505xxxxxxxxxxxxxx0b464374  success 'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -s false'
  20230505xxxxxxxxxxxxxx02dbb6bd  failed  'upload d:\data.txt sale_detail/sale_date="201312",region="hangzhou" -s false'

顯示最後一次上傳或下載資料的日誌。

tunnel show log;

命令功能

修複執行記錄，僅對上傳資料有效。

命令格式

odps@  project_name>tunnel help resume;
usage: tunnel resume [session_id] [-force]
              resume an upload session
 -f,-force   force resume
Example:
       tunnel resume

參數說明

• session_id

  上傳失敗的Session ID。必選參數。

• -f

  指定是否強制修複執行記錄。預設忽略。

樣本

odps@ project_name>tunnel resume 20150610xxxxxxxxxxx70a002ec60c -force;
start resume
20150610xxxxxxxxxxx70a002ec60c
Upload session: 20150610xxxxxxxxxxx70a002ec60c
Start upload:d:\data.txt
Resume 1 blocks 
2015-06-10 16:46:42     upload block: '1'
2015-06-10 16:46:42     upload block complete, blockid=1
upload complete, average speed is 0 KB/s
OK

命令功能

將MaxCompute表資料或指定Instance的執行結果下載至本地。

使用Tunnel下載資料時，您需要擁有Download許可權。如果無Download許可權，需要聯絡Project Owner或具備Super_Administrator角色的使用者完成授權操作。更多Download許可權授權操作，請參見Policy許可權控制。

命令格式

odps@ project_name>tunnel help download;
usage: tunnel download [options] <[project.]table[/partition]> <path>

              download data to local file
 -c,-charset <ARG>                 specify file charset, default ignore.
                                   set ignore to download raw data
 -cf,-csv-format <ARG>             use csv format (true|false), default
                                   false. When uploading in csv format,
                                   file splitting not supported.
 -ci,-columns-index <ARG>          specify the columns index(starts from
                                   0) to download, use comma to split each
                                   index
 -cn,-columns-name <ARG>           specify the columns name to download,
                                   use comma to split each name
 -cp,-compress <ARG>               compress, default true
 -dfp,-date-format-pattern <ARG>   specify date format pattern, default
                                   yyyy-MM-dd HH:mm:ss
 -e,-exponential <ARG>             When download double values, use
                                   exponential express if necessary.
                                   Otherwise at most 20 digits will be
                                   reserved. Default false
 -fd,-field-delimiter <ARG>        specify field delimiter, support
                                   unicode, eg \u0001. default ","
 -h,-header <ARG>                  if local file should have table header,
                                   default false
    -limit <ARG>                   specify the number of records to
                                   download
 -ni,-null-indicator <ARG>         specify null indicator string, default
                                   ""(empty string)
 -rd,-record-delimiter <ARG>       specify record delimiter, support
                                   unicode, eg \u0001. default "\r\n"
 -sd,-session-dir <ARG>            set session dir, default
                                   D:\software\odpscmd_public\plugins\dship
 -t,-threads <ARG>                 number of threads, default 1
 -te,-tunnel_endpoint <ARG>        tunnel endpoint
 -time,-time <ARG>                 keep track of upload/download elapsed
                                   time or not. Default false
 -tz,-time-zone <ARG>              time zone, default local timezone:
                                   Asia/Shanghai
usage: tunnel download [options] instance://<[project/]instance_id> <path>

              download instance result to local file
 -c,-charset <ARG>                 specify file charset, default ignore.
                                   set ignore to download raw data
 -cf,-csv-format <ARG>             use csv format (true|false), default
                                   false. When uploading in csv format,
                                   file splitting not supported.
 -ci,-columns-index <ARG>          specify the columns index(starts from
                                   0) to download, use comma to split each
                                   index
 -cn,-columns-name <ARG>           specify the columns name to download,
                                   use comma to split each name
 -cp,-compress <ARG>               compress, default true
 -dfp,-date-format-pattern <ARG>   specify date format pattern, default
                                   yyyy-MM-dd HH:mm:ss
 -e,-exponential <ARG>             When download double values, use
                                   exponential express if necessary.
                                   Otherwise at most 20 digits will be
                                   reserved. Default false
 -fd,-field-delimiter <ARG>        specify field delimiter, support
                                   unicode, eg \u0001. default ","
 -h,-header <ARG>                  if local file should have table header,
                                   default false
    -limit <ARG>                   specify the number of records to
                                   download
 -ni,-null-indicator <ARG>         specify null indicator string, default
                                   ""(empty string)
 -rd,-record-delimiter <ARG>       specify record delimiter, support
                                   unicode, eg \u0001. default "\r\n"
 -sd,-session-dir <ARG>            set session dir, default
                                   D:\software\odpscmd_public\plugins\dshi
 -t,-threads <ARG>                 number of threads, default 1
 -te,-tunnel_endpoint <ARG>        tunnel endpoint
 -time,-time <ARG>                 keep track of upload/download elapsed
                                   time or not. Default false
 -tz,-time-zone <ARG>              time zone, default local timezone:
                                   Asia/Shanghai
Example:
    tunnel download test_project.test_table/p1="b1",p2="b2" log.txt //下載指定表資料
    tunnel download instance://test_project/test_instance log.txt   //下載指定Instance的執行結果

參數說明

• 必選參數

  • path

    下載的資料檔案儲存的本地路徑。

    資料檔案的儲存路徑有兩種選擇：您可以將檔案直接下載至MaxCompute用戶端的bin目錄中，此時path需要設定為檔案名稱.尾碼名；也可以將檔案下載至其他路徑下，例如D盤的test檔案夾，path需要設定為D:\test\檔案名稱.尾碼名。

  • [project.]table[/partition]

    需要下載的表名稱。如果是分區表，需要指定至最末級分區。如果不是當前空間的表，需要指定表所在的空間名。

  • [project/]instance_id

    Instance ID。下載指定Instance的執行結果時指定此參數。

• 選擇性參數

  • -c

    指定本機資料檔案編碼，預設忽略。

  • -cf

    指定是否為CSV檔案，預設值為False。

    說明

    Download僅支援TXT、CSV格式檔案，預設下載TXT檔案。如果需要下載CSV檔案，需要指定-cf true參數，同時請下載最新版本的MaxCompute用戶端。指定-cf true參數後，檔案分隔字元只能是半形逗號（,），即便您再使用-fd參數指定檔案分隔字元也將不起作用。

  • -ci

    指定列索引（從0開始）下載，使用英文逗號（,）分隔。

  • -cn

    指定要下載的列名稱，使用英文逗號（,）分隔每個名稱。

  • -cp

    指定是否壓縮後再下載，減少網路流量，預設值為True。

  • -dfp

    指定DATETIME類型資料格式，預設格式為yyyy-MM-dd HH:mm:ss。

  • -e

    指定下載DOUBLE類型值時，如果需要，使用指數函數表示，否則最多保留20位。預設值為False。

  • -fd

    指定本機資料檔案的列分割符，預設值為半形逗號（,）。

  • -h

    指定匯出的資料檔案是否包含表頭。預設值為False，表示匯出資料檔案中不包含表頭。如果值為True，表示匯出資料檔案中包含表頭。

    說明

    -h=true和threads>1（多線程）不能一起使用。

  • -limit

    指定要下載的行數。

  • -ni

    指定NULL資料標識符，預設為空白字串。

  • -rd

    指定本機資料檔案的行分割符，預設值為\r\n。

  • -sd

    指定Session目錄。

  • -t

    指定Threads的數量，預設值為1。

  • -te

    指定Tunnel Endpoint。

  • -time

    指定是否跟蹤下載所用時間。預設值為False。

  • -tz

    指定時區。預設為本地時區，例如Asia/Shanghai。

命令功能

清除Session目錄。

命令格式

odps@ project_name>tunnel help purge;
usage: tunnel purge [n]
              force session history to be purged.([n] days before, default
              3 days)
Example:
       tunnel purge 5

參數說明

n：清除歷史日誌的天數。預設為3天。

資料類型說明如下。

"yyyyMMddHHmmss": 資料格式"20140209101000"
"yyyy-MM-dd HH:mm:ss"（預設）：資料格式"2014-02-09 10:10:00"
"yyyy年MM月dd日": 資料格式"2014年09月01日"

tunnel upload log.txt test_table -dfp "yyyy-MM-dd HH:mm:ss"

空值：所有資料類型都可以有空值。

• 預設Null 字元串為空白值。

• 可在命令列下通過-null-indicator參數來指定空值的字串。

  tunnel upload log.txt test_table -ni "NULL"

字元編碼：您可以指定檔案的字元編碼，預設為UTF-8。

tunnel upload log.txt test_table -c "gbk"

分隔字元：tunnel命令支援您自訂的檔案分隔字元，行分隔字元選項為-record-delimiter，資料行分隔符號選項為-field-delimiter。

• 支援多個字元的行資料行分隔符號。

• 資料行分隔符號不能夠包含行分隔字元。

• 逸出字元分隔字元，在命令列方式下只支援\r、\n和\t。

tunnel upload log.txt test_table -fd "||" -rd "\r\n"