Downloading JDBC and connecting to MaxCompute - MaxCompute - Centro de documentación de Alibaba Cloud

Esta guía explica cómo descargar el controlador JDBC de MaxCompute y conectarse a MaxCompute. Incluye código de ejemplo para ayudarle a comenzar.

Precauciones

Para ejecutar sentencias SQL y obtener resultados mediante el controlador JDBC de MaxCompute, debe cumplir los siguientes requisitos:
- Debe ser miembro de un proyecto.
- Debe contar con el permiso CREATE INSTANCE en el proyecto.
- Debe tener los permisos SELECT y DOWNLOAD en la tabla que desea utilizar.
  Nota
  - Si utiliza MaxCompute JDBC V1.9 o versiones anteriores, se crea automáticamente una tabla temporal para cada consulta. Puede usar comandos de Tunnel para obtener los resultados desde dicha tabla temporal. Para usar estas versiones, es obligatorio contar con el permiso CREATE TABLE.
  - Si utiliza MaxCompute JDBC V2.2 o versiones posteriores, no se crea ninguna tabla temporal automáticamente para cada consulta. Puede llamar a la interfaz InstanceTunnel para obtener los resultados, independientemente de si tiene o no el permiso CREATE TABLE.
  Para obtener más información sobre los permisos de MaxCompute, consulte MaxCompute permissions.
MaxCompute ofrece la función de protección de datos. Si esta función está habilitada en un proyecto, no podrá extraer datos del mismo. Si utiliza una versión de MaxCompute JDBC anterior a la V2.4, no se podrán obtener result sets. Si utiliza MaxCompute JDBC V2.4 o posterior, la cantidad de filas de resultados que obtenga no podrá superar el valor del parámetro READ_TABLE_MAX_ROW. Para más detalles sobre este parámetro, consulte Project operations. Para obtener más información sobre la función de protección de datos, consulte Project data protection.

La edición de tipos de datos de MaxCompute V2.0 admite más tipos de datos, como TINYINT, SMALLINT, DATETIME, TIMESTAMP, ARRAY, MAP y STRUCT. Para utilizar estos nuevos tipos de datos, debe ejecutar el siguiente comando con el fin de habilitar la edición de tipos de datos de MaxCompute V2.0. Para obtener más información, consulte Data type version guide.
```
set odps.sql.type.system.odps2=true
```
En JDBC V3.4.1 y versiones posteriores, si maneja consultas SQL largas (superiores a 1 KB), controle cuidadosamente la concurrencia. Por ejemplo, al usar una instancia ECS con 8 vCPU y 16.0 GiB de memoria, la concurrencia no debería exceder 100. Si no logra controlar eficazmente la concurrencia, actualice JDBC a la versión V3.8.8 o V3.9.3 y establezca skipCheckIfSelect=true para deshabilitar la función de análisis sintáctico de SQL. Para más información sobre esta función, consulte Version updates.

Descarga del controlador JDBC

Puede obtener los paquetes JAR de MaxCompute para diferentes versiones desde OSS, GitHub o el repositorio de Maven. Se recomienda descargar el paquete JAR que incluye todas las dependencias (jar-with-dependencies).

A continuación se muestra la dependencia del Modelo de Objetos del Proyecto (POM) para usar el controlador JDBC de MaxCompute con Maven.

<dependency>
  <groupId>com.aliyun.odps</groupId>
  <artifactId>odps-jdbc</artifactId>
  <version>3.8.6</version>
  <classifier>jar-with-dependencies</classifier>
</dependency>

Nota

El controlador JDBC de MaxCompute es un proyecto de código abierto disponible en aliyun-odps-jdbc.

Sus contribuciones al desarrollo y mejora del controlador JDBC son bienvenidas. Puede reportar problemas en la página Issues o aportar mejoras de código mediante Pull requests. Al utilizar Issues y Pull requests, siga los requisitos de plantilla del proyecto.

Parámetros de JDBC

Puede configurar JDBC mediante parámetros de URL y objetos Properties. Los objetos Properties tienen mayor prioridad y anulan los parámetros de URL.

Nota

Si la clave de URL contiene odps_config=config_file, JDBC lee config_file como parámetros de Properties.

Parámetros básicos

