命令格式

tunnel <subcommand> [options] [args]

可選項(xiàng)說明：

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

參數(shù)說明

• upload：上傳數(shù)據(jù)到MaxCompute的表中。支持文件的上傳，每一次上傳只支持?jǐn)?shù)據(jù)上傳到一張表或表的一個(gè)分區(qū)。分區(qū)表一定要指定上傳的分區(qū)，多級(jí)分區(qū)一定要指定到末級(jí)分區(qū)。

  -- 將log.txt（在MaxCompute客戶端的bin目錄中）中的數(shù)據(jù)上傳至項(xiàng)目空間test_project的表test_table（二級(jí)分區(qū)表）中的p1="b1",p2="b2"分區(qū)。
  tunnel upload log.txt test_project.test_table/p1="b1",p2="b2";
  
  -- 將log.txt中的數(shù)據(jù)上傳至表test_table中。scan參數(shù)表示需要掃描log.txt中的數(shù)據(jù)是否符合test_table的定義，如果不符合報(bào)錯(cuò)，并停止上傳數(shù)據(jù)。
  tunnel upload  log.txt  test_table --scan=true;
  
  -- 將其他路徑下的log.txt中的數(shù)據(jù)上傳至項(xiàng)目空間test_project的表test_table（二級(jí)分區(qū)表）中的p1="b1",p2="b2"分區(qū)。
  tunnel upload D:\test\log.txt test_project.test_table/p1="b1",p2="b2";

• download：從MaxCompute的表中下載數(shù)據(jù)。只支持下載到單個(gè)文件，每一次下載只支持下載一張表或一個(gè)分區(qū)到一個(gè)文件。分區(qū)表一定要指定下載的分區(qū)，多級(jí)分區(qū)一定要指定到末級(jí)分區(qū)。

  -- 將test_project.test_table表（二級(jí)分區(qū)表）中的數(shù)據(jù)下載到test_table.txt文件中。
  tunnel download  test_project.test_table/p1="b1",p2="b2"  test_table.txt;
  -- 將test_project.test_table表（二級(jí)分區(qū)表）中的數(shù)據(jù)下載到其他路徑下。
  tunnel download  test_project.test_table/p1="b1",p2="b2"  D:\test\test_table.txt;

• resume：因?yàn)榫W(wǎng)絡(luò)或Tunnel服務(wù)的原因出錯(cuò)，支持續(xù)傳文件或目錄。如果上傳數(shù)據(jù)失敗，通過resume命令進(jìn)行斷點(diǎn)續(xù)傳，僅支持上傳數(shù)據(jù)的續(xù)傳。每次上傳、下載數(shù)據(jù)被稱為一個(gè)Session。在resume后指定session id完成續(xù)傳。

  tunnel resume;

• show：查看歷史運(yùn)行信息。

  --顯示前5次上傳或下載數(shù)據(jù)的詳細(xì)命令。
  tunnel show history -n 5;
  --顯示最后一次上傳或下載數(shù)據(jù)的日志。
  tunnel show log;

• purge：清理Session目錄，默認(rèn)清理3天內(nèi)的日志。

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

• help：輸出Tunnel幫助信息。

• upsert：結(jié)合Update和Insert語義，進(jìn)行數(shù)據(jù)寫入，僅Transaction Table 2.0類型表支持。

  若目標(biāo)表中未找到匹配數(shù)據(jù)，則會(huì)插入新數(shù)據(jù)；若數(shù)據(jù)已存在，則會(huì)進(jìn)行數(shù)據(jù)更新。

  -- 將log.txt（在MaxCompute客戶端的bin目錄中）中的數(shù)據(jù)上傳至項(xiàng)目空間test_project的表test_table（二級(jí)分區(qū)表）中的p1="b1",p2="b2"分區(qū)。
  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"

參數(shù)說明

