Utilizzare il driver ODBC per BigQuery

Il driver Open Database Connectivity (ODBC) per BigQuery connette le tue applicazioni a BigQuery. In questo modo puoi utilizzare le funzionalità di BigQuery con gli strumenti e l'infrastruttura che preferisci.

Prima di iniziare

  1. Assicurati di avere familiarità con i driver Open Database Connectivity (ODBC) e con il gestore dei driver.

  2. Tieni presente i seguenti requisiti di sistema:

    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. Identifica il tipo di connessione per il driver ODBC per BigQuery. Il driver supporta i seguenti metodi di autenticazione:

    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 KeyFilePath
    Federazione Workload Identity o federazione delle identità per la forza lavoro Proprietà Segmento di pubblico 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 o altri tipi di STS BYOID_SubjectTokenType
    Endpoint di scambio di token STS URL endpoint STS personalizzato BYOID_TokenUrl
    Credenziali predefinite dell'applicazione N/D N/D N/D

Installa e configura il driver ODBC

Questa sezione descrive come installare e configurare il driver ODBC per Windows e per i sistemi operativi non Windows.

Windows

Su Windows, assicurati di installare l'architettura del driver che corrisponde a quella della tua applicazione. Ad esempio, utilizza il driver a 64 bit per le applicazioni a 64 bit e il driver a 32 bit per le applicazioni a 32 bit. Un sistema Windows a 64 bit supporta applicazioni a 32 bit e a 64 bit.

Crea un nome origine dati

Per creare un nome origine dati in Windows:

  1. Nel menu Start, vai a ODBC Data Sources e seleziona la versione con la stessa bitness dell'applicazione client per garantire la corretta connessione a BigQuery.
  2. In Amministratore origini dati ODBC, fai clic sulla scheda Driver.
  3. Individua ODBC Driver for BigQuery (Driver ODBC per BigQuery) nell'elenco alfabetico dei driver ODBC installati.
  4. Scegli una delle seguenti opzioni:
    • Per creare un DSN per l'utente corrente, fai clic sulla scheda DSN utente.
    • Per creare un DSN per tutti gli utenti, fai clic sulla scheda DSN di sistema. I DSN di sistema sono consigliati perché alcune applicazioni caricano i dati utilizzando account utente diversi e potrebbero non rilevare i DSN utente creati in un altro account utente.
  5. Fai clic su Aggiungi.
  6. Nella finestra di dialogo Crea nuova origine dati, seleziona Driver ODBC per BigQuery e poi fai clic su Fine.
  7. Si apre la finestra di dialogo Configurazione DSN del driver ODBC per BigQuery.
  8. Nel campo Nome origine dati, digita un nome per il DSN.
  9. Consulta la sezione Proprietà di connessione per capire quali valori compilare.

Non Windows

Le distribuzioni Linux a 64 bit supportano applicazioni a 32 bit e a 64 bit. Assicurati che l'architettura del driver ODBC corrisponda all'applicazione che intendi utilizzare. Ad esempio, utilizza il driver a 64 bit per le applicazioni a 64 bit e il driver a 32 bit per le applicazioni a 32 bit. Puoi installare entrambe le architetture dei driver contemporaneamente su un singolo sistema.

Per installare il connettore utilizzando il pacchetto di file tar o zip:

  1. Crea la directory in cui vuoi installare il connettore, se non esiste già.
  2. Estrai il file ZIP principale in una posizione temporanea comoda.
  3. Vai alla cartella del file tar o zip estratto e poi (facoltativamente) copia tutti i file e le cartelle nella directory di installazione.
  4. Dopo l'estrazione, il percorso dell'oggetto condiviso del driver ODBC per BigQuery è [INSTALLDIR]/lib/libgoogle_cloud_odbc_bq_driver.so. Aggiorna i file .ini in modo che riflettano il percorso corretto del connettore.
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

Stabilire una connessione

Per stabilire una connessione utilizzando il driver ODBC per BigQuery, puoi utilizzare una stringa di connessione o un DSN.

Formato stringa di connessione

