ODBC-Treiber für BigQuery verwenden

Der ODBC-Treiber (Open Database Connectivity) für BigQuery verbindet Ihre Nicht-Java-Anwendungen mit BigQuery. So können Sie BigQuery-Funktionen mit Ihren bevorzugten Tools und Ihrer bevorzugten Infrastruktur nutzen. Verwenden Sie den JDBC-Treiber für BigQuery, um Java-Anwendungen mit BigQuery zu verbinden.

Der ODBC-Treiber für BigQuery ist unter der Apache 2.0-Lizenz verfügbar.

Hinweis

  1. Machen Sie sich mit ODBC-Treibern und Treibermanagern vertraut.

  2. Ihr Betriebssystem muss die folgenden Anforderungen erfüllen:

    Betriebssystem Unterstützte Architekturen Mindestversion und Abhängigkeiten
    Windows 32-Bit (x86), 64-Bit (x64) Version: Windows 10, Windows Server 2016 oder höher

    Abhängigkeit: Microsoft Visual C++ Redistributable für Visual Studio 2019 oder 2022
    macOS 64-Bit (x86_64), ARM64 (Apple Silicon) Version: macOS 12 (Monterey) oder höher

    Abhängigkeit: Ein ODBC-Treibermanager (z. B. unixODBC). Fügen Sie das Installationsverzeichnis zu DYLD_LIBRARY_PATH hinzu.
    Linux 64-Bit (x86_64) Version: Beliebige Distribution mit glibc 2.27 oder höher (z. B. Ubuntu 20.04 LTS+, Debian 11+)

    Abhängigkeit: Ein ODBC-Treibermanager (z. B. unixODBC). Achten Sie darauf, dass Sie das Installationsverzeichnis zu Ihrer LD_LIBRARY_PATH hinzufügen.

  3. Authentifizieren Sie sich bei BigQuery und notieren Sie sich die folgenden Informationen, die später verwendet werden, wenn Sie eine Verbindung mit dem ODBC-Treiber für BigQuery herstellen. Sie müssen nur die Informationen beachten, die der von Ihnen verwendeten Authentifizierungsmethode entsprechen.

    Authentifizierungsmethode Authentifizierungsinformationen Beispiel Verbindungsproperty (wird später festgelegt)
    Standarddienstkonto Dienstkontoschlüssel (JSON-Objekt) my-sa-key.json KeyFilePath
    Identitätsübernahme des Dienstkontos E-Mail-Adresse des Zieldienstkontos service-account@project.iam.gserviceaccount.com ServiceAccountImpersonationEmail, KeyFilePath
    Workload Identity-Föderation oder Workforce Identity-Föderation Zielgruppen-Property der Konfigurationsdatei für das externe Konto //iam.googleapis.com/locations/global/... BYOID_AudienceUrl
    Abrufen von Tokens und Datei mit Umgebungsinformationen {"file":"/path/to/file"} BYOID_CredentialSource
    Nutzerprojekt (nur für Personalpool) my_project BYOID_PoolUserProject
    STS-Tokentyp id_token BYOID_SubjectTokenType
    STS-Tokenaustausch-Endpunkt https://sts.googleapis.com/v1/token BYOID_TokenUrl
    Standardanmeldedaten für Anwendungen Keine – –

ODBC-Treiber installieren und konfigurieren

Sie können den ODBC-Treiber für BigQuery unter Windows oder einem anderen Betriebssystem installieren und konfigurieren.

