Téléchargement du pilote JDBC et connexion à MaxCompute - MaxCompute

Précautions

Pour exécuter des instructions SQL et obtenir les résultats d'exécution à l'aide du pilote MaxCompute JDBC, respectez les exigences suivantes :
- Vous êtes membre d'un projet.
- Vous disposez de l'autorisation CREATE INSTANCE sur le projet.
- Vous disposez des autorisations SELECT et DOWNLOAD sur la table que vous souhaitez utiliser.
  Remarque
  - Avec MaxCompute JDBC V1.9 ou une version antérieure, une table temporaire est automatiquement créée pour chaque requête. Utilisez les commandes Tunnel pour obtenir les résultats de la requête à partir de la table temporaire. Pour utiliser ces versions, vous devez disposer de l'autorisation CREATE TABLE.
  - Avec MaxCompute JDBC V2.2 ou une version ultérieure, aucune table temporaire n'est automatiquement créée pour chaque requête. Appelez l'interface InstanceTunnel pour obtenir les résultats de la requête, que vous disposiez ou non de l'autorisation CREATE TABLE.
  Pour plus d'informations sur les autorisations MaxCompute, consultez Autorisations MaxCompute.
MaxCompute propose la fonctionnalité de protection des données. Si cette fonctionnalité est activée pour un projet, vous ne pouvez pas déplacer les données hors du projet. Avec une version de MaxCompute JDBC antérieure à la V2.4, aucun result sets ne peut être obtenu. Avec MaxCompute JDBC V2.4 ou une version ultérieure, le nombre de lignes de résultat obtenues ne peut pas dépasser la valeur du paramètre READ_TABLE_MAX_ROW. Pour plus d'informations sur ce paramètre, consultez Opérations sur les projets. Pour plus d'informations sur la fonctionnalité de protection des données, consultez Protection des données du projet.

L'édition des types de données MaxCompute V2.0 prend en charge davantage de types de données, tels que TINYINT, SMALLINT, DATETIME, TIMESTAMP, ARRAY, MAP et STRUCT. Pour utiliser ces nouveaux types de données, exécutez la commande suivante afin d'activer l'édition des types de données MaxCompute V2.0. Pour plus d'informations, consultez Guide des versions des types de données.
```
set odps.sql.type.system.odps2=true
```
Avec JDBC V3.4.1 et versions ultérieures, si vos requêtes SQL sont longues (supérieures à 1 Ko), contrôlez attentivement la concurrence. Par exemple, avec une instance ECS dotée de 8 vCPU et de 16,0 GiB de mémoire, la concurrence ne doit pas dépasser 100. Si vous ne pouvez pas contrôler efficacement la concurrence, mettez à niveau JDBC vers la V3.8.8 ou la V3.9.3 et définissez skipCheckIfSelect=true pour désactiver la fonctionnalité d'analyse SQL. Pour plus d'informations sur cette fonctionnalité, consultez Mises à jour de version.

Télécharger le pilote JDBC

Obtenez les packages JAR MaxCompute pour différentes versions depuis OSS, GitHub ou le référentiel Maven. Nous vous recommandons de télécharger le package JAR qui inclut toutes les dépendances (jar-with-dependencies).

L'exemple suivant montre la dépendance Project Object Model (POM) pour utiliser le pilote MaxCompute JDBC avec Maven.

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

Remarque

Le pilote MaxCompute JDBC est un projet open source disponible à l'adresse aliyun-odps-jdbc.

Vos contributions au développement et à l'amélioration du pilote JDBC sont les bienvenues. Signalez des problèmes sur la page Issues ou contribuez à l'amélioration du code via les Pull requests. Lors de l'utilisation des Issues et des Pull requests, respectez les exigences de modèle du projet.

Paramètres JDBC

Configurez JDBC à l'aide des paramètres URL et des objets Properties. Les objets Properties ont une priorité plus élevée et remplacent les paramètres URL.

Remarque

Si la clé URL contient odps_config=config_file, JDBC lit config_file comme paramètres Properties.

Paramètres de base

Clé URL

Clé Property

Obligatoire

Description

project

project_name

Oui

