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

    说明

    并发写入场景，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"