阿里云云原生大数据计算服务 MaxCompute使用说明-云淘科技

支持的工具

MaxCompute支持使用odpscmd和MaxCompute Studio运行Tunnel命令。具体操作请参见使用客户端（odpscmd）连接和认识MaxCompute Studio。

Tunnel命令功能

您可以通过客户端提供的Tunnel命令实现原有Dship工具的功能。Tunnel命令主要用于数据的上传和下载等，其功能如下：

• Upload：上传本地数据至MaxCompute表中。支持文件的上传，每一次上传只支持数据上传到一张表或表的一个分区。分区表一定要指定上传的分区，多级分区一定要指定到末级分区。更多信息请参见Upload 。
• Download：下载MaxCompute表或指定Instance执行结果至本地。只支持下载到单个文件，每一次下载只支持下载一张表或一个分区到一个文件。分区表一定要指定下载的分区，多级分区一定要指定到末级分区。更多信息请参见Download。
• Resume：因为网络或Tunnel服务的原因造成上传出错，可以通过Resume命令对文件进行续传。可以继续上一次的数据上传操作，但Resume命令暂时不支持下载操作。更多信息请参见Resume。
• Show：显示历史任务信息。更多信息请参见Show 。
• Purge：清理session目录，默认清理3天内的日志。更多信息请参见Purge。
• help：获取帮助信息，每个命令和选择支持短命令格式。

说明 使用Tunnel命令过程中遇到的各类问题请参见Tunnel命令常见问题。

Tunnel上传下载限制

• Tunnel功能及Tunnel SDK当前不支持外部表操作。您可以通过Tunnel直接上传数据到MaxCompute内部表，或者是通过OSS Python SDK上传到OSS后，在MaxCompute使用外部表做映射。关于外部表详情请参见概述。
• Tunnel命令不支持上传下载ARRAY、MAP和STRUCT类型的数据。
• 每个Tunnel的Session在服务端的生命周期为24小时，创建后24小时内均可使用，也可以跨进程/线程共享使用，但是必须保证同一个BlockId没有重复使用。说明 Tunnel Session：Server端会为该Upload/Download创建一个Session， 生成唯一UploadId/DownloadId标识该Upload/Download。Tunnel的Session在服务端的生命周期为24小时，超过24小时后，该Session将不可用。
• 如果您根据Session下载，请注意只有主账号创建的Session，可以被主账号及所属子账号下载。

上传下载表数据

在操作之前，您需要准备待上传的数据文件data.txt，保存路径为d:\data.txt。文件内容如下所示。

shopx,x_id,100
shopy,y_id,200
shopz,z_id

说明 data.txt文件中第三行数据与下文中创建的分区表sale_detail的表定义不符，sale_detail定义了三列，但该行数据只有两列。上传下载表数据示例步骤如下。

1. 在MaxCompute客户端，执行如下语句创建分区表sale_detail，并为分区表sale_detail添加分区。

   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');

2. 使用upload命令上传数据文件data.txt至分区表sale_detail。
   • 命令示例

     tunnel upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -s false;

   • 返回结果

     Upload session: 20230505xxxxxxxxxxxb0b02dbb6bd
     Start upload:d:\data.txt
     Using \r
      to split records
     Upload in strict schema mode: true
     Total bytes:42   Split input to 1 blocks
     2023-05-05 10:11:35     upload block: '1'
     ERROR: column mismatch -,expected 3 columns, 2 columns found, please check data or delimiter

     说明 由于data.txt中有脏数据，数据导入失败，并给出session ID及错误提示信息。

3. 使用如下语句进行数据验证。
   • 命令示例

     select * from sale_detail where sale_date='201312';

   • 返回结果

     ID = 20230505xxxxxxxxxxxvc61z5+-----------+-------------+-------------+-----------+--------+| shop_name | customer_id | total_price | sale_date | region |+-----------+-------------+-------------+-----------+--------++-----------+-------------+-------------+-----------+--------+

     说明 由于有脏数据，数据导入失败，表中无数据。

4. 使用show命令查询失败上传的session ID。
   • 命令示例

     tunnel show history;

   • 返回结果

     20230505xxxxxxxxxxxb0b02dbb6bd  failed  'upload d:\data.txt sale_detail/sale_date=201312,region=hangzhou -s false'

5. 修改示例数据data.txt文件为如下内容，符合sale_detail的表结构。

   shopx,x_id,100shopy,y_id,200