Clave de URL	Clave de propiedad	Obligatorio	Descripción
project	project_name	Sí	El nombre del proyecto de MaxCompute.
accessId	access_id	Sí	El AccessKey ID de su cuenta de Alibaba Cloud. Puede obtener su AccessKey ID en la página AccessKey Management.
accessKey	access_key	Sí	El AccessKey secret de su cuenta de Alibaba Cloud. Puede obtener su AccessKey secret en la página AccessKey Management.
logview	logview_host	No	La URL de MaxCompute LogView. El valor es fijo: `http://logview.odps.aliyun.com`.
tunnelEndpoint	tunnel_endpoint	No	El endpoint del servicio MaxCompute Tunnel. Para consultar los endpoints de Tunnel correspondientes a cada región y tipo de red, consulte Endpoints.

Parámetros de configuración de registros

Clave de URL	Clave de propiedad	Obligatorio	Descripción
enableOdpsLogger	enable_odps_logger	No	Especifica si se habilita el registrador de MaxCompute JDBC. Valores válidos: False (predeterminado): Deshabilita el registrador. True: Habilitado. Los registros se escriben en el archivo `jdbc.log` dentro del directorio del paquete JAR.
logConfFile	log_conf_file	No	Permite especificar un archivo de configuración adicional de SLF4J para configurar de forma flexible la salida de registros, como el archivo de salida y logLevel. Este método requiere agregar las siguientes dependencias al archivo `pom.xml` de su proyecto: `<dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-core</artifactId> <version>1.2.3</version> </dependency> <dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> <version>1.2.3</version> </dependency>` Para ver un ejemplo de configuración, consulte Ejemplo de archivo de configuración.
logLevel	log_level	No	El nivel de registro de la salida. Valor predeterminado: INFO.

Otros parámetros

Clave de URL	Clave de propiedad	Obligatorio	Descripción
stsToken	sts_token	No	El token STS de Alibaba Cloud.
charset	charset	No	El conjunto de caracteres para entrada y salida. Valor predeterminado: UTF-8.
useProjectTimeZone	use_project_time_zone	No	Especifica si se usa la propiedad `odps.sql.timezone` del proyecto. Valores válidos: False (predeterminado): No usa la propiedad. True: Usa la propiedad. Nota También puede especificar la zona horaria en una sentencia mediante `set odps.sql.timezone=xxx`. Orden de prioridad: Sentencia > proyecto > null.
disableConnectionSetting	disable_connection_setting	No	Especifica si se permite establecer parámetros SQL para una conexión. Valores válidos: False (predeterminado): No permitido. True: Permitido. Cuando este parámetro se establece en true, el comando `set xxx` se aplica tanto a la sentencia como a la conexión. De lo contrario, solo se aplica a la sentencia.
settings	settings	No	Una cadena JSON para la `sql setting` global predeterminada. Ejemplo: `{"key":"value"}`.
tableList	table_list	No	Los nombres de las tablas de MaxCompute. Formato: `projectname.tablename,projectname1.tablename1`.
connectTimeout	connect_timeout	No	El tiempo de espera para establecer una conexión de red. Valor predeterminado: 10 segundos (s).
readTimeout	read_timeout	No	El tiempo de espera para leer datos de una conexión de red. Valor predeterminado: 120 segundos (s). Nota El tiempo de espera total para cada solicitud de API RESTful es la suma de connectTimeout y readTimeout, cuyo valor predeterminado es 130 segundos. El controlador reintenta cada solicitud hasta 3 veces. Para ajustar el tiempo de espera de conexión en solicitudes de API RESTful, modifique el parámetro readTimeout.
enableCommandApi	enable_command_api	No	Especifica si se usa la API de comandos. Valores válidos: False (predeterminado): No se usa la API de comandos. True: Se usa la API de comandos. Al habilitarla, puede ejecutar comandos en JDBC que normalmente son exclusivos de odpscmd.
httpsCheck	https_check	No	Especifica si se realiza la verificación del certificado HTTPS. Valores válidos: False (predeterminado): No se realiza la verificación. True: Se realiza la verificación.
tunnelConnectTimeout	tunnel_connect_timeout	No	El período de tiempo de espera de conexión para Tunnel al descargar datos. Valor predeterminado: 180 segundos (s).
tunnelReadTimeout	tunnel_read_timeout	No	El período de tiempo de espera de lectura para Tunnel al descargar datos. Valor predeterminado: 300 segundos (s).
skipCheckIfSelect	skipCheckIfSelect	No	Especifica si se omite el análisis sintáctico de SQL. Valores válidos: False (predeterminado): No omite el análisis. True: Omite el análisis. Nota Omitir el análisis puede reducir el consumo de CPU y memoria del lado del cliente, pero podría aumentar la latencia en sentencias que no sean SELECT.

Parámetros no MCQA (válidos solo en modo sin conexión)

