MaxCompute客戶端常用命令

MaxCompute客戶端命令

最新的MaxCompute服務對常用命令做了調整，新的命令風格更貼近於Hive的使用方式，方便原有的Hadoop和Hive用戶。MaxCompute提供了對項目空間、表、資源和實例等對象的一系列操作。您可以通過客戶端命令或SDK來操作這些對象。包括：

• 項目空間操作
• 表操作
• 實例操作
• 資源操作
• 函數操作
• SET操作
• 時區配置操作（暫略，具體見：時區配置操作）
• 其他

對於MaxCompute客戶端命令，可以使用odpscmd客戶端進行運行，也可以使用IDEA MaxCompute Studio中創建的SQL Script文件中運行。客戶端和基本開發環境的構建見：MaxCompute基礎開發環境搭建。下面命令在IDEA MaxCompute Studio中創建的SQL Script文件運行。

具體內容參考自：MaxCompute官方文檔。

項目空間操作命令

1. 進入項目空間（use）

-- 使用項目空間
use YITIAN_BJ_MC;

2. 訪問該項目空間下的表

select * from emp;

3. 訪問另一項目空間下的對象，需要指定項目空間名：

--在my_project_test空間下訪問另一項目空間my_project2下的表test_src。
odps @ my_project_test>select * from my_project2.test_src;

4. 列出所有項目空間（list projects）

-- 列出所有項目空間
list projects;

-- 返回結果
Project Name                                 Comment                       Creation Time                        Last Modified Time                   
yitian_bj_dev                                                              2020-04-15 15:49:07                  2020-04-15 15:49:07                  
yitian_bj_dev_dev                                                          2020-04-15 15:49:15                  2020-04-15 15:49:15                  
yitian_bj_mc                                                               2019-05-29 17:26:39                  2020-02-17 13:57:51                  
yitian_bj_mc_dev                                                           2019-05-29 17:26:51                  2020-02-17 13:57:53                  
yitian_maxcompute                                                          2019-05-29 11:25:24                  2020-02-17 13:57:55                  
yitian_maxcompute_s_dev                                                    2019-05-29 11:32:36                  2020-02-17 13:57:57    

5. 設置項目空間屬性（setproject）

-- 命令格式
setproject <KEY>=<VALUE>;

-- 設置允許全表掃描
setproject odps.sql.allow.fullscan=true;

--顯示setproject設置的參數。
setproject;

Project屬性可設置的選項見：Project屬性詳細說明。

6. 設置IP白名單

-- 設置公網下IP白名單
setproject odps.security.ip.whitelist= IP Address
-- 設置VPC網絡下IP白名單
setproject odps.security.vpc.whitelist= RegionID_VPCID[IP address]

白名單中具體IP的配置見：項目空間操作。

表操作

1. 創建表（create table）

-- 命令格式
CREATE TABLE [IF NOT EXISTS] table_name
 [(col_name data_type [COMMENT col_comment], ...)]
 [COMMENT table_comment]
 [PARTITIONED BY (col_name data_type [COMMENT col_comment], ...)]
 [LIFECYCLE days]
 [AS select_statement]
 CREATE TABLE [IF NOT EXISTS] table_name
 LIKE existing_table_name

其中需要說明的是：

IF NOT EXISTS: 在創建表時，如果不指定IF NOT EXISTS選項而存在同名表，則返回出錯；如果指定此選項，則無論是否存在同名表，即使原表結構與要創建的目標表結構不一致，均返回成功。已存在的同名表的元信息不會被改動。

PARTITIONED BY：指定表的分區字段。MaxCompute 1.0版僅支持STRING類型。MaxCompute 2.0版對分區類型的支持進行了擴充，支持TINYINT、SMALLINT、INT、BIGINT、VARCHAR和STRING分區類型。當利用分區字段對錶進行分區時，新增分區、更新分區內數據和讀取分區數據均不需要做全表掃描，提高處理效率。

LIFECYCLE：指明此表的生命週期，僅支持正整數。單位：天。

