MaxCompute通过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的表中。支持文件的上传，每一次上传只支持数据上传到一张表或表的一个分区。分区表一定要指定上传的分区，多级分区一定要指定到末级分区。
说明 使用Tunnel命令过程中遇到的各类问题与最佳实践可参考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]
目标表表名。如果是分区表，需要指定至最末级分区。如果不是当前空间的表，需要指定表所在的空间名。
- path
- 可选参数
- -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。时区信息请参考时区列表。
- -acp
- 必选参数
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_id
- 示例执行如下命令修复上传数据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的执行结果时指定此参数。
- path
- 可选参数
- -c
指定本地数据文件编码，默认忽略。
- -cf
指定是否为CSV文件，默认值为False。
说明 Download仅支持TXT、CSV格式文件，默认下载TXT文件。如果下载CSV文件，需要指定-cf参数，同时请下载最新版本的MaxCompute客户端。 - -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。
- -c
- 必选参数
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"