• 必選參數(shù)

  • path

    上傳數(shù)據(jù)文件的路徑以及名稱。

    數(shù)據(jù)文件的歸檔路徑有兩種選擇：您可以將文件直接歸檔至MaxCompute客戶端的bin目錄中，此時(shí)path需要設(shè)置為文件名.后綴名；也可以將文件歸檔至其他路徑下，例如D盤的test文件夾，path需要設(shè)置為D:\test\文件名.后綴名。

    說明

    macOS系統(tǒng)中path值只能使用絕對(duì)路徑，例如文件歸檔在MaxCompute客戶端的bin目錄中，此時(shí)path需要設(shè)置為D:\MaxCompute\bin\文件名.后綴名。

  • [project.]table[/partition]

    目標(biāo)表表名。如果是分區(qū)表，需要指定至最末級(jí)分區(qū)。如果不是當(dāng)前空間的表，需要指定表所在的空間名。

• 可選參數(shù)

  • -acp

    如果指定分區(qū)不存在，自動(dòng)創(chuàng)建目標(biāo)分區(qū)。默認(rèn)值為False。

  • -bs

    指定每次上傳至Tunnel的數(shù)據(jù)塊大小。默認(rèn)值為100 MiB（1 MiB＝1024×1024 Byte）。

    說明

    并發(fā)寫入場(chǎng)景，MaxCompute會(huì)根據(jù)ACID進(jìn)行并發(fā)寫入保障。關(guān)于ACID的具體語義，請(qǐng)參見ACID語義。

  • -c

    指定本地?cái)?shù)據(jù)文件編碼。默認(rèn)不設(shè)定，下載源數(shù)據(jù)。

  • -cf

    指定是否為CSV文件，默認(rèn)值為False。

    說明

    Upload僅支持TXT、CSV格式文件，默認(rèn)上傳TXT文件。如果上傳CSV文件，需要指定-cf參數(shù)，同時(shí)請(qǐng)下載最新版本的MaxCompute客戶端。

  • -cp

    指定是否在本地壓縮數(shù)據(jù)后再上傳，減少網(wǎng)絡(luò)流量。默認(rèn)值為True。

  • -dbr

    指定是否忽略臟數(shù)據(jù)（多列、少列、列數(shù)據(jù)類型不匹配等情況）。默認(rèn)值為False。

    • True：忽略全部不符合表定義的數(shù)據(jù)，默認(rèn)忽略條數(shù)為1000條，如果想更改忽略條數(shù)，需要加上-mbr參數(shù)。

    • False：如果遇到臟數(shù)據(jù)，則給出錯(cuò)誤提示信息，目標(biāo)表內(nèi)的原始數(shù)據(jù)不會(huì)被污染。

  • -dfp

    指定DATETIME類型數(shù)據(jù)格式，默認(rèn)為yyyy-MM-dd HH:mm:ss。如果您想指定時(shí)間格式到毫秒級(jí)別，可以使用tunnel upload -dfp 'yyyy-MM-dd HH:mm:ss.SSS'。DATETIME數(shù)據(jù)類型詳情請(qǐng)參見數(shù)據(jù)類型版本說明。

  • -fd

    指定本地?cái)?shù)據(jù)文件的列分割符。默認(rèn)值為英文逗號(hào)（,）。

  • -h

    指定待上傳的數(shù)據(jù)文件是否可以包含表頭。默認(rèn)值為False，表示上傳的數(shù)據(jù)文件中不可以包含表頭。如果值為True，表示上傳的數(shù)據(jù)文件中可以包含表頭，會(huì)跳過表頭從第二行開始上傳數(shù)據(jù)。

  • -mbr

    此參數(shù)需要配合-dbr參數(shù)使用，當(dāng)-dbr設(shè)置為true時(shí)，設(shè)置此參數(shù)才有意義。指定可容忍的臟數(shù)據(jù)量。超過此數(shù)據(jù)量時(shí)，終止上傳。默認(rèn)值為1000條。

  • -ni

    指定NULL數(shù)據(jù)標(biāo)識(shí)符。默認(rèn)值為空字符串。

  • -ow

    指定上傳數(shù)據(jù)是否覆蓋表或分區(qū)。默認(rèn)值為False，上傳數(shù)據(jù)為累加方式。示例如下。

    --創(chuàng)建分區(qū)表
    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');
    
    --本地準(zhǔn)備好數(shù)據(jù)文件d:\data.txt，文件內(nèi)容如下：
    shopx,x_id,100
    shopy,y_id,200
    
    --上傳數(shù)據(jù)到分區(qū)表
    tunnel upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou;
    
    --查詢sale_detail表
    select * from sale_detail;
    
    --返回結(jié)果
    +------------+-------------+-------------+------------+------------+
    | 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的數(shù)據(jù)，文件內(nèi)容如下：
    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;
    
    --返回結(jié)果
    +------------+-------------+-------------+------------+------------+
    | shop_name  | customer_id | total_price | sale_date  | region     |
    +------------+-------------+-------------+------------+------------+
    | shopx      | x_id        | 300.0       | 201312     | hangzhou   |
    | shopy      | y_id        | 400.0       | 201312     | hangzhou   |
    +------------+-------------+-------------+------------+------------+

  • -rd

    指定本地?cái)?shù)據(jù)文件的行分割符。默認(rèn)值為\r\n。

  • -s

    指定是否掃描本地?cái)?shù)據(jù)文件。默認(rèn)值為True。

    • True：先掃描數(shù)據(jù)，若數(shù)據(jù)格式正確，再導(dǎo)入數(shù)據(jù)。

    • False：不掃描數(shù)據(jù)，直接導(dǎo)入數(shù)據(jù)。

    • Only：僅掃描本地?cái)?shù)據(jù)，掃描結(jié)束后不繼續(xù)導(dǎo)入數(shù)據(jù)。

  • -sd

    指定Session目錄。

  • -ss

    指定嚴(yán)格架構(gòu)模式。默認(rèn)值為True。如果為False，多余的數(shù)據(jù)將被丟棄，不足的字段將填充NULL。

  • -t

    指定Threads的數(shù)量。默認(rèn)值為1。

  • -te

    指定Tunnel的Endpoint。

  • -time

    指定是否跟蹤上傳所用時(shí)間。默認(rèn)值為False。

  • -tz

    指定時(shí)區(qū)。默認(rèn)值為本地時(shí)區(qū)，例如Asia/Shanghai。時(shí)區(qū)信息請(qǐng)參考時(shí)區(qū)列表。