Windows

  1. Installieren Sie den Treiber, der der Architektur Ihrer Anwendung entspricht:

  2. So erstellen Sie einen Datenquellennamen (Data Source Name, DSN):

    1. Rufen Sie im Windows-Startmenü die ODBC-Datenquellen auf und wählen Sie die Version aus, die dieselbe Bitanzahl wie Ihre Clientanwendung hat.
    2. Klicken Sie auf der Seite ODBC Data Source Administrator (ODBC-Datenquellenadministrator) auf den Tab Drivers (Treiber).
    3. Suchen Sie in der Liste der installierten ODBC-Treiber nach ODBC Driver for BigQuery.
    4. Wählen Sie entweder den Tab System-DSN aus, um einen DSN für alle Nutzer zu erstellen, oder den Tab Nutzer-DSN, um einen DSN für den aktuellen Nutzer zu erstellen. System-DSNs werden im Allgemeinen empfohlen, da einige Anwendungen Daten mit verschiedenen Nutzerkonten laden und möglicherweise keine anderen Nutzer-DSNs erkennen.
    5. Klicken Sie auf Hinzufügen.
    6. Wählen Sie im Dialogfeld Neue Datenquelle erstellen die Option ODBC Driver for BigQuery aus und klicken Sie dann auf Fertigstellen. Das Dialogfeld ODBC Driver for BigQuery DSN Setup (ODBC-Treiber für BigQuery – DSN-Einrichtung) wird geöffnet.
    7. Geben Sie im Feld Name der Datenquelle einen Namen für den DSN ein.
    8. Verbindungseigenschaften hinzufügen Eine vollständige Liste der Attribute finden Sie unter Verbindungseigenschaften.

Nicht-Windows

  1. Installieren Sie den Treiber, der Ihrem Betriebssystem entspricht:

  2. Extrahieren Sie den Inhalt der heruntergeladenen ZIP- oder TAR-Datei.

  3. Verschieben Sie den Inhalt der ZIP- oder TAR-Datei in das Verzeichnis, in dem Sie den Treiber installieren möchten. Der freigegebene Objektpfad des ODBC-Treibers für BigQuery ist INSTALL_DIR/lib/libgoogle_cloud_odbc_bq_driver.so, wobei INSTALL_DIR Ihr Installationsverzeichnis ist.

  4. Aktualisieren Sie Ihre .ini-Dateien, um den neuen Pfad des Treibers zu berücksichtigen.

    Im folgenden Beispiel werden die .ini-Dateien in einem Linux-System aktualisiert:

    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

    Ersetzen Sie VERSION durch die Treiberversion.

Verbindung herstellen

Um eine Verbindung zwischen Ihrer Anwendung und BigQuery mit dem ODBC-Treiber für BigQuery herzustellen, müssen Sie den Verbindungsstring ermitteln. Sie können diesen Schritt überspringen, wenn Sie die Verbindungseigenschaften bereits über Ihren DSN konfiguriert haben.

Der Verbindungsstring hat das folgende Format:

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: die ID Ihres BigQuery-Projekts.
  • AUTH_TYPE: Eine Zahl, die den von Ihnen verwendeten Authentifizierungstyp angibt. Wählen Sie eine der folgenden Optionen aus:
    • 0: für die Dienstkonto-Authentifizierung
    • 3: für die Authentifizierung mit Standardanmeldedaten für Anwendungen
    • 4: für die Authentifizierung mit Workload Identity-Föderation oder Workforce Identity-Föderation
  • AUTH_PROPS: die Authentifizierungsinformationen, die Sie sich bei der Authentifizierung bei BigQuery notiert haben, im Format property_1=value_1; property_2=value_2;..., z. B. KeyFilePath=my-sa-key.json, wenn Sie sich mit einem Dienstkonto authentifiziert haben.
  • OTHER_PROPS (optional): zusätzliche Verbindungseigenschaften für den ODBC-Treiber im Format property_1=value_1; property_2=value_2;.... Eine vollständige Liste der Verbindungseigenschaften finden Sie unter Verbindungseigenschaften.

Verbindungsattribute

ODBC-Treiberverbindungseigenschaften sind Konfigurationsparameter, die Sie in den Verbindungsstring einfügen, wenn Sie eine Verbindung zu einer Datenbank herstellen. Der ODBC-Treiber für BigQuery unterstützt die folgenden Verbindungseigenschaften.

