当您需要在本地环境与MaxCompute之间传输大量的数据时，MaxCompute提供Tunnel功能支持上传下载数据，使用Tunnel命令可以实现批量或增量数据的高效上传、下载，以提高数据传输效率和可靠性。本文为您介绍Tunnel上传下载命令的详细说明。
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";
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=true和threads>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天。
Upsert
命令功能
结合Update和Insert语义，若目标表中未找到匹配数据，则会插入新数据；若数据已存在，则会进行数据更新。
说明若您使用本地客户端（odpscmd）执行Upsert命令，必须确保odpscmd版本为V0.47及以上。
仅Transaction Table 2.0类型表支持Upsert命令。
命令格式
tunnel upsert[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) -qn,-quota_name <ARG> quota name -rd,-record-delimiter <ARG> specify record delimiter, support unicode, eg \u0001. default "\n" -sd,-session-dir <ARG> set session dir, default /Users/dingxin/Documents/debug/plugin s/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 -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 upsert 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。
说明Upsert仅支持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数据标识符。默认值为空字符串。
-qn：访问MaxCompute使用的Tunnel Quota名称。
您可以登录MaxCompute控制台，左上角切换地域后，在左侧导航栏选择工作区>配额（Quota）管理，获取Quota名称。具体操作，请参见Quota管理（新版）。
-rd
指定本地数据文件的行分割符。默认值为
\r\n。-sd
指定Session目录。
-ss
指定严格架构模式。默认值为True。如果为False，则多余的数据将被丢弃，不足的字段将填充NULL。
-te
指定Tunnel的Endpoint。关于Endpoint详情，请参见Endpoint。
-time
指定是否跟踪上传所用时间。默认值为False。
-tz
指定时区。默认值为本地时区，例如Asia/Shanghai。时区信息请参考时区列表。
注意事项
数据类型说明如下。
类型
描述
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"