Nom du projet MaxCompute.

accessId

access_id

Oui

ID de la clé AccessKey de votre compte Alibaba Cloud.

Obtenez votre ID de clé AccessKey sur la page Gestion des clés AccessKey.

accessKey

access_key

Oui

Secret de la clé AccessKey de votre compte Alibaba Cloud.

Obtenez le secret de votre clé AccessKey sur la page Gestion des clés AccessKey.

logview

logview_host

Non

URL de MaxCompute LogView. La valeur est fixée à http://logview.odps.aliyun.com.

tunnelEndpoint

tunnel_endpoint

Non

Endpoint du service MaxCompute Tunnel.

Pour connaître les endpoints Tunnel pour chaque région et type de réseau, consultez Endpoints.

Paramètres de configuration des journaux

Clé URL	Clé Property	Obligatoire	Description
enableOdpsLogger	enable_odps_logger	Non	Indique s'il faut activer le journaliseur MaxCompute JDBC. Valeurs possibles : False (par défaut) : Désactive le journaliseur. True : Activé. Les journaux sont écrits dans le fichier `jdbc.log` situé dans le répertoire du package JAR.
logConfFile	log_conf_file	Non	Spécifiez un fichier de configuration SLF4J supplémentaire pour configurer de manière flexible la sortie des journaux, tels que le fichier de sortie et le logLevel. Cette méthode nécessite d'ajouter les dépendances suivantes au fichier `pom.xml` de votre projet : `<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>` Pour un exemple de configuration, consultez Exemple de fichier de configuration.
logLevel	log_level	Non	Niveau de journalisation de la sortie. Valeur par défaut : INFO.

Autres paramètres

Clé URL	Clé Property	Obligatoire	Description
stsToken	sts_token	Non	Jeton STS Alibaba Cloud.
charset	charset	Non	Jeu de caractères pour l'entrée et la sortie. Valeur par défaut : UTF-8.
useProjectTimeZone	use_project_time_zone	Non	Indique s'il faut utiliser la propriété `odps.sql.timezone` du projet. Valeurs possibles : False (par défaut) : N'utilise pas la propriété. True : Utilise la propriété. Remarque Vous pouvez également spécifier le fuseau horaire dans une instruction à l'aide de `set odps.sql.timezone=xxx`. Ordre de priorité : Instruction > projet > null.
disableConnectionSetting	disable_connection_setting	Non	Indique s'il est autorisé de définir des paramètres SQL pour une connexion. Valeurs possibles : False (par défaut) : Non autorisé. True : Autorisé. Lorsque ce paramètre est défini sur true, la commande `set xxx` s'applique à la fois à l'instruction et à la connexion. Sinon, elle s'applique uniquement à l'instruction.
settings	settings	Non	Chaîne JSON pour le paramètre `sql setting` global par défaut. Exemple : `{"key":"value"}`.
tableList	table_list	Non	Noms des tables MaxCompute. Format : `projectname.tablename,projectname1.tablename1`.
connectTimeout	connect_timeout	Non	Délai d'attente pour l'établissement d'une connexion réseau. Valeur par défaut : 10 secondes (s).
readTimeout	read_timeout	Non	Délai d'attente pour la lecture des données depuis une connexion réseau. Valeur par défaut : 120 secondes (s). Remarque Le délai d'attente total pour chaque requête API RESTful est la somme de connectTimeout et readTimeout, soit 130 secondes par défaut. Le pilote réessaie chaque requête jusqu'à 3 fois. Pour ajuster le délai d'attente de connexion pour les requêtes API RESTful, modifiez le paramètre readTimeout.
enableCommandApi	enable_command_api	Non	Indique s'il faut utiliser l'API de commande. Valeurs possibles : False (par défaut) : L'API de commande n'est pas utilisée. True : L'API de commande est utilisée. Une fois activée, vous pouvez exécuter des commandes dans JDBC qui sont normalement exclusives à odpscmd.
httpsCheck	https_check	Non	Indique s'il faut effectuer la vérification du certificat HTTPS. Valeurs possibles : False (par défaut) : La vérification n'est pas effectuée. True : La vérification est effectuée.
tunnelConnectTimeout	tunnel_connect_timeout	Non	Délai d'attente de connexion pour Tunnel lors du téléchargement des données. Valeur par défaut : 180 secondes (s).
tunnelReadTimeout	tunnel_read_timeout	Non	Délai d'attente de lecture pour Tunnel lors du téléchargement des données. Valeur par défaut : 300 secondes (s).
skipCheckIfSelect	skipCheckIfSelect	Non	Indique s'il faut ignorer l'analyse SQL. Valeurs possibles : False (par défaut) : N'ignore pas l'analyse. True : Ignore l'analyse. Remarque Ignorer l'analyse peut réduire la consommation de CPU et de mémoire côté client, mais peut augmenter la latence pour les instructions autres que SELECT.

