All Products
Search
Document Center

MaxCompute:Install and start the MaxCompute client

Last Updated:Jan 30, 2024

The MaxCompute client (odpscmd) runs directly on your on-premises computer, and provides a simple and efficient way for you to run commands and manage MaxCompute services. This topic describes how to install and start the MaxCompute client. After the client is started, a MaxCompute project is connected.

Prerequisites

Before you install the MaxCompute client, make sure that the following conditions are met:

  • 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 belongs.

    For more information about how to add members to a DataWorks workspace, see Grant permissions to a RAM user.

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.

Install and configure the MaxCompute client

Note

MaxCompute client V0.27.0 and later support the MaxCompute V2.0 data type edition. We recommend that you use the MaxCompute V2.0 data type edition. For more information about the data types that are supported by the MaxCompute V2.0 data type edition, see MaxCompute V2.0 data type edition.

To install and configure the MaxCompute client, perform the following steps:

  1. Download the MaxCompute client installation package from GitHub.

    Note
    • You can click the preceding link to download the latest version of the MaxCompute client installation package odpscmd_public.zip on the page that appears.

    • If you cannot download the package after you click the preceding link, click MaxCompute client installation package (OSS) to download the package. For more information about how to resolve the download failure, we recommend that you search for related solutions by using search engines.

  2. Decompress the downloaded package to obtain the bin, conf, lib, and plugins folders.

  3. Open the conf folder and configure the odps_config.ini file.

    In the odps_config.ini file, lines that start with a number sign (#) are comments. The following table describes the parameters in the odps_config.ini file.

    Parameter

    Required

    Description

    Example

    project_name

    Yes

    The name of the MaxCompute project that you want to access.

    If you create a workspace in standard mode, take note of the differences in the project names between the production environment and development environment when you configure the project_name parameter. The name of the project for the development environment ends with _dev. For more information, see Differences between workspaces in basic mode and workspaces in standard mode.

    To obtain the name of the MaxCompute project, perform the following steps: Log on to the MaxCompute console. In the top navigation bar, select a region. In the left-side navigation pane, choose Workspace > Projects. On the Projects page, view the name of the MaxCompute project.

    doc_test_dev

    access_id

    Yes

    The AccessKey ID of your Alibaba Cloud account or a RAM user within the Alibaba Cloud account.

    You can obtain the AccessKey ID on the AccessKey Pair page.

    None

    access_key

    Yes

    The AccessKey secret that corresponds to the AccessKey ID.

    You can obtain the AccessKey secret on the AccessKey Pair page.

    None

    end_point

    Yes

    The endpoint of MaxCompute.

    You must configure this parameter based on the region and network connection type that you select when you create the MaxCompute project. For more information about the endpoints that correspond to different regions and network connection types, see Endpoints.

    Important
    • The value of this parameter is the endpoint of MaxCompute, which is used to access MaxCompute rather than MaxCompute Tunnel.

    • If you specify an invalid endpoint, an error occurs when you access MaxCompute.

    http://service.cn-hangzhou.maxcompute.aliyun.com/api

    log_view_host

    No

    The Uniform Resource Locator (URL) of LogView. You can view the detailed runtime information of a job by using this URL. This information helps you troubleshoot job errors. Set the value to http://logview.odps.aliyun.com.

    Note

    We recommend that you configure this parameter. If you do not configure this parameter, you cannot identify the cause of job errors.

    http://logview.odps.aliyun.com

    https_check

    No

    Specifies whether to enable HTTPS access. If HTTPS access is enabled, requests to access MaxCompute projects are encrypted. Valid values:

    • True: HTTPS access is enabled.

    • False: HTTP access is enabled.

    Default value: False.

    True

    data_size_confirm

    No

    The maximum size of input data. Unit: GB. You can set this parameter to any value. We recommend that you set this parameter to 100.

    100

    update_url

    No

    A reserved parameter.

    None

    use_instance_tunnel

    No

    Specifies whether to use InstanceTunnel to download the execution results of SQL statements. Valid values:

    • True: InstanceTunnel is used to download the execution results of SQL statements.

    • False: InstanceTunnel is not used to download the execution results of SQL statements.

    Default value: False.

    True

    instance_tunnel_max_record

    No

    The maximum number of SQL execution results that can be returned by the client. If the use_instance_tunnel parameter is set to True, you must configure this parameter. Maximum value: 10000.

    10000

    tunnel_endpoint

    No

    The public endpoint of MaxCompute Tunnel. If you do not configure this parameter, traffic is automatically routed to the Tunnel endpoint that corresponds to the network in which MaxCompute resides. If you configure this parameter, traffic is routed to the specified endpoint and automatic routing is not performed.

    For more information about the Tunnel endpoints that correspond to each region and network, see Endpoints.

    http://dt.cn-hangzhou.maxcompute.aliyun.com

    set.<key>

    No

    The properties of the MaxCompute project.

    For more information about the properties of MaxCompute projects, see Properties.

    set.odps.sql.decimal.odps2=true

    Note

    Make sure that the settings of the preceding parameters are valid. Invalid settings will result in a project connection failure.

Start the MaxCompute client

You can start the MaxCompute client by using one of the following methods:

Method 1: Start the MaxCompute client by using the script file of the installation package

In the bin folder in the installation directory of the MaxCompute client, double-click the odpscmd.bat file for the Windows operating system (OS) or the odpscmd file for macOS to start the MaxCompute client. If the information shown in the following figure is returned, the MaxCompute project is connected.image.png

Method 2: Start the MaxCompute client by using the CLI of the system

In the CLI of the system, go to the bin folder in the installation directory of the MaxCompute client and run the odpscmd command for the Windows OS or run the sh odpscmd command for macOS or Linux OS 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 the sh odpscmd command in Ubuntu. You can run the ./odpscmd command to start the MaxCompute client.

image.png

If you start the MaxCompute client by using the CLI of the system, you can specify parameters to run commands. For more information, see Specify startup parameters.

What to do next

After you start the MaxCompute client, you can create tables in the connected MaxCompute project. For more information about how to create tables, see Create tables.

References

For more information about how to use the MaxCompute client and common errors that may occur when you configure the MaxCompute client, see MaxCompute client (odpscmd).