使用說明 - MaxCompute

本文為您介紹Tunnel命令的功能和如何通過Tunnel命令上傳下載資料。

支援的工具

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：擷取協助資訊，每個命令和選擇支援短命令格式。
Upsert：結合Update和Insert語義，進行資料寫入，僅Transaction Table 2.0類型表支援。
若目標表中未找到匹配資料，則會插入新資料；若資料已存在，則會進行資料更新。

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定義了三列，但該行資料只有兩列。

上傳下載表資料樣本步驟如下。

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

使用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\n 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及錯誤提示資訊。

使用如下語句進行資料驗證。

命令樣本

select * from sale_detail where sale_date='201312';

返回結果

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

說明

由於有髒資料，資料匯入失敗，表中無資料。

使用show命令查詢失敗上傳的session ID。

命令樣本
```
tunnel show history;
```

返回結果

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

修改樣本資料data.txt檔案為如下內容，符合sale_detail的表結構。
```
shopx,x_id,100
shopy,y_id,200
```

執行resume命令修複執行上傳資料。其中，20230505xxxxxxxxxxxb0b02dbb6bd為上傳失敗的session ID。

命令樣本

tunnel resume 20230505xxxxxxxxxxxb0b02dbb6bd --force;

返回結果

start resume
20230505xxxxxxxxxxxb0b02dbb6bd
Upload session: 20230505xxxxxxxxxxxb0b02dbb6bd
Start upload:d:\data.txt
Using \r\n to split records
Upload in strict schema mode: true
Resume 1 blocks 
2023-05-05 10:32:39     upload block: '1'
2023-05-05 10:32:40     upload block complete, block id: 1
upload complete, average speed is 0 bytes/s
OK

執行如下語句進行資料驗證，上傳成功。

命令樣本

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

執行download命令將表sale_detail上的資料下載至本地result.txt。
說明
此處將資料下載至本地路徑path的命名規則如下：
- 您可以將檔案直接歸檔至MaxCompute用戶端的bin目錄中，此時path需要設定為檔案名稱.尾碼名。
- 也可以將檔案歸檔至其他路徑下，例如D盤的test檔案夾，path需要設定為D:\test\檔案名稱.尾碼名。
- 如果本地存在同名檔案，會直接覆蓋。
```
tunnel download sale_detail/sale_date=201312,region=hangzhou result.txt;
```
驗證result.txt的檔案內容，如下所示，下載成功。
說明
下載成功後的檔案中，只顯示非分區欄位值。
```
shopx,x_id,100.0
shopy,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 ID
show 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 tunnel
use_instance_tunnel=true
# the max records when download sql results by instance tunnel
instance_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來關閉此功能。