• 對於非分區表：自最後一次數據被修改開始計算，經過days天后數據仍未被改動，則此表無需您干預，將會被MaxCompute自動回收（類似drop table操作）。
• 對於分區表：根據各分區的LastDataModifiedTime判斷該分區是否該被回收。不同於非分區表，分區表的最後一個分區被回收後，該表不會被刪除。生命週期只能設定到表級別，不能在分區級設置生命週期。

--如果沒有同名表存在，創建一張分區表sale_deail。
CREATE TABLE IF NOT EXISTS sale_detail(
  shop_name     STRING,
  customer_id   STRING,
  total_price   DOUBLE)
PARTITIONED BY (sale_date STRING,region STRING);

--創建非分區表test1。
create table test1 (key string);

--創建分區表test2。
create table test2 (key bigint) partitioned by (pt string, ds string);

--創建帶有生命週期的表test3。
create table test3 (key boolean) partitioned by (pt string, ds string) lifecycle 100;

-- 除生命週期屬性外，test4的其他屬性（字段類型、分區類型等）均與test3完全一致。
create table test4 like test3;

-- 這個操作會創建test5，但分區生命週期信息不會被拷貝到目標表中。此操作僅會將test2的數據複製到test5中（如果test2有數據，此示例中test2爲空表，後續章節會介紹數據導入）。
create table test5 as select * from test2;

2. 修改表的owner（alter table）

-- 命令格式
ALTER TABLE table_name CHANGEOWNER to new_owner;

-- 將表test1的所有人修改爲[email protected]。
ALTER TABLE test1 CHANGEOWNER to '[email protected]';

3. 刪除表（drop table）

-- 命令格式
DROP TABLE [IF EXISTS] table_name; 

--刪除表sale_detail。如果表存在，返回成功。
DROP TABLE sale_detail; 
--刪除表sale_detail。無論sale_detail表是否存在，均返回成功。
DROP TABLE IF EXISTS sale_detail; 

如果不指定IF EXISTS選項而表不存在，則返回異常；如果指定此選項，無論表是否存在，均返回成功。

4. 查看錶信息（desc） 

-- 查看錶或者視圖信息
DESC <table_name>; 

-- 查看外部表信息
DESC extended <table_name>; 

具體返回的信息如下：

• Owner：表的屬主。
• Project：表所屬的項目空間。
• CreateTime：創建時間。
• LastDDLTime：最後一次DDL操作時間。
• LastModifiedTime：表中的數據最後一次被改動的時間。
• InternalTable：表示被描述的對象是表，總是顯示YES。
• Size：表數據所佔壓縮後的存儲容量大小，壓縮比一般爲5倍，單位Byte。
• Native Columns：非分區列的信息，包括列名、類型和備註。
• Partition Columns：分區列信息，包括分區名、類型和備註。
• Extended Info：外部表StorageHandler 、Location等信息。

DESC sale_detail; 

-- 返回信息
+------------------------------------------------------------------------------------+
| Owner: [email protected] | Project: yitian_bj_mc                                |
| TableComment:                                                                      |
+------------------------------------------------------------------------------------+
| CreateTime:               2019-05-31 10:43:36                                      |
| LastDDLTime:              2019-05-31 10:43:36                                      |
| LastModifiedTime:         2019-05-31 14:59:55                                      |
+------------------------------------------------------------------------------------+
| InternalTable: YES      | Size: 1440                                               |
+------------------------------------------------------------------------------------+
| Native Columns:                                                                    |
+------------------------------------------------------------------------------------+
| Field           | Type       | Label | Comment                                     |
+------------------------------------------------------------------------------------+
| shop_name       | string     |       |                                             |
| customer_id     | string     |       |                                             |
| total_price     | double     |       |                                             |
+------------------------------------------------------------------------------------+
| Partition Columns:                                                                 |
+------------------------------------------------------------------------------------+
| sale_date       | string     |                                                     |
| region          | string     |                                                     |
+------------------------------------------------------------------------------------+

5. 查看錶的分區信息（desc partitions）

-- 命令格式
desc table_name partition(pt_spec);

-- 使用示例
desc meta.m_security_users partition (ds='20151010');
+------------------------------------------------------------------------------------+
| PartitionSize: 2109112                                                             |
+------------------------------------------------------------------------------------+
| CreateTime:               2015-10-10 08:48:48                                      |
| LastDDLTime:              2015-10-10 08:48:48                                      |
| LastModifiedTime:         2015-10-11 01:33:35                                      |
+------------------------------------------------------------------------------------+
OK