Paramètres non-MCQA (effectifs uniquement en mode hors ligne)

Clé URL

Clé Property

Obligatoire

Description

autoLimitFallback

auto_limit_fallback

Non

Repli automatique de limite. Valeurs possibles :

False (par défaut) : Pas de repli.
True : Repli. En mode hors ligne, lorsque Tunnel signale une exception no download permission, le pilote effectue automatiquement un repli et limite le nombre d'enregistrements téléchargés à 10 000.

Paramètres MaxQA/MCQA 1.0 (effectifs uniquement pour MaxQA/MCQA 1.0)

Configuration de base

Clé URL	Clé Property	Obligatoire	Description
interactiveMode	interactive_mode	Non	Indique s'il faut activer MaxQA/MCQA 1.0. Valeurs possibles : False (par défaut) : Désactivé. True : Activé.
executeProject	execute_project_name	Non	Nom du projet MaxCompute où la tâche SQL s'exécute réellement.
tunnelRetryTime	tunnel_retry_time	Non	Nombre de tentatives Tunnel pour SQLExecutor. Valeur par défaut : 6.
attachTimeout	attach_timeout	Non	Délai d'attente pour l'établissement d'une connexion MCQA 1.0. Valeur par défaut : 60 secondes (s).
fallbackQuota	fallback_quota	Non	Quota à utiliser lorsqu'une tâche MCQA 1.0 effectue un repli. S'il n'est pas configuré, le quota par défaut du projet est utilisé.
quotaName	quota_name	Non	Quota de ressources de calcul utilisé par la tâche MaxQA.

Paramètres liés aux limites

Clé URL	Clé Property	Obligatoire	Description
instanceTunnelMaxRecord	instance_tunnel_max_record	Non	Nombre maximal d'enregistrements dans l'ensemble de résultats. Remarque Ce paramètre prend effet uniquement lorsque le paramètre enableLimit est défini sur False.
instanceTunnelMaxSize	instance_tunnel_max_size	Non	Taille maximale de l'ensemble de résultats. Unité : octet.
autoSelectLimit	auto_select_limit	Non	Limite de requête automatique. Par défaut, vous pouvez interroger un maximum de 1 000 000 de lignes dans les environnements de cloud public Alibaba Cloud. Pour interroger plus de données, configurez ce paramètre. Remarque Ce paramètre prend effet uniquement lorsque le paramètre enableLimit est défini sur False. Avec JDBC V3.2.29 et versions ultérieures, si vous définissez le paramètre autoSelectLimit, le paramètre enableLimit est automatiquement défini sur False.
enableLimit	enable_limit	Non	Indique s'il faut activer la limite. Valeurs possibles : False : La limite n'est pas activée. True (par défaut) : La limite est activée. Si elle est activée, l'autorisation de téléchargement n'est pas vérifiée et les ensembles de résultats sont limités à 10 000 enregistrements par défaut.

Paramètres liés au repli

