You can use the MaxCompute client to access MaxCompute projects and run commands. This topic describes how to install, configure, and run the MaxCompute client and provides related instructions.
Prerequisites
- Java 8 or later is installed on the machine on which you want to install the MaxCompute client.
- A MaxCompute project is created.
For more information about how to create a MaxCompute project, see Create a MaxCompute project.
- A RAM user as which you want to use the MaxCompute client is added to the DataWorks
workspace to which the MaxCompute project that you created belongs.
For more information about how to add members to a workspace, see Add a workspace member and configure roles.
Background information
- Obtain information about the current logon user. For more information, see Obtain information about the current logon user.
- Exit the MaxCompute client. For more information, see Exit the MaxCompute client.
- Obtain help information about commands. For more information, see Obtain help information about commands.
- If you want to start the MaxCompute client by running commands in the CLI, you must specify parameters in the commands. For more information, see Specify startup parameters.
Limits
MaxCompute client V0.28.0 and later support Java Development Kit (JDK) 1.8 and JDK 1.9. The MaxCompute client of a version that is earlier than V0.28.0 supports only JDK 1.8. You can view the client version in the CLI after you start the MaxCompute client. For more information about how to start the MaxCompute client, see Run the MaxCompute client.
Precautions
- The output format of the MaxCompute client may not be forward compatible. The command syntax and execution rules of the client vary based on the client version. We recommend that you do not rely on the output format of the client to parse data. For more information about client versions, see aliyun-odps-console.
- If you run the
Tunnel Download
command for the first time on the MaxCompute client, the MaxCompute client creates a folder named session in the client installation directoryplugins/dship
of your machine. The session folder is used to store logs. If multiple users run theTunnel Download
commands on the same machine, you can use one of the following methods to ensure data security:- Use the folder permission management feature provided by the machine to manage the permissions on the session folder.
- Add the
-sd <Name of a new session folder>
or-session-dir <Name of a new session folder>
parameter to theTunnel Download
command to download data to a different session folder. For more information aboutTunnel Download
commands, see Download.
- Two consecutive minus signs (-) are used to comment out a command line on the MaxCompute client.
Install and configure the MaxCompute client
To install and configure the MaxCompute client, perform the following steps:
Run the MaxCompute client
- Method 1: In the bin folder in the installation path of the MaxCompute client, double-click the
odpscmd.bat
file to start the MaxCompute client. This method is used for the Windows operating system. If the information shown in the following figure is returned, the MaxCompute project is connected. - Method 2: In the CLI of the system, go to the bin folder in the installation path of the MaxCompute client and run the
odpscmd
command for the Windows operating system or run thesh odpscmd
command for the macOS or Linux operating system to start the MaxCompute client. If the information shown in the following figure is returned, the MaxCompute project is connected.Note An error is returned when you run thesh odpscmd
command in Ubuntu. You can run the./odpscmd
command to start the MaxCompute client.

Obtain information about the current logon user
odps@project_name>whoami;
The following figure shows the returned results. 
- Name: the account of the current logon user.
- Source IP: the IP address of the machine in which the MaxCompute client resides.
- End_Point: the endpoint of MaxCompute.
- Project: the name of the MaxCompute project.
Exit the MaxCompute client
odps@project_name>quit;
-- The preceding command is equivalent to the following command:
odps@project_name>q;
Obtain help information about commands
- Method 1: View the help information about commands on the MaxCompute client.
- View the help information about all commands.
odps@project_name>help; -- The preceding command is equivalent to the following command: odps@project_name>h;
- Specify a keyword to view the help information about the related commands.
Example: Obtain the help information about the commands that are related to table operations.
odps@project_name>help table; -- Returned results: 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]
- View the help information about all commands.
- Method 2: In the CLI of the system, go to the bin folder in the installation path of the MaxCompute client, and run the following command
to view the help information about all commands. If you start the MaxCompute client
by running commands in the CLI, you can specify a series of parameters in the commands.
For more information about these parameters, see Specify startup parameters.
...\odpscmd\bin>odpscmd -h
Specify startup parameters
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
Parameter | Description | Sample command |
---|---|---|
--help or -h |
Obtains the help information about all commands of the MaxCompute client. | odpscmd --help |
--config |
Specifies the directory in which the configuration file odps_config.ini is stored. The default directory is odpscmd_public/conf .
|
odpscmd --config=D:/odpscmd/conf/odps_config.ini |
--project |
Specifies the name of the MaxCompute project that you want to access. | odpscmd --project=doc_test |
--endpoint |
Specifies the endpoint of MaxCompute. For more information about the endpoints of MaxCompute, see Endpoints. | odpscmd --endpoint=http://service.cn-shanghai.maxcompute.aliyun.com/api |
-k |
Executes statements from a specific location. If n is set to a value that is less than or equal to 0, the execution starts from the
first statement. Multiple statements are separated by semicolons (;).
|
Run the following command to ignore the first two statements and start from the third
statement: 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 |
Specifies the number of retries that are allowed after a job fails to run. | odpscmd -r 2 -e "select * from sale_detail;select * from table_test;" |
-f |
Specifies the file to read. |
|
-e |
Specifies the command that you want to run. | odpscmd -e "select * from sale_detail;" |
The dynamic return value of an odpscmd -e SQL statement
command may be called by a shell script that is run in a shell window or the Command
Prompt in Windows. A shell variable may obtain the return value and use it in subsequent
jobs. In this scenario, only field values are required. Other information, such as
runtime information and headers, cannot be returned. To facilitate shell calls, you
must set the use_instance_tunnel parameter in the odps_config.ini file to false to disable InstanceTunnel. You can run the set odps.sql.select.output.format={""needHeader"":false,""fieldDelim"":""""};
command to disable header display.
-- Run the following command in the Command Prompt in Windows:
...\odpscmd\bin>odpscmd -e "set odps.sql.select.output.format={""needHeader"":false,""fieldDelim"":""""};select * from noheader;" >D:\test.txt
-- The returned results are stored in the test.txt file in drive D.
-- Run the following command in a shell window:
/Users/.../odpscmd/bin/odpscmd -e "set odps.sql.select.output.format={""needHeader"":false,""fieldDelim"":""""};select * from noheader;" >/Users/A/temp/test.txt
-- The returned results are stored in the test.txt file in the /Users/A/temp directory.
-- Returned results:
1
2
3
Version updates
The following table describes the latest version updates of the MaxCompute client. For more information, click the URL of a specific version.
Version | Change type | Description |
---|---|---|
v0.37.4-public | Enhanced feature |
|
v0.36.0-public | New feature | An external project can be created to connect to Data Lake Formation (DLF). This implements the data lakehouse feature. |
Fixed issue | The issue that caused the nanosecond part of data of the TIMESTAMP type to be incorrectly processed is fixed. |