Clave de URL

Clave de propiedad

Obligatorio

Descripción

autoLimitFallback

auto_limit_fallback

Reversión automática de límite. Valores válidos:

False (predeterminado): No revierte.
True: Revierte. En modo sin conexión, cuando Tunnel reporta una excepción de no download permission, el controlador revierte automáticamente y limita la cantidad de registros descargados a 10,000.

Parámetros de MaxQA/MCQA 1.0 (válidos solo para MaxQA/MCQA 1.0)

Configuración básica

Clave de URL	Clave de propiedad	Obligatorio	Descripción
interactiveMode	interactive_mode	No	Especifica si se habilita MaxQA/MCQA 1.0. Valores válidos: False (predeterminado): Deshabilitado. True: Habilitado.
executeProject	execute_project_name	No	El nombre del proyecto de MaxCompute donde se ejecuta realmente la tarea SQL.
tunnelRetryTime	tunnel_retry_time	No	El número de reintentos de Tunnel para SQLExecutor. Valor predeterminado: 6.
attachTimeout	attach_timeout	No	El período de tiempo de espera para establecer una conexión MCQA 1.0. Valor predeterminado: 60 segundos (s).
fallbackQuota	fallback_quota	No	La cuota que se utiliza cuando una tarea MCQA 1.0 revierte. Si no se configura, se usa la cuota predeterminada del proyecto.
quotaName	quota_name	No	La cuota de recursos de cómputo utilizada por la tarea MaxQA.

Parámetros relacionados con límites

Clave de URL	Clave de propiedad	Obligatorio	Descripción
instanceTunnelMaxRecord	instance_tunnel_max_record	No	El número máximo de registros en el conjunto de resultados. Nota Este parámetro surte efecto únicamente cuando el parámetro enableLimit se establece en False.
instanceTunnelMaxSize	instance_tunnel_max_size	No	El tamaño máximo del conjunto de resultados. Unidad: byte.
autoSelectLimit	auto_select_limit	No	El límite automático de consulta. De forma predeterminada, puede consultar un máximo de 1,000,000 filas en entornos de nube pública de Alibaba Cloud. Para consultar más datos, configure este parámetro. Nota Este parámetro surte efecto únicamente cuando el parámetro enableLimit se establece en False. En JDBC V3.2.29 y versiones posteriores, si establece el parámetro autoSelectLimit, el parámetro enableLimit se configura automáticamente en False.
enableLimit	enable_limit	No	Especifica si se habilita el límite. Valores válidos: False: El límite no está habilitado. True (predeterminado): El límite está habilitado. Si se habilita, no se verifica el permiso de descarga y los conjuntos de resultados se limitan a 10,000 registros de forma predeterminada.

Parámetros relacionados con reversión

Clave de URL	Clave de propiedad	Obligatorio	Descripción
fallbackForUnknownError	fallback_for_unknownerror	No	Especifica si se revierte al modo sin conexión cuando ocurre un error desconocido. Valores válidos: False: No revierte. True (predeterminado): Revierte.
fallbackForResourceNotEnough	fallback_for_resourcenotenough	No	Especifica si se revierte al modo sin conexión cuando los recursos son insuficientes. Valores válidos: False: No revierte. True (predeterminado): Revierte.
fallbackForUpgrading	fallback_for_upgrading	No	Especifica si se revierte al modo sin conexión durante una actualización. Valores válidos: False: No revierte. True (predeterminado): Revierte.
fallbackForRunningTimeout	fallback_for_runningtimeout	No	Especifica si se revierte al modo sin conexión cuando se agota el tiempo de espera de un comando de operación. Valores válidos: False: No revierte. True (predeterminado): Revierte.
fallbackForUnsupportedFeature	fallback_for_unsupported_feature	No	Especifica si se revierte al modo sin conexión cuando se utiliza una función MCQA no compatible. Valores válidos: False: No revierte. True (predeterminado): Revierte.
alwaysFallback	always_fallback	No	Especifica si se revierte al modo sin conexión en todos los escenarios anteriores. Valores válidos: False (predeterminado): No revierte. True: Revierte. Nota Este parámetro solo es compatible con JDBC V3.2.3 y versiones posteriores.
disableFallback	disable_fallback	No	Especifica si se deshabilita la reversión al modo sin conexión en todos los escenarios anteriores. Valores válidos: False (predeterminado): Revierte. True: No revierte.
fallbackQuota	fallback_quota	No	El nombre de la cuota a la que revierte una tarea MCQA. Si no se configura, se usa la cuota predeterminada del proyecto.

