您可以通过MaxCompute客户端访问MaxCompute项目并运行命令。本文为您介绍如何安装、配置和运行客户端并提供客户端相关使用说明信息。

前提条件

在使用MaxCompute客户端前,请您确认已满足如下条件:
  • 待安装MaxCompute客户端的设备已安装Java 8或以上版本。
  • 已创建MaxCompute项目。

    更多创建MaxCompute项目操作,请参见创建MaxCompute项目

  • 使用MaxCompute客户端的RAM用户已被添加至MaxCompute项目所属的DataWorks工作空间。

    更多添加工作空间成员操作,请参见添加工作空间成员并设置角色

背景信息

安装并配置MaxCompute客户端后,您可以通过安装路径下的脚本文件或在系统的命令行窗口启动MaxCompute客户端,并执行命令。MaxCompute客户端支持如下操作:

使用限制

MaxCompute客户端从v0.28.0版开始支持JDK 1.9,v0.28.0以下版本只支持JDK 1.8。您可以启动MaxCompute客户端后,在命令行界面查看客户端版本号。更多启动客户端操作,请参见运行MaxCompute客户端

注意事项

  • MaxCompute客户端的输出格式不承诺向前兼容,不同版本间的客户端命令格式及行为有差异,请勿依赖客户端的输出格式执行任何解析工作。更多客户端版本,请参见aliyun-odps-console
  • MaxCompute客户端的命令行使用两个减号(--)作为注释。

安装并配置MaxCompute客户端

说明 客户端从v0.27.0版本开始支持MaxCompute 2.0新数据类型,推荐使用新数据类型。支持的数据类型列表,请参见2.0数据类型版本

