Utiliser le pilote JDBC pour BigQuery

Le pilote Java Database Connectivity (JDBC) pour BigQuery connecte vos applications Java à BigQuery, ce qui vous permet d'utiliser les fonctionnalités de BigQuery avec vos outils et votre infrastructure préférés. Pour connecter des applications non Java à BigQuery, utilisez le pilote Open Database Connectivity (ODBC) pour BigQuery.

Limites

Le pilote JDBC pour BigQuery est soumis aux limitations suivantes :

• Le pilote est spécifique à BigQuery et ne peut pas être utilisé avec d'autres produits ou services.
• Le type de données INTERVAL n'est pas compatible avec l'API BigQuery Storage Read.
• Toutes les limites du langage de manipulation de données (LMD) s'appliquent.

Avant de commencer

1. Assurez-vous de bien connaître les pilotes JDBC, Apache Maven et le package java.sql.
2. Vérifiez que votre système est configuré avec l'environnement d'exécution Java (JRE) 8.0 ou version ultérieure. Pour savoir comment vérifier la version de votre JRE, consultez Vérifier l'environnement JRE.

3. Authentifiez-vous auprès de BigQuery et notez les informations suivantes, qui seront utilisées ultérieurement lorsque vous établirez une connexion avec le pilote JDBC pour BigQuery. Il vous suffit de noter les informations correspondant à la méthode d'authentification que vous utilisez.

   Méthode d'authentification	Informations d'authentification	Exemple	Propriété de connexion (à définir ultérieurement)
   Compte de service standard	Adresse e-mail du compte de service	bq-jdbc-sa@mytestproject.s3ns.iam.gserviceaccount.com	OAuthServiceAcctEmail
   	Clé de compte de service (objet JSON)	my-sa-key	OAuthPvtKey
   Fichier de clé du compte de service	Fichier de clé du compte de service (chemin d'accès complet)	path/to/file/secret.json	OAuthPvtKeyPath
   Compte utilisateur Google	ID client	123-abc.apps.googleusercontent.com	OAuthClientId
   	Code secret du client	_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV	OAuthClientSecret
   Jeton d'accès prégénéré	Jeton d'accès	ya29.a0AfH6SMCiH1L-x_yZ	OAuthAccessToken
   Jeton d'actualisation prégénéré	Jeton d'actualisation	1/fFAGRNJru1FTz70BzhT3Zg	OAuthRefreshToken
   	ID client	123-abc.apps.googleusercontent.com	OAuthClientId
   	Code secret du client	_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV	OAuthClientSecret
   Identifiants par défaut de l'application	Aucun	N/A	N/A
   Fichier de configuration	Fichier de configuration (objet JSON ou chemin d'accès complet)	path/to/file/secret.json	OAuthPvtKey
   Objet de configuration de compte externe	Objet de configuration du compte	external_account_configuration_object	OAuthPvtKey
   Autre	Propriété d'audience du fichier de configuration du compte externe	//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider	BYOID_AudienceUri
   	Fichier de récupération de jeton et d'informations sur l'environnement	{\"file\":\"/path/to/file\"}	BYOID_CredentialSource
   	Projet utilisateur (uniquement si vous utilisez un pool d'employés)	my_project	BYOID_PoolUserProject
   	URI pour l'emprunt d'identité d'un compte de service (uniquement si vous utilisez un pool d'employés)	my-sa	BYOID_SA_Impersonation_Uri
   	Jeton Security Token Service basé sur la spécification d'échange de jetons	urn:ietf:params:oauth:tokentype:id_token	BYOID_SubjectTokenType
   	Point de terminaison d'échange de jetons Security Token Service	https://sts.googleapis.com/v1/token	BYOID_TokenUri

Installer et configurer le pilote JDBC

Vous pouvez installer et configurer le pilote JDBC pour BigQuery en téléchargeant directement le fichier uber-JAR ou en utilisant Maven.

Configuration du téléchargement direct

Pour configurer le pilote JDBC par téléchargement direct, procédez comme suit :

1. Téléchargez la version 1.6.0 du pilote.
2. Copiez le fichier téléchargé à l'emplacement spécifié par votre logiciel.

Pour en savoir plus sur les modifications apportées aux fonctionnalités et les mises à jour des workflows, consultez le journal des modifications.

Configuration de Maven

Le pilote JDBC pour BigQuery est disponible sur Maven Central.

Pour configurer votre environnement de développement avec le pilote JDBC, ajoutez le pilote en tant que dépendance à votre projet :

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.6.0</version>
</dependency>

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.6.0</version>
    <classifier>all</classifier>
    <exclusions>
      <exclusion>
        <groupId>*</groupId>
        <artifactId>*</artifactId>
      </exclusion>
    </exclusions>
</dependency>

dependencies {
// ... other dependencies
implementation("com.google.cloud:google-cloud-bigquery-jdbc:1.6.0")
}

Établir une connexion

Pour établir une connexion entre votre application Java et BigQuery avec le pilote JDBC pour BigQuery, procédez comme suit :

1. Identifiez votre chaîne de connexion pour le pilote JDBC pour BigQuery. Cette chaîne capture toutes les informations requises pour établir une connexion entre votre application Java et BigQuery. La chaîne de connexion utilise le format suivant :

   jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

   Remplacez les éléments suivants :

   • HOST : adresse DNS ou adresse IP du serveur.
   • PORT : numéro de port TCP.
   • PROJECT_ID : ID de votre projet BigQuery.
   • AUTH_TYPE : nombre spécifiant le type d'authentification que vous avez utilisé. Choisissez l'une des options suivantes :
     • 0 : pour l'authentification par compte de service (standard et fichier de clé)
     • 1 : pour l'authentification du compte utilisateur Google
     • 2 : pour l'authentification par jeton d'actualisation ou jeton d'accès prégénéré
     • 3 : pour l'authentification par identifiants par défaut de l'application
     • 4 : pour les autres méthodes d'authentification
   • AUTH_PROPS : informations d'authentification que vous avez notées lorsque vous vous êtes authentifié auprès de BigQuery, listées au format property_1=value_1; property_2=value_2;... (par exemple, OAuthPvtKeyPath=path/to/file/secret.json si vous vous êtes authentifié avec un fichier de clé de compte de service).
   • OTHER_PROPS (facultatif) : propriétés de connexion supplémentaires pour le pilote JDBC, listées au format property_1=value_1; property_2=value_2;.... Pour obtenir la liste complète des propriétés de connexion, consultez Propriétés de connexion.

2. Connectez votre application Java au pilote JDBC pour BigQuery à l'aide de la classe DriverManager ou DataSource.

   • Connectez-vous avec la classe DriverManager :

     import java.sql.Connection;
     import java.sql.DriverManager;
     
     private static Connection getJdbcConnectionDM(){
       Connection connection = DriverManager.getConnection(CONNECTION_STRING);
       return connection;
     }

     Remplacez CONNECTION_STRING par la chaîne de connexion de l'étape précédente.

   • Connectez-vous avec la classe DataSource :

     import com.google.cloud.bigquery.jdbc.DataSource;
     import java.sql.Connection;
     import java.sql.SQLException;
     
     private static public Connection getJdbcConnectionDS() throws SQLException {
       Connection connection = null;
       DataSource dataSource = new com.google.cloud.bigquery.jdbc.DataSource();
       dataSource.setURL(CONNECTION_STRING);
       connection = dataSource.getConnection();
       return connection;
     }

     Remplacez CONNECTION_STRING par la chaîne de connexion de l'étape précédente.

     La classe DataSource comporte également des méthodes setter que vous pouvez utiliser pour définir les propriétés de connexion, plutôt que de les inclure dans la chaîne de connexion. En voici un exemple :

     private static Connection getConnection() throws SQLException {
       DataSource ds = new DataSource();
       ds.setURL(jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;);
       ds.setAuthType(3);  // Application Default Credentials
       ds.setProjectId("MyTestProject");
       ds.setEnableHighThroughputAPI(true);
       ds.setLogLevel("6");
       ds.setUseQueryCache(false);
       return ds.getConnection();
     }

Propriétés de connexion

Les propriétés de connexion du pilote JDBC sont des paramètres de configuration que vous incluez dans la chaîne de connexion ou que vous transmettez via des méthodes setter lorsque vous établissez une connexion à une base de données. Les propriétés de connexion suivantes sont compatibles avec le pilote JDBC pour BigQuery.

Exécuter des requêtes avec le pilote

Une fois votre application Java connectée à BigQuery via le pilote JDBC, vous pouvez exécuter des requêtes dans votre environnement de développement via le processus JDBC standard. Tous les quotas et limites BigQuery s'appliquent.

Mappage des types de données

Lorsque vous exécutez des requêtes via le pilote JDBC pour BigQuery, le mappage de types de données suivant se produit :

Exemples

Les sections suivantes fournissent des exemples d'utilisation des fonctionnalités BigQuery via le pilote JDBC pour BigQuery.

Paramètres positionnels

L'exemple suivant exécute une requête avec un paramètre positionnel :

PreparedStatement preparedStatement = connection.prepareStatement(
    "SELECT * FROM MyTestTable where testColumn = ?");
preparedStatement.setString(1, "string2");
ResultSet resultSet = statement.executeQuery(selectQuery);

Enregistrements imbriqués et répétés

L'exemple suivant interroge l'enregistrement de base des données Struct :

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct obj = (Struct) resultSet.getObject(1);
    System.out.println(obj.toString());

Le pilote renvoie l'enregistrement de base sous la forme d'un objet struct ou d'une représentation sous forme de chaîne d'un objet JSON. Le résultat ressemble à ce qui suit :

{
  "v": {
    "f": [
      {
        "v": "Adam"
      },
      {
        "v": "5"
      }
    ]
  }
}

L'exemple suivant interroge les sous-composants d'un objet Struct :

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct structObject = (Struct) resultSet.getObject(1);
    Object[] structComponents = structObject.getAttributes();
    for (Object component : structComponents){
      System.out.println(component.toString());
    }

L'exemple suivant interroge un tableau standard de données répétées, puis vérifie le résultat :

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT [1,2,3]");
resultSet.next();
Object[] arrayObject = (Object[]) resultSet.getArray(1).getArray();

// Verify Result
int count =0;
for (; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

L'exemple suivant interroge un tableau Struct de données répétées, puis vérifie le résultat :

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT "
    + "[STRUCT(\"Adam\" as name, 12 as age), "
    + "STRUCT(\"Lily\" as name, 17 as age)]");

Struct[] arrayObject = (Struct[]) resultSet.getArray(1).getArray();

// Verify Result
for (int count =0; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

Insertion groupée

L'exemple suivant effectue une opération d'insertion groupée avec la méthode executeBatch.

Connection conn = DriverManager.getConnection(connectionUrl);
PreparedStatement statement = null;
Statement st = conn.createStatement();
final String insertQuery = String.format(
        "INSERT INTO `%s.%s.%s` "
      + " (StringField, IntegerField, BooleanField) VALUES(?, ?, ?);",
        DEFAULT_CATALOG, DATASET, TABLE_NAME);

statement = conn.prepareStatement(insertQuery1);

for (int i=0; i<2000; ++i) {
      statement.setString(1, i+"StringField");
      statement.setInt(2, i);
      statement.setBoolean(3, true);
      statement.addBatch();
}

statement.executeBatch();

Journalisation

Pour résoudre les problèmes liés au pilote JDBC pour BigQuery, vous pouvez activer la journalisation en définissant des propriétés de connexion ou des variables d'environnement. La journalisation peut affecter les performances et occuper de l'espace disque. Ne l'activez donc que temporairement pour capturer un problème.

Niveaux de journalisation

La propriété LogLevel détermine le niveau de détail consigné par le package java.util.logging :

• 0 : OFF (par défaut)
• 1 : SEVERE
• 2 : WARNING
• 3 : INFO
• 4 : CONFIG
• 5 : FINE
• 6 : FINER
• 7 : FINEST
• 8 : ALL

Nous vous recommandons le niveau 6 pour le dépannage général. Les niveaux 7 et 8 sont limités aux opérations ResultSet et génèrent un volume important de journaux.

Activer la journalisation dans la chaîne de connexion

Pour activer la journalisation dans la chaîne de connexion, ajoutez les propriétés de connexion LogLevel et LogPath, par exemple :

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=MyTestProject;OAuthType=3;LogLevel=6;LogPath=/tmp/jdbc-logs;

Activer la journalisation avec des variables d'environnement

Si votre outil pour les développeurs ne permet pas de modifier la chaîne de connexion, vous pouvez également définir le niveau et le chemin d'accès des journaux à l'aide des variables d'environnement suivantes avant d'exécuter votre application :

• BIGQUERY_JDBC_LOG_LEVEL : niveau de journalisation (0-8).
• BIGQUERY_JDBC_LOG_PATH : répertoire des fichiers journaux.

Par exemple, dans un environnement Linux ou macOS, exécutez la commande suivante :

export BIGQUERY_JDBC_LOG_LEVEL=6
export BIGQUERY_JDBC_LOG_PATH=/tmp/jdbc-logs

OpenTelementry

Le pilote JDBC pour BigQuery est compatible avec OpenTelemetry (OTel) pour fournir un traçage et une journalisation distribués, ce qui vous permet de surveiller les performances de vos interactions avec la base de données et de résoudre efficacement les problèmes.

Opérations tracées

Lorsque OpenTelemetry est activé, le pilote génère des segments pour les opérations suivantes :

• Exécution de la requête : des segments sont générés pour BigQueryStatement (execute(), executeQuery(), executeLargeUpdate(), executeBatch()) et BigQueryPreparedStatement (execute(), executeQuery(), executeLargeUpdate()).
• Opérations de métadonnées : des segments sont générés pour des méthodes DatabaseMetaData spécifiques (getCatalogs(), getSchemas(), getTables(), getColumns()).
• Pagination : les récupérations asynchrones de pages de résultats supplémentaires (lors de l'utilisation du chemin d'accès de l'API REST) sont tracées et liées de manière causale à l'intervalle d'exécution de la requête d'origine à l'aide des liens d'intervalle OpenTelemetry. Un segment nommé BigQueryStatement.pagination est créé pour ces opérations.
• Propagation du contexte : le pilote JDBC propage le contexte actif au SDK google-cloud-bigquery sous-jacent. Par conséquent, les segments générés par le SDK (tels que les appels RPC HTTP) apparaissent automatiquement en tant qu'enfants des segments JDBC, ce qui fournit une hiérarchie de trace complète de bout en bout.

Modes de configuration

Vous pouvez configurer OpenTelemetry dans le pilote JDBC à l'aide de l'un des modes suivants, en fonction de l'architecture et des exigences de votre application.

Télémétrie gérée par l'application

Si votre application utilise déjà OpenTelemetry, vous pouvez injecter votre instance OpenTelemetry dans le pilote JDBC pour vous assurer que la télémétrie du pilote est corrélée à celle de votre application.

Pour ce faire, utilisez l'API BigQueryDataSource :

BigQueryDataSource dataSource = new BigQueryDataSource();
// ... set other properties ...
dataSource.setCustomOpenTelemetry(yourOpenTelemetryInstance);

Compatibilité globale avec OpenTelemetry

Si vous avez initialisé OpenTelemetry de manière globale dans votre application (par exemple, à l'aide de l'agent Java OpenTelemetry ou en appelant la fonction GlobalOpenTelemetry.set()), vous pouvez configurer le pilote pour qu'il utilise cette instance globale.

Pour activer l'instance globale, définissez la propriété de connexion UseGlobalOpenTelemetry sur TRUE.

Télémétrie Cloud de Confiance sans configuration

Si vous utilisez Cloud de Confiance et que vous souhaitez une configuration rapide, vous pouvez activer l'exportation automatique des traces et des journaux vers l'observabilité Cloud de Confiance (Trace et Logging).

Pour activer cette exportation, définissez les propriétés de connexion suivantes dans votre URL JDBC :

• EnableGcpTraceExporter=true
• EnableGcpLogExporter=true

Voici un exemple d'URL de connexion :

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=your-project-id;EnableGcpTraceExporter=true;EnableGcpLogExporter=true;

Propriétés de connexion OpenTelemetry

Les propriétés de connexion suivantes sont compatibles avec OpenTelemetry. Pour obtenir des descriptions détaillées et des valeurs par défaut, consultez Propriétés de connexion.

• EnableGcpLogExporter
• EnableGcpTraceExporter
• GcpTelemetryCredentials
• GcpTelemetryProjectId
• UseGlobalOpenTelemetry

Remarques importantes

Lorsque vous déployez l'intégration OpenTelemetry, tenez compte des points suivants concernant le comportement de journalisation, l'authentification, la configuration du proxy et la tarification.

Interaction avec LogLevel

La propriété de connexion LogLevel existante sert de contrôleur d'accès principal pour la journalisation.

• Si la valeur LogLevel=0 (OFF) est définie, aucun enregistrement de journal n'est généré. Par conséquent, aucun journal n'est exporté à l'aide d'OpenTelemetry ou vers Logging, même si EnableGcpLogExporter=true.
• Pour activer la journalisation OTel, assurez-vous que LogLevel est défini sur une valeur supérieure à 0 (par exemple, 5 pour des journaux détaillés).

Authentification pour la télémétrie

L'exportation de la télémétrie (traçage et journalisation) avec le remplacement automatiqueCloud de Confiance est compatible avec les Identifiants par défaut de l'application (ADC) et les identifiants de compte de service explicites fournis à l'aide de GcpTelemetryCredentials.

Lorsque GcpTelemetryProjectId ou GcpTelemetryCredentials sont fournis, les journaux et les traces sont envoyés au même projet de destination spécifié à l'aide des mêmes identifiants configurés.

Configuration du proxy avec OpenTelemetry et la journalisation

Si votre application se connecte à BigQuery via un serveur proxy, le pilote gère le routage du proxy comme suit :

• Exportation de traces (HTTP). Lorsque vous utilisez le protocole HTTP par défaut pour l'exportation de traces OpenTelemetry (otel.exporter.otlp.protocol=http/protobuf), le pilote achemine automatiquement le trafic d'exportation de traces via le proxy configuré dans les propriétés de connexion à l'aide de ProxyHost et ProxyPort.

• Exportation des journaux et télémétrie gRPC L'exportateur de journaux Cloud de Confiance automatique (EnableGcpLogExporter=true) et les exportateurs OpenTelemetry basés sur gRPC (otel.exporter.otlp.protocol=grpc) utilisent gRPC, qui n'est pas compatible avec la configuration de proxy par connexion. Pour acheminer le trafic d'exportation des journaux et de télémétrie gRPC via un serveur proxy, configurez les paramètres proxy au niveau de la JVM à l'aide des propriétés système suivantes :

  -Dhttps.proxyHost=PROXY_HOST -Dhttps.proxyPort=PROXY_PORT

API et autorisations IAM requises

Pour écrire des données de télémétrie dans l'observabilité Cloud de Confiance by S3NS , effectuez la configuration suivante dans votre projet Cloud de Confiance cible :

1. Activez les API :
   • Activez l'API Cloud Trace (cloudtrace.googleapis.com).
   • Activez l'API Cloud Logging (logging.googleapis.com).
2. Attribuez des rôles IAM :
   • Pour exporter des traces : attribuez au compte principal ou au compte de service le rôle d'agent Trace (roles/cloudtrace.agent).
   • Pour exporter des journaux : attribuez au compte principal ou au compte de service le rôle "Rédacteur de journaux" (roles/logging.logWriter).

Tarification et facturation

Lorsque vous utilisez la télémétrie sans configuration Cloud de Confiance (EnableGcpTraceExporter=true ou EnableGcpLogExporter=true), les données de télémétrie sont envoyées à Trace et Logging. Ces services peuvent entraîner des frais en fonction du volume de données ingérées. Pour en savoir plus, consultez Google Cloud Observability.

Métriques

Cette intégration n'est pas compatible avec les métriques OpenTelemetry.

Ombrage des dépendances

Pour éviter les conflits de chemin de classe avec votre application, le pilote masque les dépendances du SDK et de l'exportateur OpenTelemetry. L'API OpenTelemetry reste non masquée pour permettre l'interopérabilité avec le SDK fourni par votre application.

Mise en corrélation des journaux et des traces

Lorsque OpenTelemetry est activé, le pilote met automatiquement en corrélation les journaux avec les traces :

• db.connection_id : associé en tant qu'attribut de segment à tous les segments JDBC.
• jdbc.connection_id : utilisé comme clé de bagage et associé en tant qu'étiquette à toutes les entrées de journal émises par le pilote vers Logging.
• ID de trace et ID de segment : les journaux générés dans le cadre de l'exécution d'une requête incluent automatiquement les trace_id et span_id actifs.

Tarifs

Vous pouvez télécharger le pilote JDBC pour BigQuery sans frais. Toutefois, lorsque vous utilisez le pilote, les tarifs BigQuery standards s'appliquent.

Étapes suivantes

• Pour obtenir des instructions de configuration supplémentaires, des manuels de référence sur les propriétés d'URL de connexion, des exemples de code et des instructions de compilation locale, consultez le dépôt Open Source sur GitHub :
  • Guide de l'utilisateur (docs/USER_GUIDE.md)
  • Guide du développeur (DEVELOPMENT.md)
  • Présentation détaillée des API BigQuery Storage (docs/STORAGE_APIS.md)
• En savoir plus sur le pilote ODBC pour BigQuery.
• Découvrez d'autres outils pour les développeurs BigQuery.