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

Usage notes

  • Use the MaxCompute JDBC driver to connect to MaxCompute. For more information, see Usage notes.
  • Use the MaxCompute JDBC driver to connect to Tableau. Then, you can use Tableau to analyze data in MaxCompute in a visualized manner. For more information, see Configure MaxCompute JDBC on Tableau.
  • Use the MaxCompute JDBC driver to connect to SQL Workbench/J. Then, you can use SQL Workbench/J to execute SQL statements on MaxCompute data. For more information, see Configure MaxCompute JDBC on SQL Workbench/J.

Precautions

  • To execute SQL statements and obtain execution results by using the MaxCompute JDBC driver, you must meet the following requirements:
    • You are a member of a project.
    • You have the CreateInstance permission on a project.
    • You have the Select and Download permissions on a target table.
      Note
      • MaxCompute JDBC V1.9 or earlier creates a temporary table for each query, and you can use Tunnel to obtain query results from the temporary table. To use these versions, you must have the CreateTable permission.
      • MaxCompute JDBC V2.2 or later creates no temporary tables for each query, but you can use Instance Tunnel to obtain query results. The CreateTable permission is not required.

      For more information about MaxCompute permissions, see Authorize users.

  • MaxCompute provides the data protection feature. When this feature is enabled, you cannot move data out of the project. If the version of the MaxCompute JDBC driver that you use is earlier than V2.4, no result sets can be obtained. If you use MaxCompute JDBC V2.4 or later, the number of result rows that you obtain cannot exceed the value of the READ_TABLE_MAX_ROW parameter. For more information about the parameter, see Project operations. For more information about the data protection feature, see Project data protection.
  • MaxCompute V2.0 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 Date types. 
    set odps.sql.type.system.odps2=true

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 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, rows, parameters, and return values. You can use the information for debugging.
  • How do I obtain a MaxCompute Logview URL?

    The MaxCompute JDBC driver is encapsulated based on MaxCompute SDK for Java. Like the execution of 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 job status, track job progresses, and obtain job execution results. A Logview URL is configured by using the properties.log4j parameter. The logs are displayed in stderr by default.

  • Are connection pools and the auto-commit mode supported?

    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 where connection pools are used, connection pools are unnecessary for the driver.

    MaxCompute does not support transactions. Each query is immediately performed on the server. The auto-commit mode is enabled for the driver by default. You cannot disable the auto-commit mode for the 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.