6. 查看項目空間的表（show tables）

-- 列出當前項目空間下所有的表
SHOW TABLES;

-- 列出當前項目空間下表名與'chart'匹配上的表，支持正則表達式
SHOW TABLES like 'chart';

7. 查看錶的分區信息（show partitions）

-- 命令格式
SHOW PARTITIONS table_name; 

-- 使用示例
SHOW PARTITIONS sale_detail; 
-- 返回信息
sale_date=201312/region=hangzhou
OK

 列出一張表中的所有分區，表不存在或非分區表時報錯。

實例操作

在MaxCompute中，部分任務（Task）在執行時會被實例化，以MaxCompute實例（下文簡稱爲實例或Instance）的形式存在。

1. 查看示例信息（Show Instances/Show P）

-- 命令格式
SHOW INSTANCES [FROM startdate TO enddate] [number];
SHOW P [FROM startdate TO enddate] [number];
SHOW INSTANCES [-all];
SHOW P [-all];
SHOW P -p <project name>;

參數說明

• startdate、enddate：返回指定時間段內提交的實例，即從起始時間startdate到結束時間enddate提交的實例信息，需滿足格式：yyyy-mm-dd，精度到天。可選參數，如果不指定，則返回您在三天內提交的實例。
• number：指定返回實例的數量。依照時間排序，返回提交距離當前時間最近的number個實例信息。如果不指定number，則返回滿足要求的所有實例信息。
• -all：返回當前項目下所有執行過的實例，默認最大返回50條。注意執行該命令的用戶需要有項目空間的List權限。如果需要返回更多條記錄，請使用-limit number參數，例如show p -all -limit 100表示返回當前項目下100條執行過的實例記錄。
• project name：項目名稱，您使用的賬號必須已經是項目成員。

返回由當前用戶創建的實例信息。查詢結果輸出項包括：StartTime（時間精確到秒）、RunTime（s）、Status（實例狀態）。Instance有以下6種狀態：

• Running：正在運行。
• Success：成功結束。
• Waiting：等待中。
• Failed：作業失敗，但是尚未改寫目標表數據。
• Suspended：掛起。
• Cancelled：被中止。

2. 查看實例狀態（Status Instance）

-- 命令格式
status instance_id; 

功能說明：返回指定實例的狀態，狀態包括Success、Failed、Running和Cancelled。

3. Top Instance

-- 返回當前項目中當前賬號所提交的正在執行的作業信息
top instance; 

-- 返回當前項目下所有正在執行的作業，默認最大返回50條。如需返回更多條記錄，請使用-limit number參數
top instance -all;

4. 停止實例

-- 停止指定的實例，此實例的狀態必須爲Running。
kill instance_id; 

5. 查詢實例信息

desc instance instance_id; 

6. 查看實例日誌信息（Wait Instance）

-- 根據具體的實例ID獲得任務運行日誌信息，包含Logview鏈接。再通過查看Logview可以獲得任務的詳細日誌
wait instance_id; 

資源操作

1. 添加資源

-- 命令格式
add file <local_file> [as alias] [comment 'cmt'][-f];
add archive <local_file> [as alias] [comment 'cmt'][-f];
add table <table_name> [partition (spec)] [as alias] [comment 'cmt'][-f];
add <PY | JAR> <localfile[.py |.jar]> [COMMENT 'cmt'][-f];

參數說明

• file/archive/table/jar/py：表示資源類型。
• local_file：表示本地文件所在路徑。並以此文件名作爲該資源名，資源名是資源的唯一標識。
• table_name：表示MaxCompute中的表名。目前不支持添加外部表爲資源。
• [PARTITION (spec)]：當添加的資源爲分區表時，MaxCompute僅支持將某個分區作爲資源，不支持將整張分區表作爲資源。
• alias：指定資源名，不加該參數時默認文件名爲資源名。Jar及Python類型資源不支持此參數。
• [comment'cmt']：給資源添加註釋。
• [-f]：當存在同名的資源時，此操作會覆蓋原有資源。如果不指定此選項，存在同名資源時，操作將失敗。

 2. 查看資源列表