Conexión a MaxCompute

Cargue el controlador JDBC de MaxCompute.

Class.forName("com.aliyun.odps.jdbc.OdpsDriver");

Cree una conexión mediante DriverManager.
```
Connection cnct = DriverManager.getConnection(url, accessId, accessKey);
```
- url: La URL debe tener el siguiente formato: jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project_name>[&useProjectTimeZone={true|false}]. Los parámetros se describen a continuación:
  - <maxcompute_endpoint>: El endpoint del servicio MaxCompute para la región. Por ejemplo, el endpoint público para la región China (Hangzhou) es http://service.cn-hangzhou.maxcompute.aliyun.com/api. Para obtener más información, consulte Endpoints.
  - <maxcompute_project_name>: El nombre del proyecto de MaxCompute.
  - useProjectTimeZone: Especifica si se usa la zona horaria del proyecto de MaxCompute.
  Ejemplo:
```
jdbc:odps:http://service.cn-hangzhou.maxcompute.aliyun.com/api?project=test_project&useProjectTimeZone=true;
```
- accessId: El AccessKey ID de su cuenta de Alibaba Cloud.
- accessKey: El AccessKey secret correspondiente al AccessKey ID.
  
  Nota
  Para crear y consultar un AccessKey ID y un AccessKey secret, consulte Prepare an Alibaba Cloud account.

Ejecute una consulta.

try (
    Statement stmt = cnct.createStatement();
    ResultSet rset = stmt.executeQuery("SELECT foo FROM bar;")
) {
    while (rset.next()) {
      // process the results
    }
} catch (SQLException e) {
  // handle the exception
} finally {
    if (cnct != null) {
        try {
            cnct.close();
        } catch (SQLException e) {
            // Ignore or record a closed exception
        }
    }
}

Código de ejemplo

Eliminar una tabla, crear una tabla y obtener metadatos

Nota

Si agrega la dependencia JDBC a su proyecto, no agregue la dependencia del SDK por separado. La dependencia JDBC incluye el SDK obligatorio; agregarlo por separado puede provocar errores por incompatibilidad de versiones.

