Utiliser le pilote ODBC pour BigQuery

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Remarque : Le pilote ODBC pour BigQuery est disponible sous la licence Apache 2.0. Pour demander un commentaire ou une assistance pour cette fonctionnalité, envoyez un e-mail à l'adresse [e-mail].

Le pilote Open Database Connectivity (ODBC) pour BigQuery connecte vos applications à BigQuery. Vous pouvez ainsi utiliser les fonctionnalités de BigQuery avec les outils et l'infrastructure de votre choix.

Avant de commencer

1. Assurez-vous de bien connaître les pilotes ODBC (Open Database Connectivity) et le gestionnaire de pilotes.

2. Tenez compte de la configuration système requise suivante :

   Système d'exploitation	Architectures compatibles	Version minimale et dépendances
   Windows	32 bits (x86), 64 bits (x64)	Version : Windows 10, Windows Server 2016 ou version ultérieure Dépendance : Microsoft Visual C++ Redistributable pour Visual Studio 2019 ou 2022
   macOS	64 bits (x86_64), ARM64 (Apple Silicon)	Version : macOS 12 (Monterey) ou version ultérieure Dépendance : un gestionnaire de pilotes ODBC (par exemple, unixODBC). Assurez-vous d'ajouter le répertoire d'installation à votre DYLD_LIBRARY_PATH.
   Linux	64 bits (x86_64)	Version : toute distribution avec glibc 2.27 ou version ultérieure (par exemple, Ubuntu 20.04 LTS+, Debian 11+) Dépendance : un gestionnaire de pilotes ODBC (par exemple, unixODBC). Assurez-vous d'ajouter le répertoire d'installation à votre LD_LIBRARY_PATH.

