MaxCompute:MaxCompute client

Requirements and compatibility

• Java: Java 8 or later is required. odpscmd v0.28.0 and later support JDK 1.9. Earlier versions support only JDK 1.8.

• Version compatibility: Command syntax and output formats may differ across client versions. Client output formats are not forward-compatible — do not parse client output for automation. After starting the client, verify the version number in the command-line interface. For all available versions, see aliyun-odps-console releases.

• Encoding: The client uses UTF-8 encoding by default. If your local environment uses a different encoding, Chinese characters in query results or uploaded files may appear as garbled text. This can happen when querying MaxCompute tables or uploading local data files with Tunnel commands.

Billing

Connecting to a MaxCompute project with odpscmd is free. Operations you run through the client — such as SQL queries and write commands — may incur charges for compute and storage. For details, see Billing items and methods.

Install and configure odpscmd

Starting with v0.27.0, odpscmd supports MaxCompute V2.0 data types. For the full list of supported types, see MaxCompute V2.0 data types.

1. Download the MaxCompute client package from GitHub. Download the latest odpscmd_public.zip from the releases page.

   If the GitHub link is not accessible, download the package from OSS instead.

2. Extract the package. The extracted directory contains four folders: bin, conf, lib, and plugins.

3. In the conf folder, open odps_config.ini and configure the parameters below. The file uses # for comments. The following table describes the parameters.

   Parameter	Required	Description	Example
   project_name	Yes	The MaxCompute project to access. If your workspace is in standard mode, distinguish between production and development (_dev) project names. To find your project name: log on to the MaxCompute console, select your region, then go to Manage Configurations > Projects. See Differences between workspace modes.	doc_test_dev
   access_id	Yes	Your Alibaba Cloud account or RAM user AccessKey ID. Get it from the AccessKey management page.	—
   access_key	Yes	The AccessKey secret that matches your AccessKey ID.	—
   end_point	Yes	The MaxCompute service endpoint. Set this based on your project's region and network type. For endpoints by region and network, see Endpoint. This must be the MaxCompute endpoint, not the Tunnel endpoint. An incorrect endpoint causes connection errors.	http://service.cn-hangzhou.maxcompute.aliyun.com/api
   log_view_host	No	The LogView URL for viewing job runtime information and troubleshooting failures. We recommend setting this parameter. Without it, you cannot quickly locate issues when jobs fail. Fixed value: http://logview.odps.aliyun.com.	http://logview.odps.aliyun.com
   https_check	No	Whether to use HTTPS for requests. True or False. Default: False.	True
   data_size_confirm	No	Maximum input data size in GB. No limit applies. Recommended: 100.	100
   update_url	No	Reserved parameter. Leave blank.	—
   use_instance_tunnel	No	Whether to use InstanceTunnel to download SQL query results. True or False. Default: False.	True
   instance_tunnel_max_record	No	Maximum number of records returned for SQL query results when use_instance_tunnel is True. Maximum: 10000.	10000
   tunnel_endpoint	No	The public endpoint for the Tunnel service. If not set, Tunnel auto-routes based on your MaxCompute endpoint's region and network. If set, Tunnel uses that endpoint and does not auto-route. For Tunnel endpoints by region and network, see Endpoint.	http://dt.cn-hangzhou.maxcompute.aliyun.com
   set.<key>	No	Set properties for your MaxCompute project. For available properties, see Property list.	set.odps.sql.decimal.odps2=true

Start the MaxCompute client

Before you begin, ensure that you have:

• A MaxCompute project. See Create a MaxCompute project.

• (If connecting as a RAM user) The RAM user added to the target project. See Grant permissions to other users.

Start the client using one of the following methods.

Method 1: Double-click the script

In the bin folder of your installation directory:

• Windows: Double-click odpscmd.bat.

• macOS: Double-click odpscmd.

When the client starts and connects successfully, you see a confirmation message.

Method 2: Run from the command line

Navigate to the bin folder in your command-line window, then run:

• Windows: odpscmd

• Linux or macOS: sh odpscmd

• Ubuntu: ./odpscmd (running sh odpscmd returns an error on Ubuntu)

When the client starts and connects successfully, you see a confirmation message.

When starting from the command line, you can pass startup parameters to run commands directly. See Startup parameters.

odps@project_name>whoami;

Common operations

-- View help for all commands.
odps@project_name>help;
-- Equivalent to:
odps@project_name>h;

-- View help for commands matching a keyword (for example, table-related commands).
odps@project_name>help table;

...\odpscmd\bin>odpscmd -h

odps@project_name>quit;
-- Equivalent to:
odps@project_name>q;

Startup parameters

Use startup parameters to pass commands directly when launching odpscmd from the command line.

Usage: odpscmd [OPTION]...
    --help                                  (-h) for help
    --config=<config_file>                  specify another config file
    --project=<prj_name>                    use project
    --endpoint=<http://host:port>           set endpoint
    -k <n>                                  skip beginning queries and start from specified position
    -r <n>                                  set retry times
    -f <"file_path;">                       execute commands in file
    -e <"command;[command;]...">            execute commands, including SQL commands

-- Windows command prompt: redirect output to a file with no headers.
...\odpscmd\bin>odpscmd -e "set odps.sql.select.output.format={""needHeader"":false,""fieldDelim"":"" ""};select * from noheader;" >D:\test.txt

-- Shell: redirect output to a file with no headers.
/Users/.../odpscmd/bin/odpscmd -e "set odps.sql.select.output.format={\"needHeader\":false,\"fieldDelim\":\"\"};select * from noheader;" >/Users/A/temp/test.txt
-- Output (no headers, raw data only):
-- 1
-- 2
-- 3

Troubleshooting

Version history

The following table lists recent updates to odpscmd. For the full changelog, see aliyun-odps-console releases.

What's next

• To run SQL commands in your project, see Use MaxCompute with the client.

• To explore all available commands, see Common commands and SQL commands and functions.

• If the client does not connect, see Troubleshooting.