顯示歷史記錄。

• 命令格式

  tunnel show history [-n <number>];

  -n <number>：tunnel執(zhí)行的次數(shù)。

• 命令示例

  示例1：顯示歷史記錄，默認(rèn)保存500條數(shù)據(jù)。

  tunnel show history;

  返回結(jié)果：

  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次上傳或下載數(shù)據(jù)的詳細(xì)命令。

  tunnel show history -n 5;

  返回結(jié)果：

  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'

顯示最后一次上傳或下載數(shù)據(jù)的日志。

tunnel show log;

命令功能

修復(fù)執(zhí)行歷史記錄，僅對(duì)上傳數(shù)據(jù)有效。

命令格式

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

參數(shù)說明

• session_id

  上傳失敗的Session ID。必選參數(shù)。

• -f

  指定是否強(qiáng)制修復(fù)執(zhí)行歷史記錄。默認(rèn)忽略。

示例

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表數(shù)據(jù)或指定Instance的執(zhí)行結(jié)果下載至本地。

使用Tunnel下載數(shù)據(jù)時(shí)，您需要擁有Download權(quán)限。如果無Download權(quán)限，需要聯(lián)系Project Owner或具備Super_Administrator角色的用戶完成授權(quán)操作。更多Download權(quán)限授權(quán)操作，請(qǐng)參見Policy權(quán)限控制。

命令格式

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 //下載指定表數(shù)據(jù)
    tunnel download instance://test_project/test_instance log.txt   //下載指定Instance的執(zhí)行結(jié)果

參數(shù)說明