3. Identifiez votre type de connexion pour le pilote ODBC pour BigQuery. Le pilote est compatible avec les méthodes d'authentification suivantes :

   Méthode d'authentification	Informations d'authentification	Exemple	Propriété de connexion (à définir ultérieurement)
   Compte de service standard	Clé de compte de service (objet JSON)	my-sa-key	KeyFilePath
   Fédération Workload Identity ou fédération des identités des employés	Propriété "audience" du fichier de configuration du compte externe	//iam.googleapis.com/locations/global/...	BYOID_AudienceUrl
   	Fichier d'informations sur l'environnement et récupération de jetons	{"file":"/path/to/file"}	BYOID_CredentialSource
   	Projet utilisateur (uniquement pour le pool d'employés)	my_project	BYOID_PoolUserProject
   	Type de jeton STS	id_token ou d'autres types de STS	BYOID_SubjectTokenType
   	Point de terminaison d'échange de jetons STS	URL de point de terminaison STS personnalisée	BYOID_TokenUrl
   Identifiants par défaut de l'application	N/A	N/A	N/A

Installer et configurer le pilote ODBC

Cette section explique comment installer et configurer le pilote ODBC pour les systèmes d'exploitation Windows et non Windows.

Windows

Sous Windows, assurez-vous d'installer l'architecture de pilote qui correspond à celle de votre application. Par exemple, utilisez le pilote 64 bits pour les applications 64 bits et le pilote 32 bits pour les applications 32 bits. Un système Windows 64 bits est compatible avec les applications 32 bits et 64 bits.

• Télécharger ODBCDriverforBigQuery_windows_x86.msi pour les applications 32 bits
• Télécharger ODBCDriverforBigQuery_windows_x64.msi pour les applications 64 bits

Créer un nom de source de données

Pour créer un nom de source de données dans Windows :

1. Dans le menu Démarrer, accédez à Sources de données ODBC, puis sélectionnez la version qui a la même architecture (32 bits ou 64 bits) que votre application cliente pour vous assurer de vous connecter correctement à BigQuery.
2. Dans l'administrateur de source de données ODBC, cliquez sur l'onglet Pilotes.
3. Recherchez le pilote ODBC pour BigQuery dans la liste alphabétique des pilotes ODBC installés.
4. Choisissez l'une des options suivantes :
   • Pour créer un DSN pour l'utilisateur actuel, cliquez sur l'onglet DSN utilisateur.
   • Pour créer un DSN pour tous les utilisateurs, cliquez sur l'onglet DSN système. Les DSN système sont recommandés, car certaines applications chargent les données à l'aide de différents comptes utilisateur et peuvent ne pas détecter les DSN utilisateur créés sous un autre compte utilisateur.
5. Cliquez sur Ajouter.
6. Dans la boîte de dialogue Créer une source de données, sélectionnez Pilote ODBC pour BigQuery, puis cliquez sur Terminer.
7. La boîte de dialogue Configuration du DSN du pilote ODBC pour BigQuery s'ouvre.
8. Dans le champ Nom de la source de données, saisissez le nom de votre DSN.
9. Consultez la section Propriétés de la connexion pour comprendre les valeurs à renseigner.

Non-Windows

Les distributions Linux 64 bits sont compatibles avec les applications 32 bits et 64 bits. Assurez-vous que l'architecture du pilote ODBC correspond à l'application que vous souhaitez utiliser. Par exemple, utilisez le pilote 64 bits pour les applications 64 bits et le pilote 32 bits pour les applications 32 bits. Vous pouvez installer les deux architectures de pilote simultanément sur un même système.

• Télécharger ODBCDriverforBigQuery_linux_latest.zip pour Linux
• Télécharger ODBCDriverforBigQuery_macos_latest.tar.gz pour macOS

Pour installer le connecteur à l'aide du package de fichier tar ou zip :

1. Créez le répertoire dans lequel vous souhaitez installer le connecteur, s'il n'existe pas déjà.
2. Extrayez le fichier ZIP principal vers un emplacement temporaire pratique.
3. Accédez au dossier du fichier tar ou zip extrait, puis (facultatif) copiez tous les fichiers et dossiers dans le répertoire d'installation.
4. Après l'extraction, le chemin d'accès à l'objet partagé du pilote ODBC pour BigQuery est [INSTALLDIR]/lib/libgoogle_cloud_odbc_bq_driver.so. Mettez à jour vos fichiers .ini pour refléter le chemin correct du connecteur.

unzip linux_odbc-driver.VERSION.zip -d linux_odbc-driver.VERSION/
cd ./linux_odbc-driver.VERSION
export INSTALL_DIR=$(pwd)
export ODBCINI=$INSTALL_DIR/odbc.ini
export ODBCINSTINI=$INSTALL_DIR/odbcinst.ini
export GOOGLEBIGQUERYODBCINI=$INSTALL_DIR/googlebigqueryodbc.ini

Établir une connexion

Pour établir une connexion à l'aide du pilote ODBC pour BigQuery, vous pouvez utiliser une chaîne de connexion ou un DSN.

Format de la chaîne de connexion

Driver=ODBC Driver for BigQuery;ProjectId=PROJECT_ID;OAuthMechanism=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

Remplacez les éléments suivants :

• 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 du compte de service
  • 3 : pour l'authentification avec les identifiants par défaut de l'application
  • 4 : pour l'authentification par fédération d'identité de charge de travail ou des employés
• AUTH_PROPS : informations d'authentification que vous avez notées lorsque vous vous êtes authentifié auprès de BigQuery.
• OTHER_PROPS (facultatif) : propriétés de connexion supplémentaires pour le pilote ODBC.

Propriétés de connexion

Les propriétés de connexion du pilote ODBC sont des paramètres de configuration que vous incluez dans la chaîne de connexion lorsque vous établissez une connexion à une base de données. Le pilote ODBC pour BigQuery est compatible avec les propriétés de connexion suivantes.

Remarque : Tous les noms de propriétés de connexion ne sont pas sensibles à la casse.

Propriété de connexion	Description	Valeur par défaut	Type de données	Obligatoire
AdditionalProjects	Projets auxquels le pilote peut accéder pour les requêtes et les opérations sur les métadonnées, en plus du projet principal défini par la propriété ProjectId.	N/A	Chaîne séparée par des virgules	Non
AllowHtapiForLargeResults	Détermine si le conducteur peut utiliser l'API Read.	0	Booléen	Non
AllowLargeResults	Indique si le pilote ODBC doit traiter les résultats de requête supérieurs à 128 Mo lorsque vous utilisez l'ancien SQL (QueryDialect=BIG_QUERY).	0	Booléen	Non
BYOID_AudienceUrl	L'audience contient le nom de ressource du pool d'identités de charge de travail ou du pool de travailleurs, ainsi que l'identifiant du fournisseur dans ce pool.	N/A	Chaîne	Uniquement lorsque OAuthMechanism=4
BYOID_CredentialSource	Définit les informations nécessaires pour récupérer le jeton lui-même, ainsi que certaines informations sur l'environnement.	N/A	Chaîne	Uniquement lorsque OAuthMechanism=4
BYOID_PoolUserProject	Définissez cette valeur lorsqu'il s'agit d'un pool de personnel et non d'un pool d'Workload Identity.	N/A	Chaîne	Uniquement lorsque OAuthMechanism=4 est utilisé et qu'un pool d'employés est utilisé
BYOID_SubjectTokenType	Définit le type de jeton STS en fonction de la spécification d'échange de jetons OAuth 2.0. Les valeurs attendues incluent : urn:ietf:params:oauth:token-type:jwt urn:ietf:params:oauth:token-type:id_token urn:ietf:params:oauth:token-type:saml2 urn:ietf:params:aws:token-type:aws4_request	N/A	Chaîne	Uniquement lorsque OAuthMechanism=4
BYOID_TokenUrl	Définit le point de terminaison d'échange de jetons STS.	https://sts.googleapis.com/v1/token	Chaîne	Non
DefaultDataset	Il s'agit d'un ensemble de données désigné dans un projet auquel le pilote fait automatiquement référence lorsque vous exécutez des requêtes sans spécifier explicitement un ensemble de données.	N/A	Chaîne	Non
FilterTablesOnDefaultDataset	Détermine le champ d'application des méthodes de métadonnées de table/colonne. Si la valeur est FALSE, aucun filtrage n'est effectué. Vous devez également définir la propriété DefaultDataset pour activer le filtrage.	FALSE	Booléen	Non
EnableSession	Détermine si une connexion démarre une session. Lorsqu'elle est activée, la première requête exécutée par cette connexion démarre une session, et le pilote transmet l'ID de session à toutes les requêtes suivantes.	0	Booléen	Non
JobCreationMode	Vous permet d'activer le chemin de requête à faible latence. Choisissez l'une des options suivantes : 1 : le pilote crée des jobs pour chaque requête (JOB_CREATION_REQUIRED). 2 : le pilote exécute les requêtes sans tâches (JOB_CREATION_OPTIONAL)	2	Integer	Non
KeyFilePath	Chemin d'accès à la clé du compte de service lors de l'utilisation de l'authentification par compte de service.	N/A	Chaîne	Uniquement lorsque OAuthMechanism=0
KMSKeyName	Vous permet de spécifier le nom de la clé KMS à utiliser pour chiffrer et déchiffrer les données.	N/A	Chaîne	Non
LargeResultsDataSetId	Vous permet de spécifier l'ensemble de données de destination pour stocker les résultats de requête volumineux.	N/A	Chaîne	Non
LargeResultsDatasetExpirationTime	Vous permet de spécifier la durée de vie de toutes les tables de l'ensemble de données de résultats volumineux, en millisecondes.	3600000	Long	Non
Location	Vous permet de spécifier l'emplacement où le pilote crée ou interroge les ensembles de données.	N/A	Chaîne	Non
LogLevel	Limite le niveau de détail des journaux du conducteur lors des interactions. Choisissez l'une des options suivantes : 0 : OFF 1 : ERROR 2 : WARNING 3 : INFO	0	Integer	Non
LogPath	Vous permet de spécifier le répertoire dans lequel le pilote écrit les fichiers journaux.	N/A	Chaîne	Non
LogFileCount	Vous permet de définir le nombre maximal de fichiers journaux à conserver.	0	Integer	Non
LogFileSize	Vous permet de définir la taille maximale de chaque fichier journal en octets.	0	Long	Non
MaxResults	Vous permet de spécifier le nombre de résultats par page dans les résultats de l'API BigQuery.	10000	Long	Non
MaxThreads	Définit le nombre maximal de threads que le connecteur peut utiliser pour le traitement simultané dans un pool de threads. Pour configurer cette propriété en tant que paramètre à l'échelle du connecteur pour les connecteurs non Windows (Linux/macOS), spécifiez-la dans le fichier googlebigqueryodbc.ini.	8	Integer	Non
OAuthMechanism	Type d'authentification. Choisissez l'une des options suivantes : 0 : authentification du compte de service 3 : authentification avec les identifiants par défaut de l'application 4 : authentification par fédération d'identité de charge de travail ou fédération des identités des employés	N/A	Integer	Oui
ProjectId	ID du projet par défaut pour le pilote. Le pilote utilise ce projet pour exécuter des requêtes et le facture pour l'utilisation des ressources.	N/A	Chaîne	Oui
ProxyHost	Nom d'hôte ou adresse IP d'un serveur proxy.	N/A	Chaîne	Non
ProxyPort	Numéro de port sur lequel le serveur proxy écoute.	N/A	Chaîne	Non
ProxyPwd	Mot de passe pour l'authentification lors de la connexion via un serveur proxy.	N/A	Chaîne	Non
ProxyUid	Nom d'utilisateur pour l'authentification lors de la connexion via un serveur proxy.	N/A	Chaîne	Non
PrivateServiceConnectUris	Points de terminaison personnalisés pour remplacer les points de terminaison par défaut. Exemples : BIGQUERY=https://bigquery.us-east4.rep.googleapis.com/ READ_API=bigquerystorage.us-east4.rep.googleapis.com OAUTH2=oauth2.us-east4.rep.googleapis.com	N/A	Chaîne séparée par des virgules	Non
QueryDialect	Spécifie le dialecte de requête à utiliser. Utilisez SQL pour GoogleSQL (fortement recommandé) et BIG_QUERY pour l'ancien SQL.	SQL	Chaîne	Non
QueryProperties	Configure les propriétés qui peuvent modifier le comportement de la requête.	N/A	Map<String, String>	Non
UniverseDomain	Spécifie le domaine de l'univers pour votre organisation.	googleapis.com	Chaîne	Non
UseQueryCache	Vous permet d'activer la fonctionnalité de mise en cache des requêtes dans BigQuery.	true	Booléen	Non

Exécuter des requêtes avec le pilote

Cette section fournit des informations sur le mappage des types de données et des exemples d'exécution de requêtes avec le pilote ODBC.

Mappage des types de données

Lorsque vous exécutez des requêtes via le pilote ODBC pour BigQuery, le mappage de type de données suivant se produit (en fonction des types SQL ODBC standards) :

Type GoogleSQL	Type SQL ODBC
INT64	SQL_BIGINT
BOOL	SQL_BIT
DATE	SQL_TYPE_DATE
FLOAT64	SQL_DOUBLE
TIME	SQL_TYPE_TIME
TIMESTAMP	SQL_TYPE_TIMESTAMP
DATETIME	SQL_TYPE_TIMESTAMP
BYTES	SQL_VARBINARY
STRING	SQL_VARCHAR
ARRAY	SQL_VARCHAR
STRUCT	SQL_VARCHAR
INTERVAL	SQL_VARCHAR
JSON	SQL_VARCHAR
GEOGRAPHY	SQL_VARCHAR
RANGE	SQL_VARCHAR
NUMERIC	SQL_NUMERIC
BIGNUMERIC	SQL_NUMERIC

Exemples

Les exemples suivants montrent comment utiliser des requêtes paramétrées et des scripts à plusieurs instructions avec le pilote ODBC.

Requêtes paramétrées

// 1. Prepare statement
std::string insert_stmt = "INSERT INTO MyTable VALUES (?, ?, ?)";
status = SQLPrepare(hstmt, (SQLCHAR*)insert_stmt.c_str(), SQL_NTS);

// 2. Bind parameters
std::string str_val = "example_string";
long long int_val = 12345;
double float_val = 1.2345;

// Bind string field
status = SQLBindParameter(
    hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR, 50, 0,
    (SQLPOINTER)str_val.c_str(), str_val.size(), NULL);

// Bind integer field
status = SQLBindParameter(
    hstmt, 2, SQL_PARAM_INPUT, SQL_C_UBIGINT, SQL_BIGINT, 0, 0,
    &int_val, 0, NULL);

// Bind float field
status = SQLBindParameter(
    hstmt, 3, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_DOUBLE, 0, 0,
    &float_val, 0, NULL);

// 3. Execute statement
status = SQLExecute(hstmt);

Scripts à plusieurs instructions

// 1. Prepare and execute the multi-statement script
std::string query =
    "CREATE OR REPLACE TABLE MyTable (StringField STRING, IntegerField INTEGER); "
    "INSERT INTO MyTable VALUES ('example', 123); "
    "SELECT * FROM MyTable;";

status = SQLExecDirect(hstmt, (SQLCHAR*)query.c_str(), SQL_NTS);

// 2. Process results for each statement using SQLMoreResults
do {
    SQLSMALLINT num_cols;
    status = SQLNumResultCols(hstmt, &num_cols);

    if (num_cols > 0) {
        // This is a result-returning statement (e.g., SELECT)
        while (SQLFetch(hstmt) == SQL_SUCCESS) {
            // Process rows...
        }
    } else {
        // This is a non-result statement (e.g., CREATE, INSERT)
        SQLLEN row_count;
        SQLRowCount(hstmt, &row_count);
        // Process affected rows...
    }
} while (SQLMoreResults(hstmt) == SQL_SUCCESS);

Tarifs

L'interrogation via le pilote ODBC pour BigQuery est soumise aux tarifs d'analyse standards de BigQuery.