Verbindungseigenschaft Beschreibung Standardwert Datentyp Erforderlich
AdditionalProjects Projekte, auf die der Treiber für Abfragen und Metadatenvorgänge zugreifen kann, zusätzlich zum primären Projekt, das durch die Catalog-Property festgelegt wird. – Kommagetrennter String Nein
AllowHtapiForLargeResults Gibt an, ob der Treiber die BigQuery Storage Read API verwenden kann. 0 Boolesch Nein
AllowLargeResults Legt fest, ob der Treiber Abfrageergebnisse verarbeitet, die größer als 128 MB sind, wenn die Eigenschaft SQLDialect auf 0 (Legacy-SQL) festgelegt ist. Wenn die Eigenschaft SQLDialect auf 1 (GoogleSQL) festgelegt ist, verarbeitet der Treiber immer große Abfrageergebnisse. 0 Boolesch Nein
BYOID_AudienceUrl Enthält den Ressourcennamen für den Workload Identity-Pool oder den Personalpool und die Anbieter-ID in diesem Pool. – String Nur, wenn OAuthMechanism=4
BYOID_CredentialSource Legt die erforderlichen Informationen zum Abrufen des Tokens selbst sowie einige Umgebungsinformationen fest. – String Nur, wenn OAuthMechanism=4
BYOID_PoolUserProject Legen Sie das Projekt fest, wenn es sich um einen Personalpool und nicht um einen Workload Identity-Pool handelt. – String Nur bei OAuthMechanism=4 und Verwendung eines Personalpools
BYOID_SubjectTokenType Legt den STS-Tokentyp basierend auf der Spezifikation für den OAuth 2.0-Tokenaustausch fest. Mögliche Werte:
  • 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
 – String Nur, wenn OAuthMechanism=4
BYOID_TokenUrl Legt den STS-Tokenaustausch-Endpunkt fest. https://sts.googleapis.com/v1/token String Nein
Catalog Die Standard-BigQuery-Projekt-ID für den Treiber. Der Treiber verwendet dieses Projekt zum Ausführen von Abfragen und stellt die Ressourcennutzung in Rechnung. – String Ja
DefaultDataset Dient als festgelegtes Dataset in einem Projekt, auf das der Treiber automatisch verweist, wenn Sie Abfragen ausführen, ohne ein Dataset explizit anzugeben. – String Nein
EnableSession Legt fest, ob durch eine Verbindung eine Sitzung gestartet wird. Wenn diese Option aktiviert ist, wird mit der ersten Abfrage, die über diese Verbindung ausgeführt wird, eine Sitzung gestartet. Der Treiber übergibt die Sitzungs-ID an alle nachfolgenden Abfragen. 0 Boolesch Nein
FilterTablesOnDefaultDataset Bestimmt den Umfang der Metadaten, die von den Methoden für Tabellen- oder Spaltenmetadaten zurückgegeben werden. Wenn „false“ (0) festgelegt ist, findet keine Filterung statt. Sie müssen auch das Attribut DefaultDataset festlegen, um die Filterung zu aktivieren. 0 Boolesch Nein
IgnoreTransactions Wenn aktiviert (1 oder TRUE), umgeht der Treiber die manuelle Transaktionsverarbeitung (BEGIN TRANSACTION, COMMIT, ROLLBACK), wenn SQL_ATTR_AUTOCOMMIT auf SQL_AUTOCOMMIT_OFF gesetzt ist. Dies wird für BI- und SQL-Client-Tools von Drittanbietern (z. B. Tableau, Power BI und DBeaver) empfohlen, bei denen „Autocommit“ standardmäßig deaktiviert ist. 0 Boolesch Nein
JobCreationMode Ermöglicht es Ihnen, den Abfragepfad mit geringer Latenz zu aktivieren. Wählen Sie eine der folgenden Optionen aus:
  • 1: Der Treiber erstellt für jede Anfrage Jobs (JOB_CREATION_REQUIRED).
  • 2: Der Treiber führt Abfragen ohne Jobs aus (JOB_CREATION_OPTIONAL)
 2 Ganzzahl Nein
KeyFilePath Der Pfad zur JSON-Datei des Dienstkontoschlüssels, wenn die Dienstkontoauthentifizierung verwendet wird. – String Nur, wenn OAuthMechanism=0
KMSKeyName Gibt den Cloud KMS-Schlüsselressourcennamen an, der zum Verschlüsseln und Entschlüsseln von Daten verwendet werden soll. – String Nein
LargeResultsDataSetId Gibt das Ziel-Dataset zum Speichern umfangreicher Abfrageergebnisse an. – String Nein
LargeResultsTempTableExpirationTime Gibt die Lebensdauer temporärer Tabellen in LargeResultsDataSetId in Millisekunden an. 3600000 Lang Nein
LogLevel Beschränkt die Detailtiefe, die der Treiber bei Interaktionen protokolliert. Weitere Informationen finden Sie unter Logging und Treiberkonfiguration. Wählen Sie eine der folgenden Optionen aus:
  • 0: OFF
  • 1: ERROR
  • 2: WARNING
  • 3: INFO
 0 Ganzzahl Nein