Driver=ODBC Driver for BigQuery;ProjectId=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. Scegli 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 forza lavoro
  • AUTH_PROPS: le informazioni di autenticazione che hai annotato quando ti sei autenticato in BigQuery.
  • OTHER_PROPS (facoltativo): proprietà di connessione aggiuntive per il driver ODBC.

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à ProjectId. N/D Stringa separata da virgole No
AllowHtapiForLargeResults Determina se il driver può utilizzare l'API Read. 0 Booleano No
AllowLargeResults Specifica se il driver ODBC deve elaborare i risultati delle query superiori a 128 MB quando si utilizza SQL precedente (QueryDialect=BIG_QUERY). 0 Booleano No
BYOID_AudienceUrl Il pubblico 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 questo valore 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 di 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
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
FilterTablesOnDefaultDataset Determina l'ambito dei metadati restituiti dai metodi dei metadati di tabella/colonna. Se FALSE, non viene applicato alcun filtro. Devi anche impostare la proprietà DefaultDataset per abilitare il filtro. FALSE Booleano 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
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 della chiave del account di servizio quando si utilizza l'autenticazione delaccount di serviziot. N/D Stringa Solo quando OAuthMechanism=0
KMSKeyName Consente di specificare il nome della chiave KMS da utilizzare per criptare e decriptare i dati. N/D Stringa No
LargeResultsDataSetId Consente di specificare il set di dati di destinazione per l'archiviazione dei risultati di query di grandi dimensioni. N/D Stringa No
LargeResultsDatasetExpirationTime Consente di specificare la durata di tutte le tabelle nel set di dati dei risultati di grandi dimensioni, in millisecondi. 3600000 Lungo No
Location Consente di specificare la località in cui il driver crea o esegue query sui set di dati. N/D Stringa No
LogLevel Limita i dettagli registrati dal conducente durante le interazioni. Scegli una delle seguenti opzioni:
  • 0: OFF
  • 1: ERROR
  • 2: WARNING
  • 3: INFO
 0 Numero intero No
LogPath Consente di specificare la directory in cui il driver scrive i file di log. N/D Stringa No
LogFileCount Consente di impostare il numero massimo di file di log da conservare. 0 Numero intero No
LogFileSize Consente di impostare la dimensione massima di ogni file di log in byte. 0 Lungo No
MaxResults Consente di specificare il numero di risultati per pagina nel risultato dell'API BigQuery. 10000 Lungo No
MaxThreads Definisce il numero massimo di thread che il connettore può utilizzare per l'elaborazione simultanea in un pool di thread. Per configurare questa proprietà come impostazione a livello di connettore per i connettori non Windows (Linux/macOS), devi specificarla nel file googlebigqueryodbc.ini. 8 Numero intero No
OAuthMechanism Il tipo di autenticazione. Scegli una delle seguenti opzioni:
  • 0: autenticazione del account di servizio
  • 3: Autenticazione delle credenziali predefinite dell'applicazione
  • 4: Autenticazione della federazione delle identità del workload o della forza lavoro
 N/D Numero intero Sì
ProjectId L'ID progetto predefinito per l'autista. Il driver utilizza questo progetto per eseguire query e lo fattura per l'utilizzo delle risorse. N/D Stringa Sì
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
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
QueryDialect Specifica quale dialetto della query utilizzare. Utilizza SQL per GoogleSQL (opzione altamente consigliata) e BIG_QUERY per SQL precedente. SQL Stringa No
QueryProperties Configura le proprietà che possono modificare il comportamento della query. N/D Map<String, String> No
UniverseDomain Specifica il dominio dell'universo per la tua organizzazione. googleapis.com Stringa No
UseQueryCache Consente di attivare la funzionalità di memorizzazione nella cache delle query in BigQuery. true Booleano No

Eseguire query con il driver

Questa sezione fornisce informazioni sul mapping dei tipi di dati ed esempi per l'esecuzione di query con il driver ODBC.

Mappatura dei tipi di dati

Quando esegui query tramite il driver ODBC per BigQuery, si verifica il seguente mapping dei tipi di dati (in base ai tipi SQL ODBC standard):

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

Esempi

Gli esempi seguenti mostrano come utilizzare query con parametri e 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

L'esecuzione di query tramite il driver ODBC per BigQuery è soggetta ai prezzi dell'analisi standard di BigQuery.