全部产品
Search
文档中心

云原生大数据计算服务 MaxCompute:Tunnel命令

更新时间:Jan 10, 2024

当您需要在本地环境与MaxCompute之间传输大量的数据时,MaxCompute提供Tunnel功能支持上传下载数据,使用Tunnel命令可以实现批量或增量数据的高效上传、下载,以提高数据传输效率和可靠性。本文为您介绍Tunnel上传下载命令的详细说明。

Tunnel命令说明

  • 命令格式

    tunnel <subcommand> [options] [args]

    可选项说明:

    Available subcommands:
        upload (u)
        download (d)
        resume (r)
        show (s)
        purge (p)
        help (h)
  • 参数说明

    • 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帮助信息。

Upload

  • 命令功能

    将本地文件的数据上传至MaxCompute的表中,以追加模式导入。

    说明

    追加模式:如果MaxCompute表中已存在要导入的数据,执行上传命令后,该数据不会被覆盖,而是会出现两条同样的数据。

  • 命令格式

    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。时区信息请参考时区列表

Show

  • 显示历史记录。

    • 命令格式

      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;

Resume

  • 命令功能

    修复执行历史记录,仅对上传数据有效。

  • 命令格式

    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

      指定是否强制修复执行历史记录。默认忽略。

  • 示例

    执行如下命令修复上传数据Session。20150610xxxxxxxxxxx70a002ec60c为上传失败的Session ID。

    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

Download

  • 命令功能

    将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=truethreads>1(多线程)不能一起使用。

      • -limit

        指定要下载的行数。

      • -ni

        指定NULL数据标识符,默认为空字符串。

      • -rd

        指定本地数据文件的行分割符,默认值为\r\n

      • -sd

        指定Session目录。

      • -t

        指定Threads的数量,默认值为1。

      • -te

        指定Tunnel Endpoint。

      • -time

        指定是否跟踪下载所用时间。默认值为False。

      • -tz

        指定时区。默认为本地时区,例如Asia/Shanghai。

Purge

  • 命令功能

    清除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天。

注意事项

  • 数据类型说明如下。

    类型

    描述

    STRING

    字符串类型,长度不能超过8 MB。

    BOOLEAN

    上传值只支持True、False、0或1。下载值为True或False。不区分大小写。

    BIGINT

    取值范围为[-9223372036854775807,9223372036854775807]

    DOUBLE

    • 有效位数为16位。

    • 上传支持科学计数法表示。

    • 下载仅使用数字表示。

    • 最大值:1.7976931348623157E308。

    • 最小值:4.9E-324。

    • 无穷大:Infinity。

    • 无穷小:-Infinity。

    DATETIME

    DATETIME类型默认支持时区为GMT+8的数据上传,可以通过命令行指定用户数据日期格式的format pattern。如果您上传DATETIME类型的数据,需要指定时间日期格式,具体格式请参见数据类型版本说明

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

相关文档