MaxCompute通过Tunnel功能支持上传下载数据。本文为您提供Tunnel上传下载命令的详细说明。

Tunnel命令说明

  • 命令格式
    odps@ project_name>tunnel help;
        Usage: tunnel <subcommand> [options] [args]
        Type 'tunnel help <subcommand>' for help on a specific subcommand.
    Available subcommands:
        upload (u)
        download (d)
        resume (r)
        show (s)
        purge (p)
        help (h)
    tunnel is a command for uploading data to / downloading data from ODPS.
  • 参数说明
    • upload:上传数据到MaxCompute的表中。支持文件或目录(指一级目录)的上传,每一次上传只支持数据上传到一张表或表的一个分区。分区表一定要指定上传的分区,多级分区一定要指定到末级分区。
      -- 将log.txt中的数据上传至项目空间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;
    • download:从MaxCompute的表中下载数据。只支持下载到单个文件,每一次下载只支持下载一张表或一个分区到一个文件。分区表一定要指定下载的分区,多级分区一定要指定到末级分区。
      -- 将test_project.test_table表(二级分区表)中的数据下载到test_table.txt文件中。
      tunnel download  test_project.test_table/p1="b1",p2="b2"  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的表中,以追加模式导入。

  • 命令格式
    odps@ project_name>tunnel help upload;
    usage: tunnel upload [options] <path> <[project.]table[/partition]>
    
                  upload data from local file
     -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

        上传数据文件的路径以及名称。

      • [project.]table[/partition]

        目标表表名。如果是分区表,需要指定至最末级分区。如果不是当前空间的表,需要指定表所在的空间名。

    • 可选参数
      • -acp

        如果指定分区不存在,自动创建目标分区。默认值为False。

      • -bs

        指定每次上传至Tunnel的数据块大小。默认值为100 MiB(1 MiB=1024×1024 Byte)。

      • -c

        指定本地数据文件编码。默认不设定,下载源数据。

      • -cf

        指定是否为CSV文件,默认值为False。

      • -cp

        指定是否在本地压缩数据后再上传,减少网络流量。默认值为True。

      • -dbr

        指定是否忽略脏数据(多列、少列、列数据类型不匹配等情况)。默认值为False。

        • True:忽略全部不符合表定义的数据。
        • False:如果遇到脏数据,则给出错误提示信息,目标表内的原始数据不会被污染。
      • -dfp

        指定DATETIME类型数据格式,默认为yyyy-MM-dd HH:mm:ss。如果您想指定时间格式到毫秒级别,可以使用tunnel upload -dfp 'yyyy-MM-dd HH:mm:ss.SSS'。DATETIME数据类型详情请参见数据类型版本说明

      • -fd

        指定本地数据文件的列分割符。默认值为英文逗号(,)。

      • -h

        指定数据文件是否包括表头。默认值为False。如果为True,则dship会跳过表头从第二行开始上传数据。

      • -mbr

        指定可容忍的脏数据量。超过此数据量时,终止上传。默认值为1000条。

      • -ni

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

      • -ow
        指定上传数据是否覆盖表或分区。默认值为False,上传数据为累加方式。示例如下。
        tunnel upload -overwrite true log.txt test_project.test_table/p1="b1",p2="b2";
      • -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

  • 命令功能

    显示历史记录。

  • 命令格式
    odps@ project_name>tunnel help show;
    usage: tunnel show history [options]
                  show session information
     -n,-number <ARG>   lines
    Example:
           tunnel show history -n 5
           tunnel show log
  • 参数说明

    -n:指定显示行数。

  • 示例
    odps@ project_name>tunnel show history;
    20150610xxxxxxxxxxx70a002ec60c  failed  'u --config-file /D:/console/conf/odps_config.ini --project odpstest_ay52c_ay52 --endpoint http://service.odps.aliyun.com/api --id UlxxxxxxxxxxxrI1 --key 2m4r3WvTxxxxxxxxxx0InVke7UkvR d:\data.txt sale_detail/sale_date=201312,region=hangzhou -s false'
    说明 20150610xxxxxxxxxxx70a002ec60c是上传失败的Session ID。

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的执行结果下载至本地。

  • 命令格式
    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

        下载的数据文件保存的本地路径。

      • [project.]table[/partition]

        需要下载的表名称。如果是分区表,需要指定至最末级分区。如果不是当前空间的表,需要指定表所在的空间名。

      • [project/]instance_id

        Instance ID。下载指定Instance的执行结果时指定此参数。

    • 可选参数
      • -c

        指定本地数据文件编码,默认忽略。

      • -cf

        指定是否为CSV文件,默认值为False。

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