命令格式

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

    說明

    并發寫入場景，MaxCompute會根據ACID進行并發寫入保障。關于ACID的具體語義，請參見ACID語義。

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