LogPath Gibt das Verzeichnis an, in das der Treiber Logdateien schreibt. Weitere Informationen finden Sie unter Logging und Treiberkonfiguration. – String Nein
LogFileCount Gibt die maximale Anzahl der aufzubewahrenden Logdateien an. 0 Ganzzahl Nein
LogFileSize Gibt die maximale Größe jeder Logdatei in KB an. 0 Lang Nein
MaxRetries Konfiguriert die maximale Anzahl von Wiederholungsversuchen, die vom Treiber mit exponentiellem Backoff ausgeführt werden, wenn vorübergehende BigQuery REST- und gRPC API-Fehler (z. B. Ratenlimits oder HTTP 5xx) auftreten, bevor ein Fehler zurückgegeben wird. 6 Ganzzahl Nein
MaxThreads Definiert die maximale Anzahl von Threads, die der Treiber für die gleichzeitige Verarbeitung in einem Threadpool verwenden kann. Wenn Sie dieses Attribut als treiberweite Einstellung für Nicht-Windows-Umgebungen konfigurieren möchten, geben Sie es in der Datei googlebigqueryodbc.ini an. 8 Ganzzahl Nein
OAuthMechanism Der Authentifizierungstyp. Wählen Sie eine der folgenden Optionen aus:
  • 0: Dienstkonto-Authentifizierung
  • 3: Authentifizierung mit Standardanmeldedaten für Anwendungen
  • 4: Workload Identity-Föderation oder Mitarbeiteridentitätsföderation
 – Ganzzahl Ja
PrivateServiceConnectUris Benutzerdefinierte Endpunkte zum Überschreiben von Standardendpunkten. Beispiele:
  • BIGQUERY=https://bigquery.us-east4.rep.googleapis.com/
  • READ_API=bigquerystorage.us-east4.rep.googleapis.com
  • OAUTH2=oauth2.us-east4.rep.googleapis.com
 – Kommagetrennter String Nein
ProxyHost Hostname oder IP-Adresse eines Proxyservers. – String Nein
ProxyPort Portnummer, die der Proxyserver überwacht. – String Nein
ProxyPwd Passwort für die Authentifizierung bei der Verbindung über einen Proxyserver. – String Nein
ProxyUid Nutzername für die Authentifizierung bei der Verbindung über einen Proxyserver. – String Nein
QueryProperties Konfiguriert Attribute, die das Abfrageverhalten ändern können. – Map<String, String> Nein
RefreshToken OAuth-Aktualisierungstoken, das für Nutzerauthentifizierungsabläufe gespeichert wird. – String Nein
RowsFetchedPerBlock Gibt die maximale Anzahl der Zeilen an, die pro Block oder Ergebnisseite aus BigQuery abgerufen werden. 100000 Lang Nein
ServiceAccountImpersonationEmail Gibt eine E-Mail-Adresse für das Zieldienstkonto an, dessen Identität mit den Anmeldedaten des Aufrufers angenommen werden soll. Ermöglicht Workflows für die Mandantenfähigkeit und die Delegation mit dem Prinzip der geringsten Berechtigung, ohne dass zusätzliche private Schlüssel für Dienstkonten verteilt werden müssen. – String Nein
SessionLocation Gibt den geografischen Standort (Region oder Multiregion) an, an dem der Treiber Datasets erstellt oder abfragt und Abfragesitzungen ausführt (z. B. US, EU oder us-central1). – String Nein
SQLDialect Gibt an, welcher Abfragedialekt verwendet werden soll. Verwenden Sie 1 für GoogleSQL (Standard-SQL, sehr empfehlenswert) und 0 für Legacy-SQL. 1 Ganzzahl Nein
TrustedCerts Gibt den vollständigen Pfad zu einer benutzerdefinierten PEM-formatierten SSL/TLS-Stamm-CA-Zertifikatsdatei an (z. B. roots.pem oder cacerts.pem). Überschreibt die standardmäßige gebündelte Zertifikatsdatei. – String Nein
UniverseDomain Gibt die Universe-Domain für Ihre Organisation an. googleapis.com String Nein
UseDefaultLargeResultsDataset Wenn AllowLargeResults=1, wird festgelegt, ob der Treiber große Abfrageergebnisse automatisch in das temporäre Standard-Dataset (_bqodbc_temp_tables) weiterleitet. Wenn 0 festgelegt ist, muss LargeResultsDataSetId explizit angegeben werden. 1 Boolesch Nein
UseQueryCache Aktiviert die Funktion für das Zwischenspeichern von Abfragen in BigQuery. true Boolesch Nein
UseSystemTrustStore Nur Windows. Weist den Treiber an, TLS-Zertifikate aus dem Windows Certificate Trust Store zu laden und zu validieren, anstatt nach einer lokalen PEM-Datei zu suchen. 0 Boolesch Nein

