Utilizzare il driver ODBC per BigQuery

Il driver Open Database Connectivity (ODBC) per BigQuery connette le tue applicazioni non Java a BigQuery, consentendoti di utilizzare le funzionalità di BigQuery con gli strumenti e l'infrastruttura che preferisci. Per connettere le applicazioni Java a BigQuery, utilizza il driver JDBC per BigQuery.

Il driver ODBC per BigQuery è disponibile con la licenza Apache 2.0.

Prima di iniziare

  1. Assicurati di avere familiarità con i driver ODBC e i gestori dei driver.

  2. Assicurati che il tuo sistema operativo soddisfi i seguenti requisiti:

    Sistema operativo Architetture supportate Versione minima e dipendenze
    Windows 32 bit (x86), 64 bit (x64) Versione: Windows 10, Windows Server 2016 o versioni successive

    Dipendenza: Microsoft Visual C++ Redistributable per Visual Studio 2019 o 2022
    macOS 64 bit (x86_64), ARM64 (Apple Silicon) Versione: macOS 12 (Monterey) o versioni successive

    Dipendenza: un gestore di driver ODBC (ad esempio unixODBC). Assicurati di aggiungere la directory di installazione a DYLD_LIBRARY_PATH.
    Linux 64 bit (x86_64) Versione: qualsiasi distribuzione con glibc 2.27 o versioni successive (ad esempio Ubuntu 20.04 LTS+, Debian 11+)

    Dipendenza: un gestore di driver ODBC (ad esempio unixODBC). Assicurati di aggiungere la directory di installazione a LD_LIBRARY_PATH.

  3. Autenticati in BigQuery e prendi nota delle seguenti informazioni, che verranno utilizzate in un secondo momento quando stabilirai una connessione con il driver ODBC per BigQuery. Devi annotare solo le informazioni corrispondenti al metodo di autenticazione che utilizzi.

    Metodo di autenticazione Informazioni di autenticazione Esempio Proprietà della connessione (da impostare in un secondo momento)
    Account di servizio standard Chiave del service account (oggetto JSON) my-sa-key.json KeyFilePath
    Simulazione dell'identità dei service account Indirizzo email del account di servizio di destinazione service-account@project.iam.gserviceaccount.com ServiceAccountImpersonationEmail, KeyFilePath
    Federazione delle identità per i workload o per la forza lavoro Proprietà Audience del file di configurazione dell'account esterno //iam.googleapis.com/locations/global/... BYOID_AudienceUrl
    File di recupero dei token e informazioni sull'ambiente {"file":"/path/to/file"} BYOID_CredentialSource
    Progetto utente (solo per il pool di forza lavoro) my_project BYOID_PoolUserProject
    Tipo di token STS id_token BYOID_SubjectTokenType
    Endpoint di scambio token STS https://sts.googleapis.com/v1/token BYOID_TokenUrl
    Credenziali predefinite dell'applicazione Nessuno N/D N/D

Installare e configurare il driver ODBC

Puoi installare e configurare il driver ODBC per BigQuery utilizzando un sistema operativo Windows o non Windows.

Windows

  1. Installa il driver corrispondente all'architettura della tua applicazione:

  2. Crea un nome origine dati (DSN) nel seguente modo:

    1. Dal menu Start di Windows, vai a Origini dati ODBC e seleziona la versione con la stessa bitness dell'applicazione client.
    2. Nella pagina Amministratore origini dati ODBC, fai clic sulla scheda Driver.
    3. Nell'elenco dei driver ODBC installati, individua ODBC Driver for BigQuery.
    4. Seleziona la scheda DSN di sistema per creare un DSN per tutti gli utenti o la scheda DSN utente per creare un DSN per l'utente corrente. I DSN di sistema sono generalmente consigliati perché alcune applicazioni caricano i dati utilizzando account utente diversi e potrebbero non rilevare altri DSN utente.
    5. Fai clic su Aggiungi.
    6. Nella finestra di dialogo Crea nuova origine dati, seleziona Driver ODBC per BigQuery, quindi fai clic su Fine. Si apre la finestra di dialogo Configurazione DSN del driver ODBC per BigQuery.
    7. Nel campo Nome origine dati, inserisci un nome per il DSN.
    8. Aggiungi le proprietà di connessione. Per un elenco completo delle proprietà, consulta Proprietà di connessione.

