All Products
Search
Document Center

MaxCompute:Overview

Last Updated:Jul 12, 2025

The MaxCompute Java Database Connectivity (JDBC) driver provides a standard JDBC API. You can perform distributed computing and queries on large amounts of data in MaxCompute using the JDBC API. You can also use the JDBC driver to connect tools that support JDBC to MaxCompute.

Usage notes

Usage notes

  • To execute SQL statements and obtain execution results using the MaxCompute JDBC driver, you must meet the following requirements:

    • You are a member of a project.

    • You have the CreateInstance permission on the project.

    • You have the Select and Download permissions on the table that you want to use.

      Note

      • When you use MaxCompute JDBC V1.9 or earlier, a temporary table is automatically created for each query. You can use Tunnel commands to retrieve query results from the temporary table. To use these versions, you must have the CreateTable permission.

      • When you use MaxCompute JDBC V2.2 or later, no temporary table is automatically created for each query. You can call the Instance Tunnel interface to retrieve query results, regardless of whether you have the CreateTable permission.

      For more information about MaxCompute permissions, see MaxCompute permissions.

  • MaxCompute provides the data protection feature. If the data protection feature is enabled for a project, you cannot move data out of the project. If you use MaxCompute JDBC of a version earlier than V2.4, no result set can be obtained. If you use MaxCompute JDBC V2.4 or later, the number of result rows that you retrieve cannot exceed the value of the READ_TABLE_MAX_ROW parameter. For more information about this parameter, see Project operations. For more information about the data protection feature, see Data protection mechanism.

  • The MaxCompute V2.0 data type edition supports more data types, such as TINYINT, SMALLINT, DATETIME, TIMESTAMP, ARRAY, MAP, and STRUCT. To use these new data types, you must run the following command to enable the MaxCompute V2.0 data type edition. For more information, see Data type editions. 

    set odps.sql.type.system.odps2=true

  • For JDBC V3.4.1 and later versions, if you have long SQL statements (longer than 1 KB), you need to carefully control the concurrency. For example, when using an ECS instance with 8 vCPUs and 16.0 GiB of memory, we recommend that the concurrency does not exceed 100. If you cannot effectively control the request concurrency, you can upgrade to JDBC V3.8.8 or V3.9.3, and set skipCheckIfSelect=true to skip the SQL parsing feature. For more information about this feature, see Version update history.

FAQ

  • How do I view the log file of the MaxCompute JDBC driver?

    • By default, the log file of the MaxCompute JDBC driver is stored in the same directory as the JAR package of the MaxCompute JDBC driver. The file name is jdbc.log.

    • If the code and the MaxCompute JDBC driver are in the same uber JAR package, the log file of the MaxCompute JDBC driver is stored in the same directory as the uber JAR package.

    The logs of the MaxCompute JDBC driver show details about JDBC API calls, such as class names, method names, parameters, return values, and the number of rows. You can use this information for debugging.

  • How do I obtain a MaxCompute Logview URL?

    The MaxCompute JDBC driver is encapsulated based on MaxCompute SDK for Java. Logview URLs are generated when you execute SQL statements in the MaxCompute client, MaxCompute Studio, and DataWorks. Logview URLs are also generated when you use the MaxCompute JDBC driver to execute SQL statements. You can use the Logview URLs to view the job status, track job progress, and obtain job execution results. A Logview URL is configured using the properties.log4j parameter. By default, logs are displayed as standard error logs.

  • Does MaxCompute support connection pools and the auto-commit mode?

    MaxCompute provides REST services that are different from long connections in traditional databases. It is considered a lightweight task for the MaxCompute JDBC driver to establish a connection. Although the driver supports scenarios in which connection pools are used, connection pools are unnecessary for the MaxCompute JDBC driver.

    MaxCompute does not support Transaction. Each query is immediately performed on the server. The auto-commit mode is automatically enabled for the MaxCompute JDBC driver. You cannot disable the auto-commit mode for the MaxCompute JDBC driver.

  • How do I obtain partition fields and data types?

    You can use the Connection.getMetadata() method to obtain DatabaseMetaData objects and use the getColumns() method to obtain the metadata of all columns.