-- 命令格式
LIST RESOURCES;

3. 下載資源

GET RESOURCE <resource_name> <path>;

功能說明：下載MaxCompute中的資源到本地。資源類型必須爲File、Jar、Archive或Py，不支持Table類型。

參數說明

• resource_name：要下載的資源名稱。
• path：資源保存到本地的路徑。

4. 刪除資源

DROP RESOURCE <resource_name>; 

函數操作

1. 註冊函數

-- 命令格式
CREATE FUNCTION <function_name> AS <package_to_class> USING <resource_list>;

參數說明

• function_name：新建的UDF函數名稱。函數名稱需要唯一，同名函數只能註冊一次。
• package_to_class：包名，此名稱須用引號引起。
  • Java UDF，此名稱爲從頂層包名一直到實現UDF類的類名。
  • Python UDF，此名稱爲Python腳本名.類名。
• resource_list：UDF所用到的資源列表。
  • 此資源列表必須包括UDF代碼所在的資源，且資源已經上傳至MaxCompute。
  • 如果您的代碼通過Distributed Cache接口讀取資源文件，此列表中還要包括UDF所讀取的資源文件列表。
  • 資源列表由多個資源名組成，資源名之間由逗號分隔，且資源列表必須用引號引起。
  • 如果需要指定資源所在的Project，寫法爲<project_name>/resources/<resource_name>。

-- 創建函數my_lower。假設Java UDF類org.alidata.odps.udf.examples.Lower在my_lower.jar中。
CREATE FUNCTION my_lower AS 'org.alidata.odps.udf.examples.Lower' USING 'my_lower.jar';

-- 創建函數test_udtf。假設Java UDF類com.aliyun.odps.examples.udf.UDTFResource是在udtfexample1.jar中，同時該函數還依賴File資源file_resource.txt、Table資源table_resource1以及Archive資源test_archive.zip。
create function test_udtf as 'com.aliyun.odps.examples.udf.UDTFResource' using 'udtfexample1.jar, file_resource.txt, table_resource1,test_archive.zip';

2. 註銷函數

DROP FUNCTION <function_name>;

3. 查看函數清單

-- 查看當前項目空間中的所有自定義函數
LIST FUNCTIONS; 
-- 查看指定項目空間下的所有自定義函數
LIST FUNCTIONS -p project_name;

 Set操作

set命令設置MaxCompute或用戶自定義的系統變量，區別與setproject命令：

• set命令：對當前Session設置MaxCompute系統變量。
• setproject命令：project級別的系統變量設置

-- 命令格式
set <KEY>=<VALUE>

可用的key和value屬性值見：MaxCompute的Set操作。 

其他操作

1. Alias命令

-- 命令格式
alias <alias>=<real>;

功能說明：爲資源創建別名。Alias命令可以在不修改代碼的前提下，在MapReduce或UDF代碼中，通過某個固定的資源名讀取不同資源（數據）。

參數說明

• alias：命名後的資源別名。
• real：資源的原名。

--新增資源res_20121208和res_20121209。
ADD TABLE sale_detail PARTITION (ds='20121208') AS res_20121208;
ADD TABLE sale_detail PARTITION (ds='20121209') AS res_20121209;

--命名資源res_20121208的別名爲resName，並調用它。
ALIAS resName=res_20121208;
jar -resources resName -libjars work.jar  -classpath ./work.jar com.company.MainClass args ...;  // 作業一。
--命名資源res_20121209的別名爲resName，並調用它。
ALIAS resName=res_20121209;
jar -resources resName -libjars work.jar  -classpath ./work.jar com.company.MainClass args ...; // 作業二。

2. 計量預估（Cost SQL命令）

cost sql <SQL Sentence>;

功能說明：預估出一條SQL的計量信息，包含輸入數據的大小、UDF個數以及SQL複雜等級。但該信息不能作爲實際計費標準，僅供參考，實際費用請以賬單爲準。

cost sql select distinct project_name, user_name from meta.m_security_users distribute by project_name sort by project_name;  

ID = 20150715113033121xxxxxxx
Input:65727592 Bytes
UDF:0
Complexity:1.0