Non Windows

  1. Installa il driver corrispondente al tuo sistema operativo:

  2. Estrai i contenuti del file ZIP o TAR scaricato.

  3. Sposta i contenuti del file ZIP o TAR nella directory in cui vuoi installare il driver. Il percorso dell'oggetto condiviso del driver ODBC per BigQuery è INSTALL_DIR/lib/libgoogle_cloud_odbc_bq_driver.so, dove INSTALL_DIR è la directory di installazione.

  4. Aggiorna i file .ini in modo che riflettano il nuovo percorso del driver.

    Il seguente esempio aggiorna i file .ini in un sistema Linux:

    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

    Sostituisci VERSION con la versione del driver.

Stabilire una connessione

Per stabilire una connessione tra la tua applicazione e BigQuery con il driver ODBC per BigQuery, identifica la stringa di connessione. Puoi saltare questo passaggio se hai già configurato le proprietà di connessione tramite il DSN.

La stringa di connessione ha il seguente formato:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del tuo progetto BigQuery.
  • AUTH_TYPE: un numero che specifica il tipo di autenticazione che hai utilizzato. Seleziona una delle seguenti opzioni:
    • 0: per l'autenticazione del account di servizio
    • 3: per l'autenticazione delle credenziali predefinite dell'applicazione
    • 4: per l'autenticazione della federazione delle identità per i workload o della federazione delle identità della forza lavoro
  • AUTH_PROPS: le informazioni di autenticazione che hai annotato quando ti sei autenticato in BigQuery, elencate nel formato property_1=value_1; property_2=value_2;..., ad esempio, KeyFilePath=my-sa-key.json, se ti sei autenticato con un account di servizio.
  • OTHER_PROPS (facoltativo): proprietà di connessione aggiuntive per il driver ODBC, elencate nel formato property_1=value_1; property_2=value_2;.... Per un elenco completo delle proprietà di connessione, consulta Proprietà di connessione.

Proprietà di connessione

Le proprietà di connessione del driver ODBC sono parametri di configurazione che includi nella stringa di connessione quando stabilisci una connessione a un database. Il driver ODBC per BigQuery supporta le seguenti proprietà di connessione.

Proprietà della connessione Descrizione Valore predefinito Tipo di dati Obbligatorio
AdditionalProjects Progetti a cui il driver può accedere per query e operazioni sui metadati, oltre al progetto principale impostato dalla proprietà Catalog. N/D Stringa separata da virgole No
AllowHtapiForLargeResults Determina se il driver può utilizzare l'API BigQuery Storage di lettura. 0 Booleano No
AllowLargeResults Determina se il driver elabora i risultati delle query di dimensioni superiori a 128 MB quando la proprietà SQLDialect è impostata su 0 (SQL precedente). Se la proprietà SQLDialect è impostata su 1 (GoogleSQL), il driver elabora sempre i risultati di query di grandi dimensioni. 0 Booleano No
BYOID_AudienceUrl Contiene il nome della risorsa per il pool di identità del workload o il pool di forza lavoro e l'identificatore del provider in quel pool. N/D Stringa Solo quando OAuthMechanism=4
BYOID_CredentialSource Imposta le informazioni necessarie per recuperare il token stesso, nonché alcune informazioni ambientali. N/D Stringa Solo quando OAuthMechanism=4
BYOID_PoolUserProject Imposta il progetto quando si tratta di un pool della forza lavoro e non di un pool di Workload Identity. N/D Stringa Solo quando OAuthMechanism=4 e si utilizza un pool forza lavoro
BYOID_SubjectTokenType Imposta il tipo di token STS in base alla specifica di scambio di token OAuth 2.0. I valori previsti includono:
  • 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/D Stringa Solo quando OAuthMechanism=4
BYOID_TokenUrl Imposta l'endpoint di scambio dei token STS. https://sts.googleapis.com/v1/token Stringa No
Catalog L'ID progetto BigQuery predefinito per il driver. Il driver utilizza questo progetto per eseguire le query e lo fattura per l'utilizzo delle risorse. N/D Stringa Sì
DefaultDataset Funge da set di dati designato all'interno di un progetto a cui il driver fa riferimento automaticamente quando esegui query senza specificare esplicitamente un set di dati. N/D Stringa No
EnableSession Determina se una connessione avvia una sessione. Se abilitata, la prima query eseguita da quella particolare connessione avvia una sessione e il driver passa l'ID sessione a tutte le query successive. 0 Booleano No
FilterTablesOnDefaultDataset Determina l'ambito dei metadati restituiti dai metodi dei metadati di tabelle o colonne. Se è false (0), non viene applicato alcun filtro. Devi anche impostare la proprietà DefaultDataset per attivare il filtro. 0 Booleano No
IgnoreTransactions Quando è abilitato (1 o TRUE), il driver ignora la gestione manuale delle transazioni (BEGIN TRANSACTION, COMMIT, ROLLBACK) quando SQL_ATTR_AUTOCOMMIT è impostato su SQL_AUTOCOMMIT_OFF. Questa operazione è consigliata per strumenti client BI e SQL di terze parti (come Tableau, Power BI e DBeaver) che disabilitano l'autocommit per impostazione predefinita. 0 Booleano No
JobCreationMode Consente di attivare il percorso di query a bassa latenza. Scegli una delle seguenti opzioni:
  • 1: Il driver crea job per ogni query (JOB_CREATION_REQUIRED)
  • 2: Il driver esegue query senza job (JOB_CREATION_OPTIONAL)
 2 Numero intero No