• 必選參數(shù)

  • path

    下載的數(shù)據(jù)文件保存的本地路徑。

    數(shù)據(jù)文件的保存路徑有兩種選擇：您可以將文件直接下載至MaxCompute客戶端的bin目錄中，此時(shí)path需要設(shè)置為文件名.后綴名；也可以將文件下載至其他路徑下，例如D盤的test文件夾，path需要設(shè)置為D:\test\文件名.后綴名。

  • [project.]table[/partition]

    需要下載的表名稱。如果是分區(qū)表，需要指定至最末級(jí)分區(qū)。如果不是當(dāng)前空間的表，需要指定表所在的空間名。

  • [project/]instance_id

    Instance ID。下載指定Instance的執(zhí)行結(jié)果時(shí)指定此參數(shù)。

• 可選參數(shù)

  • -c

    指定本地?cái)?shù)據(jù)文件編碼，默認(rèn)忽略。

  • -cf

    指定是否為CSV文件，默認(rèn)值為False。

    說明

    Download僅支持TXT、CSV格式文件，默認(rèn)下載TXT文件。如果需要下載CSV文件，需要指定-cf true參數(shù)，同時(shí)請(qǐng)下載最新版本的MaxCompute客戶端。指定-cf true參數(shù)后，文件分隔符只能是半角逗號(hào)（,），即便您再使用-fd參數(shù)指定文件分隔符也將不起作用。

  • -ci

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

  • -cn

    指定要下載的列名稱，使用英文逗號(hào)（,）分隔每個(gè)名稱。

  • -cp

    指定是否壓縮后再下載，減少網(wǎng)絡(luò)流量，默認(rèn)值為True。

  • -dfp

    指定DATETIME類型數(shù)據(jù)格式，默認(rèn)格式為yyyy-MM-dd HH:mm:ss。

  • -e

    指定下載DOUBLE類型值時(shí)，如果需要，使用指數(shù)函數(shù)表示，否則最多保留20位。默認(rèn)值為False。

  • -fd

    指定本地?cái)?shù)據(jù)文件的列分割符，默認(rèn)值為半角逗號(hào)（,）。

  • -h

    指定導(dǎo)出的數(shù)據(jù)文件是否包含表頭。默認(rèn)值為False，表示導(dǎo)出數(shù)據(jù)文件中不包含表頭。如果值為True，表示導(dǎo)出數(shù)據(jù)文件中包含表頭。

    說明

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

  • -limit

    指定要下載的行數(shù)。

  • -ni

    指定NULL數(shù)據(jù)標(biāo)識(shí)符，默認(rèn)為空字符串。

  • -rd

    指定本地?cái)?shù)據(jù)文件的行分割符，默認(rèn)值為\r\n。

  • -sd

    指定Session目錄。

  • -t

    指定Threads的數(shù)量，默認(rèn)值為1。

  • -te

    指定Tunnel Endpoint。

  • -time

    指定是否跟蹤下載所用時(shí)間。默認(rèn)值為False。

  • -tz

    指定時(shí)區(qū)。默認(rèn)為本地時(shí)區(qū)，例如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

參數(shù)說明

n：清除歷史日志的天數(shù)。默認(rèn)為3天。

數(shù)據(jù)類型說明如下。

"yyyyMMddHHmmss": 數(shù)據(jù)格式"20140209101000"
"yyyy-MM-dd HH:mm:ss"（默認(rèn)）：數(shù)據(jù)格式"2014-02-09 10:10:00"
"yyyy年MM月dd日": 數(shù)據(jù)格式"2014年09月01日"

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

空值：所有數(shù)據(jù)類型都可以有空值。

• 默認(rèn)空字符串為空值。

• 可在命令行下通過-null-indicator參數(shù)來指定空值的字符串。

  tunnel upload log.txt test_table -ni "NULL"

字符編碼：您可以指定文件的字符編碼，默認(rèn)為UTF-8。

tunnel upload log.txt test_table -c "gbk"

分隔符：tunnel命令支持您自定義的文件分隔符，行分隔符選項(xiàng)為-record-delimiter，列分隔符選項(xiàng)為-field-delimiter。

• 支持多個(gè)字符的行列分隔符。

• 列分隔符不能夠包含行分隔符。

• 轉(zhuǎn)義字符分隔符，在命令行方式下只支持\r、\n和\t。

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