Clé URL	Clé Property	Obligatoire	Description
fallbackForUnknownError	fallback_for_unknownerror	Non	Indique s'il faut revenir au mode hors ligne en cas d'erreur inconnue. Valeurs possibles : False : Pas de repli. True (par défaut) : Repli.
fallbackForResourceNotEnough	fallback_for_resourcenotenough	Non	Indique s'il faut revenir au mode hors ligne en cas de ressources insuffisantes. Valeurs possibles : False : Pas de repli. True (par défaut) : Repli.
fallbackForUpgrading	fallback_for_upgrading	Non	Indique s'il faut revenir au mode hors ligne pendant une mise à niveau. Valeurs possibles : False : Pas de repli. True (par défaut) : Repli.
fallbackForRunningTimeout	fallback_for_runningtimeout	Non	Indique s'il faut revenir au mode hors ligne en cas de dépassement du délai d'attente d'une commande d'opération. Valeurs possibles : False : Pas de repli. True (par défaut) : Repli.
fallbackForUnsupportedFeature	fallback_for_unsupported_feature	Non	Indique s'il faut revenir au mode hors ligne lorsqu'une fonctionnalité MCQA non prise en charge est utilisée. Valeurs possibles : False : Pas de repli. True (par défaut) : Repli.
alwaysFallback	always_fallback	Non	Indique s'il faut revenir au mode hors ligne dans tous les scénarios précédents. Valeurs possibles : False (par défaut) : Pas de repli. True : Repli. Remarque Ce paramètre est pris en charge uniquement dans JDBC V3.2.3 et versions ultérieures.
disableFallback	disable_fallback	Non	Indique s'il faut désactiver le repli vers le mode hors ligne dans tous les scénarios précédents. Valeurs possibles : False (par défaut) : Repli. True : Pas de repli.
fallbackQuota	fallback_quota	Non	Nom du quota vers lequel une tâche MCQA effectue un repli. S'il n'est pas configuré, le quota par défaut du projet est utilisé.

Se connecter à MaxCompute

Chargez le pilote MaxCompute JDBC.

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

Créez une connexion à l'aide de DriverManager.
```
Connection cnct = DriverManager.getConnection(url, accessId, accessKey);
```
- url : L'URL doit être au format suivant : jdbc:odps:<maxcompute_endpoint>?project=<maxcompute_project_name>[&useProjectTimeZone={true|false}]. Les paramètres sont décrits ci-dessous :
  - <maxcompute_endpoint> : Endpoint du service MaxCompute pour la région. Par exemple, l'endpoint public pour la région Chine (Hangzhou) est http://service.cn-hangzhou.maxcompute.aliyun.com/api. Pour plus d'informations, consultez Endpoints.
  - <maxcompute_project_name> : Nom du projet MaxCompute.
  - useProjectTimeZone : Indique s'il faut utiliser le fuseau horaire du projet MaxCompute.
  Exemple :
```
jdbc:odps:http://service.cn-hangzhou.maxcompute.aliyun.com/api?project=test_project&useProjectTimeZone=true;
```
- accessId : ID de la clé AccessKey de votre compte Alibaba Cloud.
- accessKey : Secret de la clé AccessKey correspondant à l'ID de la clé AccessKey.
  
  Remarque
  Pour créer et afficher un ID de clé AccessKey et un secret de clé AccessKey, consultez Préparer un compte Alibaba Cloud.

Exécutez une requête.

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
        }
    }
}

Exemples de code

Supprimer une table, créer une table et obtenir des métadonnées

Remarque

Si vous ajoutez la dépendance JDBC à votre projet, n'ajoutez pas séparément la dépendance SDK. La dépendance JDBC inclut le SDK requis et l'ajouter séparément peut provoquer des erreurs d'incompatibilité de version.

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();
        }
    }
}

Exemple de sortie :

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

Mettre à jour une table

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();
        }
    }
}

Mettre à jour une table par lots

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();
        }
    }
}

Remarque

La méthode executeBatch ne prend pas en charge les écritures par lots dans les tables clusterisées, telles que les tables Transaction Table 2.0.

Pour écrire des données dans une table partitionnée standard par lots, spécifiez la partition cible dans l'instruction INSERT INTO. Exemple :

-- 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(?, ?, ?)

Interroger une table

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();
        }
    }
}

Remarque

OdpsStatement prend en charge trois méthodes : execute(sql), executeQuery(sql) et executeUpdate(sql). Les méthodes execute(sql) et executeQuery(sql) prennent également en charge trois commandes courantes : desc table, show tables et show partitions.