KeyFilePath Il percorso del file JSON della chiave dell'account di servizio quando utilizzi l'autenticazione dell'account di servizio. N/D Stringa Solo quando OAuthMechanism=0
KMSKeyName Specifica il nome risorsa della chiave Cloud KMS da utilizzare per criptare e decriptare i dati. N/D Stringa No
LargeResultsDataSetId Specifica il set di dati di destinazione per l'archiviazione dei risultati di query di grandi dimensioni. N/D Stringa No
LargeResultsTempTableExpirationTime Specifica la durata delle tabelle temporanee in LargeResultsDataSetId, in millisecondi. 3600000 Lungo No
LogLevel Limita i dettagli registrati dal conducente durante le interazioni. Per saperne di più, consulta Configurazione di logging e driver. Scegli una delle seguenti opzioni:
  • 0: OFF
  • 1: ERROR
  • 2: WARNING
  • 3: INFO
 0 Numero intero No
LogPath Specifica la directory in cui il driver scrive i file di log. Per saperne di più, consulta Configurazione di logging e driver. N/D Stringa No
LogFileCount Specifica il numero massimo di file di log da conservare. 0 Numero intero No
LogFileSize Specifica la dimensione massima di ogni file di log in KB. 0 Lungo No
MaxRetries Configura il numero massimo di tentativi di ripetizione eseguiti dal driver con backoff esponenziale in caso di errori temporanei delle API BigQuery REST e gRPC (ad esempio limiti di frequenza o HTTP 5xx) prima di restituire un errore. 6 Numero intero No
MaxThreads Definisce il numero massimo di thread che il driver può utilizzare per l'elaborazione simultanea in un pool di thread. Per configurare questa proprietà come impostazione a livello di driver per ambienti non Windows, specificarla nel file googlebigqueryodbc.ini. 8 Numero intero No
OAuthMechanism Il tipo di autenticazione. Scegli una delle seguenti opzioni:
  • 0: autenticazione del service account
  • 3: Autenticazione delle credenziali predefinite dell'applicazione
  • 4: Autenticazione della federazione delle identità per i workload o della federazione delle identità della forza lavoro
 N/D Numero intero Sì
PrivateServiceConnectUris Endpoint personalizzati per sovrascrivere gli endpoint predefiniti. Esempi:
  • BIGQUERY=https://bigquery.us-east4.rep.googleapis.com/
  • READ_API=bigquerystorage.us-east4.rep.googleapis.com
  • OAUTH2=oauth2.us-east4.rep.googleapis.com
 N/D Stringa separata da virgole No
ProxyHost Nome host o indirizzo IP di un server proxy. N/D Stringa No
ProxyPort Numero di porta su cui il server proxy è in ascolto. N/D Stringa No
ProxyPwd Password per l'autenticazione durante la connessione tramite un server proxy. N/D Stringa No
ProxyUid Nome utente per l'autenticazione durante la connessione tramite un server proxy. N/D Stringa No
QueryProperties Configura le proprietà che possono modificare il comportamento della query. N/D Map<String, String> No
RefreshToken Token di aggiornamento OAuth memorizzato per i flussi di autenticazione utente. N/D Stringa No
RowsFetchedPerBlock Specifica il numero massimo di righe recuperate per blocco o pagina dei risultati da BigQuery. 100000 Lungo No
ServiceAccountImpersonationEmail Specifica un indirizzo email del account di servizio di destinazione da rappresentare utilizzando le credenziali di base del chiamante. Consente flussi di lavoro di delega multi-tenant e con privilegi minimi senza distribuire chiavi private aggiuntive del account di servizio. N/D Stringa No
SessionLocation Specifica la posizione geografica (regione o multiregione) in cui il driver crea o esegue query sui set di dati ed esegue sessioni di query (ad esempio, US, EU o us-central1). N/D Stringa No
SQLDialect Specifica quale dialetto della query utilizzare. Utilizza 1 per GoogleSQL (SQL standard, vivamente consigliato) e 0 per SQL precedente. 1 Numero intero No
TrustedCerts Specifica il percorso completo di un file di certificati CA radice SSL/TLS personalizzato in formato PEM (ad esempio roots.pem o cacerts.pem). Esegue l'override del file di certificati in bundle predefinito. N/D Stringa No
UniverseDomain Specifica il dominio dell'universo per la tua organizzazione. googleapis.com Stringa No
UseDefaultLargeResultsDataset Quando AllowLargeResults=1, determina se il driver instrada automaticamente i risultati di query di grandi dimensioni nel set di dati temporaneo predefinito (_bqodbc_temp_tables). Se è impostato su 0, LargeResultsDataSetId deve essere specificato in modo esplicito. 1 Booleano No
UseQueryCache Attiva la funzionalità di memorizzazione nella cache delle query in BigQuery. true Booleano No
UseSystemTrustStore Solo Windows. Indica al driver di caricare e convalidare i certificati TLS in base all'archivio di attendibilità dei certificati di Windows anziché cercare un file PEM locale. 0 Booleano No