6. 执行resume命令修复执行上传数据。其中，20230505xxxxxxxxxxxb0b02dbb6bd为上传失败的session ID。
   • 命令示例

     tunnel resume 20230505xxxxxxxxxxxb0b02dbb6bd --force;

   • 返回结果

     start resume20230505xxxxxxxxxxxb0b02dbb6bdUpload session: 20230505xxxxxxxxxxxb0b02dbb6bdStart upload:d:\data.txtUsing \r to split recordsUpload in strict schema mode: trueResume 1 blocks 2023-05-05 10:32:39     upload block: '1'2023-05-05 10:32:40     upload block complete, block id: 1upload complete, average speed is 0 bytes/sOK

7. 执行如下语句进行数据验证，上传成功。
   • 命令示例

     select * from sale_detail where sale_date='201312';

   • 返回结果

     ID = 20230505xxxxxxxxxxxx7afc9qcg +-----------+-------------+-------------+-----------+--------+ | shop_name | customer_id | total_price | sale_date | region | +-----------+-------------+-------------+-----------+--------+ | shopx     | x_id        | 100.0       | 201312    | hangzhou| | shopy     | y_id        | 200.0       | 201312    | hangzhou| +-----------+-------------+-------------+-----------+--------+

8. 执行download命令将表sale_detail上的数据下载至本地result.txt。说明 此处将数据下载至本地路径path的命名规则如下：
   • 您可以将文件直接归档至MaxCompute客户端的bin目录中，此时path需要设置为文件名.后缀名。
   • 也可以将文件归档至其他路径下，例如D盘的test文件夹，path需要设置为D: est\文件名.后缀名。
   • 如果本地存在同名文件，会直接覆盖。

   tunnel download sale_detail/sale_date=201312,region=hangzhou result.txt;

9. 验证result.txt的文件内容，如下所示，下载成功。 说明 下载成功后的文件中，只显示非分区字段值。

   shopx,x_id,100.0shopy,y_id,200.0

下载Instance数据

• 方式一：使用tunnel download命令将特定Instance的执行结果下载到本地文件。
  1. 执行SELECT语句查询表sale_detail。

     select * from sale_detail;

     说明 如果前面已经对分区表sale_detail设置了禁止全表扫描，此处执行会报错Table(xxxx) is full scan with all partitions, please specify partition predicates，请参考错误码附录进行设置。

  2. 执行如下Tunnel命令下载执行结果到本地文件。

     --查看SELECT命令的instance IDshow p;--执行下载命令tunnel download instance://20170724071705393ge3csfb8 result.txt;

• 方式二：通过配置参数使SQL查询默认采用InstanceTunnel方式输出执行结果。 在MaxCompute客户端中打开use_instance_tunnel选项后，执行的SELECT查询会默认使用InstanceTunnel来下载结果，从而避免在MaxCompute平台获取SQL查询结果时所遇到的获取数据超时和获取数据量受限的问题。打开该配置有以下两种方法： 说明 InstanceTunnel的约束与限制请参见InstanceTunnel约束与限制。
  • 在最新版本的客户端中，odps_config.ini文件里已经默认打开此选项，并且instance_tunnel_max_record被默认设置成了10000。

    # download sql results by instance tunneluse_instance_tunnel=true# the max records when download sql results by instance tunnelinstance_tunnel_max_record=10000

    说明 instance_tunnel_max_record用来设置通过InstanceTunnel下载SQL查询结果的条数。若不设置该项，则下载条数不受限制。

  • 将set console.sql.result.instancetunnel设置为true来开启此功能。
    • 打开Instance tunnel选项。

      set console.sql.result.instancetunnel=true;

    • 运行select query。

      select * from wc_in;

      返回结果如下。

      ID = 20170724081946458g14csfb8
      Log view:
      http://logview/xxxxx.....
      +------------+
      | key        |
      +------------+
      | slkdfj     |
      | hellp      |
      | apple      |
      | tea        |
      | peach      |
      | apple      |
      | tea        |
      | teaa       |
      +------------+
      A total of 8 records fetched by instance tunnel. Max record number: 10000

    说明 如果用InstanceTunnel的方式来输出SELECT查询结果，系统在最后一行会打印一条提示，此示例中Instance的执行结果共有8条数据。同理，您可以将set console.sql.result.instancetunnel设置为false来关闭此功能。