使用本地客户端（odpscmd）连接

费用说明

使用MaxCompute客户端连接项目不收费，但是通过客户端执行的操作可能会触发MaxCompute计费。例如，使用客户端提交一个SQL查询和写入命令，此SQL命令在MaxCompute上运行会消耗计算资源，同时写入数据会占用存储空间，将产生计算费用和存储费用。MaxCompute计费详情请参见计费项与计费方式。

安装并配置MaxCompute客户端

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

操作流程如下：

1. 下载MaxCompute客户端安装包（Github）。

   说明

   • 通过上方链接进入客户端发布界面，下载最新版本的MaxCompute客户端安装包（odpscmd_public.zip）。

   • 如果上方链接无法下载，可以尝试单击此处的MaxCompute客户端安装包（OSS）下载。更多关于GitHub链接访问失败的问题，推荐在搜索引擎中查找相关解决方案。

2. 解压下载的安装包文件，得到bin、conf、lib和plugins文件夹。

3. 进入conf文件夹，配置odps_config.ini文件。

   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。	无
   end_point	是	MaxCompute服务的连接地址。 需要根据创建MaxCompute项目时选择的地域以及网络连接方式配置Endpoint。各地域及网络对应的Endpoint值，请参见Endpoint。 重要 Endpoint用于MaxCompute服务，Tunnel Endpoint用于MaxCompute的Tunnel服务，此处请填写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客户端

1. 创建MaxCompute项目。

2. 若使用MaxCompute客户端的用户为RAM用户，需要通过阿里云主账号将该RAM用户添加至目标MaxCompute项目。更多添加工作空间成员操作，请参见授权给其他用户。

3. 启动MaxCompute客户端有如下两种方式，任选其一即可：

   方式一：安装包的脚本文件

   在MaxCompute客户端安装路径下的bin文件夹中，双击odpscmd.bat文件（Windows系统）或者双击odpscmd文件（macOS系统），即可启动MaxCompute客户端。返回如下信息，表明已成功连接MaxCompute项目。

   方式二：系统的命令行执行窗口

   在系统的命令行执行窗口，进入MaxCompute客户端安装路径下的bin目录，执行odpscmd命令（Windows系统）或sh odpscmd（Linux系统或Mac系统），即可启动MaxCompute客户端。返回如下信息，表明已成功连接MaxCompute项目。

   说明

   在Ubuntu执行sh odpscmd会提示报错，请使用./odpscmd命令尝试启动。

   

   如果通过系统的命令行窗口启动MaxCompute客户端，可以指定参数来执行命令，更多参数信息，请参见启动参数。

MaxCompute客户端相关操作

...\odpscmd\bin>odpscmd -h

odps@project_name>whoami;

odps@project_name>quit;
-- 等价于如下命令。
odps@project_name>q;

相关文档

登录MaxCompute客户端后，即可在MaxCompute项目内执行SQL命令，请参见通过客户端使用MaxCompute。

MaxCompute客户端支持的详细命令语法信息，请参见常用命令列表或SQL命令及函数。

常见问题

配置完odps_config.ini文件后启动MaxCompute客户端，常见报错如下：

启动参数

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

在Shell（或Windows命令行）执行窗口，用户可能需要使用odpscmd -e <SQL语句>执行得到的动态返回值，Shell的变量会获取这个动态返回值，然后在Shell中执行后续作业。此场景需要返回值不包含运行信息、表头等额外信息。为便于Shell调用，需要配置odps_config.ini文件中的use_instance_tunnel参数值为false，关闭Instance Tunnel服务。然后执行set odps.sql.select.output.format={"needHeader":false,"fieldDelim":" "}; 命令，关闭表头显示。

--Windows命令行执行窗口运行命令如下。
...\odpscmd\bin>odpscmd -e "set odps.sql.select.output.format={""needHeader"":false,""fieldDelim"":"" ""};select * from noheader;" >D:\test.txt
--返回结果会保存在D:\test.txt中。

--Shell执行窗口运行命令如下。
/Users/.../odpscmd/bin/odpscmd -e "set odps.sql.select.output.format={\"needHeader\":false,\"fieldDelim\":\"\"};select * from noheader;" >/Users/A/temp/test.txt 
--返回结果会保存在/Users/A/temp/test.txt中。
--返回结果如下。
1
2
3

版本更新记录

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

更多MaxCompute客户端版本及相关功能更新说明，请参见GitHub。