Mappatura dei tipi di dati

Quando esegui query tramite il driver ODBC per BigQuery, viene eseguito il seguente mapping dei tipi di dati:

Tipo GoogleSQL Tipo SQL ODBC
INT64SQL_BIGINT
BOOLSQL_BIT
DATESQL_TYPE_DATE
FLOAT64SQL_DOUBLE
TIMESQL_TYPE_TIME
TIMESTAMPSQL_TYPE_TIMESTAMP
DATETIMESQL_TYPE_TIMESTAMP
BYTESSQL_VARBINARY
STRINGSQL_VARCHAR
ARRAYSQL_VARCHAR
STRUCTSQL_VARCHAR
INTERVALSQL_VARCHAR
JSONSQL_VARCHAR
GEOGRAPHYSQL_VARCHAR
RANGESQL_VARCHAR
NUMERICSQL_NUMERIC
BIGNUMERICSQL_NUMERIC

Configurazione di logging e driver

Per configurare le opzioni a livello di driver (come la registrazione e la codifica dei caratteri):

Windows

Configura le opzioni di logging e DSN utilizzando la finestra di dialogo di configurazione DSN in ODBC Data Source Administrator.

Non Windows

  1. Crea o modifica un file di configurazione, ad esempio googlebigqueryodbc.ini, e aggiungi le opzioni del driver nella sezione [Driver]. Di seguito è riportato un esempio:

    [Driver]
LogLevel=3
LogPath=/path/to/log/directory
LogFileCount=200
LogFileSize=1000
MaxThreads=8
WcharEncoding=UTF-16LE

  2. Imposta la variabile di ambiente GOOGLEBIGQUERYODBCINI sul percorso di questo file:

    export GOOGLEBIGQUERYODBCINI=/path/to/googlebigqueryodbc.ini

Livelli di logging del driver

Il driver supporta i livelli di logging da 0 a 3. Ti consigliamo di iniziare con LogLevel=3 (INFO) per la risoluzione dei problemi.

Livello di logging ODBC Descrizione
0 (OFF) Disattiva tutta la registrazione.
1 (ERRORE) Registra gli eventi di errore.
2 (AVVISO) Registra gli eventi di avviso.
3 (INFO) Registra informazioni generali che descrivono l'avanzamento del conducente.

Proprietà di configurazione a livello di driver (non Windows)

Le seguenti proprietà possono essere configurate nella sezione [Driver] di googlebigqueryodbc.ini:

Proprietà Descrizione Valori consentiti Valore predefinito
WcharEncoding Controlla esplicitamente la codifica wire dei buffer di caratteri SQLWCHAR quando si passano stringhe di caratteri estesi tra il driver e il gestore di driver ODBC (ad esempio, WcharEncoding=UTF-16LE). In questo modo si risolvono i problemi di danneggiamento e troncamento dei caratteri in unixODBC (in genere UTF-16LE a 2 byte) e iODBC (in genere UTF-32LE a 4 byte). UTF-8, UTF-16LE, UTF-32LE Vuoto (rilevamento automatico in base a sizeof(SQLWCHAR))
MaxThreads Definisce il numero massimo di thread che il driver può utilizzare per l'elaborazione simultanea in un pool di thread. Intero positivo 8

Esempi

Gli esempi seguenti mostrano come utilizzare le query con parametri e gli script con più istruzioni con il driver ODBC.

Query con parametri

// 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);

Script con più istruzioni

// 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);

Prezzi

Puoi scaricare il driver ODBC per BigQuery senza costi. Tuttavia, quando utilizzi il driver, si applicano i prezzi standard dell'analisi BigQuery.

Passaggi successivi