Datentypzuordnung

Wenn Sie Abfragen über den ODBC-Treiber für BigQuery ausführen, erfolgt die folgende Datentypzuordnung:

GoogleSQL-Typ ODBC-SQL-Typ
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

Logging und Treiberkonfiguration

So konfigurieren Sie treiberweite Optionen wie Logging und Zeichencodierung:

Windows

Konfigurieren Sie die Protokollierungs- und DSN-Optionen über das DSN-Konfigurationsdialogfeld im ODBC Data Source Administrator.

Nicht-Windows

  1. Erstellen oder bearbeiten Sie eine Konfigurationsdatei, z. B. googlebigqueryodbc.ini, und fügen Sie Treiberoptionen im Abschnitt [Driver] hinzu. Hier ein Beispiel:

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

  2. Legen Sie die Umgebungsvariable GOOGLEBIGQUERYODBCINI auf den Pfad dieser Datei fest:

    export GOOGLEBIGQUERYODBCINI=/path/to/googlebigqueryodbc.ini

Treiber-Logging-Ebenen

Der Treiber unterstützt die Logging-Ebenen 0 bis 3. Wir empfehlen, mit LogLevel=3 (INFO) zu beginnen.

ODBC-Protokollierungsebene Beschreibung
0 (AUS) Deaktiviert das gesamte Logging.
1 (FEHLER) Protokolliert Fehlerereignisse.
2 (WARNUNG) Protokolliert Warnereignisse.
3 (INFO) Protokolliert allgemeine Informationen zum Fortschritt des Fahrers.

Treiberweite Konfigurationseigenschaften (nicht Windows)

Die folgenden Properties können im Abschnitt [Driver] in googlebigqueryodbc.ini konfiguriert werden:

Attribut Beschreibung Zulässige Werte Standardwert
WcharEncoding Steuert explizit die Wire-Codierung von SQLWCHAR-Zeichenpuffern beim Übergeben von Wide-Character-Strings zwischen dem Treiber und dem ODBC-Treibermanager (z. B. WcharEncoding=UTF-16LE). Dadurch werden Probleme mit beschädigten und abgeschnittenen Zeichen zwischen unixODBC (in der Regel 2-Byte-UTF-16LE) und iODBC (in der Regel 4-Byte-UTF-32LE) behoben. UTF-8, UTF-16LE, UTF-32LE Leer (automatische Erkennung basierend auf sizeof(SQLWCHAR))
MaxThreads Definiert die maximale Anzahl von Threads, die der Treiber für die gleichzeitige Verarbeitung in einem Threadpool verwenden kann. Positive Ganzzahl 8

Beispiele

Die folgenden Beispiele zeigen, wie Sie parametrisierte Abfragen und Scripts mit mehreren Anweisungen mit dem ODBC-Treiber verwenden.

Parametrisierte Abfragen

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

Skripts mit mehreren Anweisungen

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

Preise

Sie können den ODBC-Treiber für BigQuery kostenlos herunterladen. Wenn Sie den Treiber verwenden, gelten jedoch die standardmäßigen Preise für BigQuery-Analysen.

Nächste Schritte