安装并配置MaxCompute客户端的操作流程如下:

  1. 下载MaxCompute客户端安装包(Github)
    说明 如果上方链接无法下载,您可以尝试单击此处的MaxCompute客户端安装包(OSS)进行下载。更多关于Github链接访问失败的问题,推荐您直接在搜索引擎中查找相关解决方案。
  2. 解压下载的安装包文件,得到binconflibplugins文件夹。
  3. 进入conf文件夹,配置odps_config.ini文件。
    odps_config.ini文件内容如下。
    project_name=
    access_id=
    access_key=
    end_point=
    log_view_host=
    https_check=
    # confirm threshold for query input size(unit: GB)
    data_size_confirm=
    # this url is for odpscmd update
    update_url=
    # download sql results by instance tunnel
    use_instance_tunnel=
    # the max records when download sql results by instance tunnel
    instance_tunnel_max_record=
    # IMPORTANT:
    #   If leaving tunnel_endpoint untouched, console will try to automatically get one from odps service, which might charge networking fees in some cases.
    #   Please refer to 配置Endpoint
    # tunnel_endpoint=
    
    # use set.<key>=
    # e.g. set.odps.sql.select.output.format=

    odps_config.ini文件中使用井号(#)作为注释。参数详细信息如下。

    参数 是否必填 描述 示例
    project_name 访问的目标MaxCompute项目名称。

    如果您创建了标准模式的工作空间,在配置project_name时,请注意区分生产环境与开发环境(_dev)的项目名称,请参见简单模式和标准模式的区别

    您可以登录MaxCompute控制台,在项目管理页签获取MaxCompute项目名称。

    doc_test_dev
    access_id 阿里云账号或RAM用户的AccessKey ID。

    您可以进入AccessKey管理页面获取AccessKey ID。

    access_key AccessKey ID对应的AccessKey Secret。

    您可以进入AccessKey管理页面获取AccessKey Secret。

    end_point MaxCompute服务的连接地址。

    您需要根据创建MaxCompute项目时选择的地域以及网络连接方式配置Endpoint。各地域及网络对应的Endpoint值,请参见Endpoint

    注意 如果Endpoint配置有误,会出现无法访问错误,请务必仔细确认。
    http://service.cn-hangzhou.maxcompute.aliyun.com/api
    log_view_host Logview地址。您可以通过该地址查看作业的详细运行信息,并为报错处理提供依据。固定取值为:http://logview.odps.aliyun.com。
    说明 推荐您配置该参数,如果不配置该参数,在作业报错时无法快速定位问题。
    http://logview.odps.aliyun.com
    https_check 是否开启HTTPS访问机制,对访问MaxCompute项目的请求进行加密。取值范围如下:
    • True:采用HTTPS机制。
    • False:采用HTTP机制。

    默认值为False。

    True
    data_size_confirm 输入数据量的最大值,单位为GB。取值范围无限制。推荐设置为100 GB。 100
    update_url 预留参数,暂无需关注。
    use_instance_tunnel 是否使用InstanceTunnel下载SQL执行结果。取值范围如下:
    • True:使用InstanceTunnel下载SQL执行结果。
    • False:不使用InstanceTunnel下载SQL执行结果。

    默认值为False。

    True
    instance_tunnel_max_record 客户端返回的SQL执行结果的最大记录数。如果use_instance_tunnel值为True,需要配置该参数。最大值为10000。 10000
    tunnel_endpoint Tunnel服务的外网访问链接。如果您未配置Tunnel Endpoint,Tunnel会自动路由到MaxCompute服务所在网络对应的Tunnel Endpoint。如果您配置了Tunnel Endpoint,则以配置为准,不进行自动路由。

    各地域及网络对应的Tunnel Endpoint值,请参见Endpoint

    http://dt.cn-hangzhou.maxcompute.aliyun.com
    set.<key> 设置MaxCompute项目的属性。

    更多属性信息,请参见属性列表

    set.odps.sql.decimal.odps2=true

运行MaxCompute客户端

MaxCompute客户端可通过如下方式启动,您可以任选其中一种:
  • 方式一:在MaxCompute客户端安装路径下的bin文件夹中,双击odpscmd.bat文件,即可启动MaxCompute客户端。返回如下信息,表明已成功连接MaxCompute项目。连接成功
  • 方式二:在系统的命令行执行窗口,进入MaxCompute客户端安装路径下的bin目录,执行odpscmd命令,即可启动MaxCompute客户端。返回如下信息,表明已成功连接MaxCompute项目。连接成功
您可以在上述图中的光标位置处输入命令,按下回车即可运行。命令示例及返回结果如下。返回结果
说明 MaxCompute客户端支持的详细命令语法信息,请参见常用命令列表SQL命令及函数

获取当前登录用户

您可以在上述运行窗口执行如下命令获取当前登录用户的信息。
odps@project_name>whoami;
返回结果如下。当前登录用户
  • Name:当前登录的账号信息。
  • Source IP:MaxCompute客户端所在设备的IP地址。
  • End_Point:MaxCompute服务的连接地址。
  • Project:MaxCompute项目的名称。

退出MaxCompute客户端

您可以在上述运行窗口执行如下命令退出MaxCompute客户端。
odps@project_name>quit;
--等价于如下命令。
odps@project_name>q;

获取命令帮助

您可以通过如下方式快速获取MaxCompute客户端的命令帮助,您可以任选其中一种:
  • 方式一:在MaxCompute客户端查看命令帮助信息。
    • 查看全部命令的帮助。
      odps@project_name>help;
      --等价于如下命令。
      odps@project_name>h;
    • 通过指定关键字查看相关命令帮助信息。
      例如获取与表操作相关的命令帮助。
      odps@project_name>help table;
      --返回结果如下。
      Usage: alter table <tablename> merge smallfiles
      Usage: export table <tablename>
      Usage: show tables [in <project_name>] [like '<prefix>']
             list|ls tables [-p,-project <project_name>]
      Usage: describe|desc [<projectname>.]<tablename> [partition(<spec>)]
      Usage: read [<project_name>.]<table_name> [(<col_name>[,..])] [PARTITION (<partition_spec>)] [line_num]
  • 方式二:在系统的命令行执行窗口,切换到MaxCompute客户端安装路径下的bin目录,执行如下命令查看全部命令的帮助信息。在命令行执行窗口启动MaxCompute客户端时,您可以指定一系列参数,更多参数信息,请参见启动参数
    ..\odpscmd\bin>odpscmd -h

启动参数

在系统的命令行执行窗口,您可以通过指定一系列参数快速执行命令,命令使用方法如下。
Usage: odpscmd [OPTION]...
where options include:
    --help                                  (-h)for help
    --config=<config_file>                  specify another config file
    --project=<prj_name>                    use project
    --endpoint=<http://host:port>           set endpoint
    -k <n>                                  will skip begining queries and start from specified position
    -r <n>                                  set retry times
    -f <"file_path;">                       execute command in file
    -e <"command;[command;]...">            execute command, include sql command
启动参数说明如下。
命令 说明 命令示例
--help-h 获取MaxCompute客户端的全部命令帮助信息。 odpscmd --help
--config 指定配置文件odps_config.ini的路径。默认配置文件的路径是odpscmd_public/conf/odps_config.ini odpscmd --config=D:/odpscmd/conf/odps_config.ini
--project 指定访问的MaxCompute项目名称。 odpscmd --project=doc_test
--endpoint 指定连接MaxCompute服务的Endpoint信息。更多Endpoint信息,请参见配置Endpoint odpscmd --endpoint=http://service.cn-shanghai.maxcompute.aliyun.com/api
-k 运行从指定位置开始的语句。当n≤0时,从第一条语句开始执行。每条语句以分号(;)分隔。 忽略前两条语句,直接从第三条语句开始执行。odpscmd -k 3 -e "drop table table_name;create table table_name (dummy string);insert overwrite table table_name select count(*) from table_name;"
-r 设置作业运行失败时的重试次数。 odpscmd -r 2 -e "select * from sale_detail;select * from table_test;"
-f 指定读取的文件。
  1. 准备本地脚本文件script.txt,假设存放在D盘,文件内容如下。
    drop table if exists test_table_mj;
    create table test_table_mj (id string, name string);
    drop table test_table_mj;
  2. 在系统命令行窗口,换到MaxCompute客户端安装路径下的bin目录,运行如下命令。
    ..\odpscmd\bin>odpscmd -f D:/script.txt;
-e 指定执行的命令。 odpscmd -e "select * from sale_detail;"

在Shell(或Windows命令行)执行窗口,用户可能需要使用odpscmd -e SQL语句执行得到的动态返回值,Shell的变量会获取这个动态返回值,然后在Shell中执行后续作业。此场景需要返回值不包含运行信息、表头等额外信息。为便于Shell调用,您可以通过执行set odps.sql.select.output.format={"needHeader":false,"fieldDelim":""};命令,关闭表头显示。

例如表noheader中有一列三行数据,为1、2、3。执行如下命令,将计算结果重定向stdout到目标句柄,计算结果仅包含具体数据,不包含其他额外信息:
odpscmd -e "set odps.sql.select.output.format={"needHeader":false,"fieldDelim":""};select * from noheader;" >/temp/test.txt
--返回结果如下。
1
2
3

版本更新记录

MaxCompute客户端近期版本的更新说明如下,详细信息请单击对应版本链接获取。

版本 变更类型 描述
v0.37.4-public 功能增强
  • 优化命令对应的帮助信息。
  • desc extended partition命令支持返回更多分区属性信息。
v0.36.0-public 新功能 支持创建External Project连接DLF(Data Lake Formation),实现湖仓一体功能。更多湖仓一体信息,请参见MaxCompute湖仓一体
缺陷修复 修复下载TIMESTAMP类型数据时,纳秒(nano)部分处理不正确的问题。