The MaxCompute Java Database Connectivity (JDBC) driver implements the standard JDBC API, letting you run distributed SQL queries on large datasets in MaxCompute and connect any JDBC-compatible tool to MaxCompute.
What you can do
-
BI analysis tools — Connect Tableau, Yonghong BI, and similar tools to visualize and analyze MaxCompute data.
-
Database management tools — Connect DBeaver, DataGrip, and SQL Workbench/J to manage MaxCompute projects.
-
Custom Java applications — Use the JDBC API in your Java code to run SQL statements and process query results.
Prerequisites
Before you begin, ensure that you have:
-
Membership in a MaxCompute project
-
CREATE INSTANCE permission on the project
-
SELECT and DOWNLOAD permissions on the tables you want to query
Version-specific requirements:
| JDBC version | Additional requirement |
|---|---|
| V1.9 and earlier | CREATE TABLE permission (a temporary table is created per query; use Tunnel commands to retrieve results) |
| V2.2 and later | No CREATE TABLE permission required (uses the InstanceTunnel interface; no temporary table is created) |
For more information about MaxCompute permissions, see MaxCompute permissions.
Limits and constraints
Data protection
If data protection is enabled for a project, data cannot move out of the project.
-
JDBC earlier than V2.4: no result sets can be retrieved.
-
JDBC V2.4 and later: result rows are limited by the
READ_TABLE_MAX_ROWparameter. For more information, see Project operations.
For more information about the data protection feature, see Project data protection.
Extended data types
The MaxCompute V2.0 data type edition supports more data types, such as TINYINT, SMALLINT, DATETIME, TIMESTAMP, ARRAY, MAP, and STRUCT. To enable these types, run the following command. For more information, see Data type editions.
set odps.sql.type.system.odps2=trueConcurrency control for long SQL statements
For JDBC V3.4.1 and later, limit concurrency when running SQL statements longer than 1 KB. For example, on an ECS instance with 8 vCPUs and 16.0 GiB of memory, keep concurrency at or below 100.
If you cannot control concurrency effectively, upgrade to JDBC V3.8.8 or V3.9.3 and set skipCheckIfSelect=true to disable SQL parsing. For more information, see Version updates.
Connection pools and transactions
MaxCompute uses REST services rather than persistent connections, so establishing a connection is lightweight. Connection pools are supported but not required.
MaxCompute does not support transactions. Every query runs immediately, and auto-commit mode is always enabled and cannot be disabled.
FAQ
Where is the JDBC driver log file?
By default, the log file is in the same directory as the JDBC driver JAR file and is named jdbc.log. If the driver is bundled in an uber JAR, the log file appears in the same directory as the uber JAR.
The log records JDBC API call details — class names, method names, parameters, return values, and row counts — which are useful for debugging.
How do I get a Logview URL?
The JDBC driver is built on MaxCompute SDK for Java, so Logview URLs are generated automatically when you run SQL statements through the driver, just as they are in the MaxCompute client, MaxCompute Studio, and DataWorks. Configure the properties.log4j parameter to capture Logview URLs; by default, they are written to standard error.
Use Logview URLs to check job status, track progress, and retrieve execution results.
How do I retrieve partition fields and column data types?
Call Connection.getMetadata() to get a DatabaseMetaData object, then call getColumns() to retrieve the metadata of all columns.