import java.sql.Connection;
import java.sql.DatabaseMetaData;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class Main {

    private static final String DRIVER_NAME = "com.aliyun.odps.jdbc.OdpsDriver";
    // An Alibaba Cloud account's AccessKey pair has permissions for all API operations, which is a security risk. We strongly recommend using a RAM user for API access or routine O&M. To create a RAM user, log on to the RAM console.
    // This example stores the AccessKey ID and AccessKey secret in environment variables. You can also store them in a configuration file based on your business requirements.
    // For security, do not hardcode the AccessKey ID and AccessKey secret in your code.
    private static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
    private static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

    public static void main(String[] args) {
        try {
            Class.forName(DRIVER_NAME);
        } catch (ClassNotFoundException e) {
            e.printStackTrace();
            System.exit(1);
        }

        try (
            Connection conn = DriverManager.getConnection(
                "jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project>",
                Main.accessId, Main.accessKey);
            Statement stmt = conn.createStatement()
        ) {
            // create a table
            final String tableName = "jdbc_test";
            stmt.execute("DROP TABLE IF EXISTS " + tableName);
            stmt.execute("CREATE TABLE " + tableName + " (key BIGINT, value STRING)");

            // get meta data
            DatabaseMetaData metaData = conn.getMetaData();
            System.out.println("product = " + metaData.getDatabaseProductName());
            System.out.println("jdbc version = "
                               + metaData.getDriverMajorVersion() + ", "
                               + metaData.getDriverMinorVersion());

            try (ResultSet tables = metaData.getTables(null, "default", tableName, null)) {
                while (tables.next()) {
                    String name = tables.getString("TABLE_NAME");
                    System.out.println("inspecting table: " + name);

                    try (ResultSet columns = metaData.getColumns(null, null, name, null)) {
                        while (columns.next()) {
                            System.out.println(
                                columns.getString("COLUMN_NAME") + "\t" +
                                columns.getString("TYPE_NAME") + "(" +
                                columns.getInt("DATA_TYPE") + ")");
                        }
                    }
                }
            }
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

Salida de ejemplo:

product = MaxCompute/ODPS
jdbc version = 3, 8
inspecting table: jdbc_test
key    BIGINT(-5)
value    STRING(12)

Actualizar una tabla

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;

public class Main {

    private static final String DRIVER_NAME = "com.aliyun.odps.jdbc.OdpsDriver";
    // An Alibaba Cloud account's AccessKey pair has permissions for all API operations, which is a security risk. We strongly recommend using a RAM user for API access or routine O&M. To create a RAM user, log on to the RAM console.
    // This example stores the AccessKey ID and AccessKey secret in environment variables. You can also store them in a configuration file based on your business requirements.
    // For security, do not hardcode the AccessKey ID and AccessKey secret in your code.
    private static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
    private static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

    public static void main(String[] args) {
        try {
            Class.forName(DRIVER_NAME);
        } catch (ClassNotFoundException e) {
            e.printStackTrace();
            System.exit(1);
        }

        try (
            Connection conn = DriverManager.getConnection(
                "jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project>",
                Main.accessId, Main.accessKey);
            Statement stmt = conn.createStatement()
        ) {
            // The following DML also works
            // String dml = "INSERT INTO jdbc_test SELECT 1, \"foo\"";
            String dml = "INSERT INTO jdbc_test VALUES(1, \"foo\")";
            int ret = stmt.executeUpdate(dml);

            assert ret == 1;
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

Actualizar una tabla en lotes

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;

public class Main {

    private static final String DRIVER_NAME = "com.aliyun.odps.jdbc.OdpsDriver";
    // An Alibaba Cloud account's AccessKey pair has permissions for all API operations, which is a security risk. We strongly recommend using a RAM user for API access or routine O&M.
    // This example stores the AccessKey ID and AccessKey secret in environment variables. You can also store them in a configuration file based on your business requirements.
    // For security, do not hardcode the AccessKey ID and AccessKey secret in your code.
    private static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
    private static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

    public static void main(String[] args) {
        try {
            Class.forName(DRIVER_NAME);
        } catch (ClassNotFoundException e) {
            e.printStackTrace();
            System.exit(1);
        }

        try (
            Connection conn = DriverManager.getConnection(
                "jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project>",
                Main.accessId, Main.accessKey);
            PreparedStatement pstmt = conn.prepareStatement("INSERT INTO jdbc_test VALUES(?, ?)")
        ) {
            // First batch
            pstmt.setLong(1, 1L);
            pstmt.setString(2, "foo");
            pstmt.addBatch();

            // Second batch
            pstmt.setLong(1, 2L);
            pstmt.setString(2, "bar");
            pstmt.addBatch();

            int[] ret = pstmt.executeBatch();

            assert ret[0] == 1;
            assert ret[1] == 1;

        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

Nota

El método executeBatch no admite escrituras por lotes en tablas agrupadas, como las tablas Transaction Table 2.0.

Para escribir datos en una tabla particionada estándar en lotes, debe especificar la partición de destino en la instrucción INSERT INTO. Ejemplo:

-- The table creation statement for the partitioned table sale_detail is as follows.
create table if not exists sale_detail
(
shop_name string,
customer_id string,
total_price double
)
partitioned by (sale_date string, region string);

-- Assume that the partition sale_date='20240219', region='hangzhou' already exists. The INSERT INTO statement for batch writes to the partitioned table is as follows.
INSERT INTO sale_detail PARTITION(sale_date='20240219', region='hangzhou') VALUES(?, ?, ?)

Consultar una tabla

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class Main {

    private static final String DRIVER_NAME = "com.aliyun.odps.jdbc.OdpsDriver";
    // An Alibaba Cloud account's AccessKey pair has permissions for all API operations, which is a security risk. We strongly recommend using a RAM user for API access or routine O&M.
    // This example stores the AccessKey ID and AccessKey secret in environment variables. You can also store them in a configuration file based on your business requirements.
    // For security, do not hardcode the AccessKey ID and AccessKey secret in your code.
    private static String accessId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
    private static String accessKey = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET");

    public static void main(String[] args) {
        try {
            Class.forName(DRIVER_NAME);
        } catch (ClassNotFoundException e) {
            e.printStackTrace();
            System.exit(1);
        }

        try (
            Connection conn = DriverManager.getConnection(
                "jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project>",
                accessId, accessKey);
            Statement stmt = conn.createStatement();
            ResultSet rset = stmt.executeQuery("SELECT * FROM JDBC_TEST")
        ) {
            while (rset.next()) {
                System.out.println(rset.getInt(1) + "\t" + rset.getString(2));
            }
        } catch (SQLException e) {
            e.printStackTrace();
        }
    }
}

Nota

OdpsStatement admite tres métodos: execute(sql), executeQuery(sql) y executeUpdate(sql). Los métodos execute(sql) y executeQuery(sql) también admiten tres comandos comunes: desc table, show tables y show partitions.