ODBC-Treiber für BigQuery verwenden

Der ODBC-Treiber (Open Database Connectivity) für BigQuery stellt eine Verbindung zwischen Ihren Anwendungen und BigQuery her. So können Sie BigQuery-Funktionen mit Ihren bevorzugten Tools und Infrastrukturen nutzen.

Hinweis

  1. Machen Sie sich mit Open Database Connectivity (ODBC)-Treibern und dem Treibermanager vertraut.

  2. Beachten Sie die folgenden Systemanforderungen:

    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). Fügen Sie das Installationsverzeichnis zu LD_LIBRARY_PATH hinzu.

  3. Ermitteln Sie den Verbindungstyp für den ODBC-Treiber für BigQuery. Der Treiber unterstützt die folgenden Authentifizierungsmethoden:

    Authentifizierungsmethode Authentifizierungsinformationen Beispiel Verbindungseigenschaft (wird später festgelegt)
    Standarddienstkonto Dienstkontoschlüssel (JSON-Objekt) my-sa-key KeyFilePath
    Identitätsföderation von Arbeitslasten oder Mitarbeiteridentitätsfö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 oder andere STS-Typen BYOID_SubjectTokenType
    STS-Tokenaustausch-Endpunkt Benutzerdefinierte STS-Endpunkt-URL BYOID_TokenUrl
    Standardanmeldedaten für Anwendungen – – –

ODBC-Treiber installieren und konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie den ODBC-Treiber für Windows- und Nicht-Windows-Betriebssysteme installieren und konfigurieren.

Windows

Achten Sie unter Windows darauf, dass Sie die Treiberarchitektur installieren, die der Architektur Ihrer Anwendung entspricht. Verwenden Sie beispielsweise den 64‑Bit-Treiber für 64‑Bit-Anwendungen und den 32‑Bit-Treiber für 32‑Bit-Anwendungen. Ein 64-Bit-Windows-System unterstützt sowohl 32‑Bit- als auch 64‑Bit-Anwendungen.

DSN erstellen

So erstellen Sie einen Datenquellennamen in Windows:

  1. Rufen Sie im Menü Start die ODBC-Datenquellen auf und wählen Sie die Version aus, die dieselbe Bitanzahl wie Ihre Clientanwendung hat, um eine ordnungsgemäße Verbindung zu BigQuery herzustellen.
  2. Klicken Sie im ODBC Data Source Administrator auf den Tab Treiber.
  3. Suchen Sie in der alphabetischen Liste der installierten ODBC-Treiber nach dem ODBC-Treiber für BigQuery.
  4. Wählen Sie eine der folgenden Optionen aus:
    • Wenn Sie einen DSN für den aktuellen Nutzer erstellen möchten, klicken Sie auf den Tab Nutzer-DSN.
    • Wenn Sie einen System-DSN für alle Nutzer erstellen möchten, klicken Sie auf den Tab System-DSN. System-DSNs werden empfohlen, da einige Anwendungen Daten mit verschiedenen Nutzerkonten laden und möglicherweise keine Nutzer-DSNs erkennen, die unter einem anderen Nutzerkonto erstellt wurden.
  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.
  7. Das Dialogfeld ODBC Driver for BigQuery DSN Setup (ODBC-Treiber für BigQuery – DSN-Einrichtung) wird geöffnet.
  8. Geben Sie im Feld Name der Datenquelle einen Namen für den DSN ein.
  9. Informationen dazu, welche Werte angegeben werden müssen, finden Sie im Abschnitt Verbindungseigenschaften.

Nicht Windows

64-Bit-Linux-Distributionen unterstützen sowohl 32‑Bit- als auch 64‑Bit-Anwendungen. Die Architektur des ODBC-Treibers muss mit der Anwendung übereinstimmen, die Sie verwenden möchten. Verwenden Sie beispielsweise den 64-Bit-Treiber für 64-Bit-Anwendungen und den 32-Bit-Treiber für 32-Bit-Anwendungen. Sie können beide Treiberarchitekturen gleichzeitig auf einem einzelnen System installieren.

So installieren Sie den Connector mit dem TAR- oder ZIP-Dateipaket:

  1. Erstellen Sie das Verzeichnis, in dem Sie den Connector installieren möchten, falls es noch nicht vorhanden ist.
  2. Extrahieren Sie die Haupt-ZIP-Datei an einem geeigneten temporären Speicherort.
  3. Rufen Sie den Ordner der extrahierten TAR- oder ZIP-Datei auf und kopieren Sie dann (optional) alle Dateien und Ordner in das Installationsverzeichnis.
  4. Nach der Extraktion lautet der Pfad des freigegebenen ODBC-Treiberobjekts für BigQuery [INSTALLDIR]/lib/libgoogle_cloud_odbc_bq_driver.so. Aktualisieren Sie Ihre .ini-Dateien, damit der richtige Pfad des Connectors angegeben ist.
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

Verbindung herstellen

Um eine Verbindung mit dem ODBC-Treiber für BigQuery herzustellen, können Sie einen Verbindungsstring oder einen DSN verwenden.

Format des Verbindungsstrings

Driver=ODBC Driver for BigQuery;ProjectId=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 der Identitätsföderation von Arbeitslasten oder Mitarbeitern
  • AUTH_PROPS: die Authentifizierungsinformationen, die Sie sich bei der Authentifizierung bei BigQuery notiert haben.
  • OTHER_PROPS (optional): zusätzliche Verbindungseigenschaften für den ODBC-Treiber.

Verbindungsattribute

ODBC-Treiberverbindungseigenschaften sind Konfigurationsparameter, die Sie in die Verbindungszeichenfolge 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 Eigenschaft ProjectId festgelegt wird. – Kommagetrennter String Nein
AllowHtapiForLargeResults Gibt an, ob der Fahrer die Read API verwenden kann. 0 Boolesch Nein
AllowLargeResults Gibt an, ob der ODBC-Treiber Abfrageergebnisse mit einer Größe von mehr als 128 MB verarbeiten soll, wenn Legacy-SQL (QueryDialect=BIG_QUERY) verwendet wird. 0 Boolesch Nein
BYOID_AudienceUrl „Audience“ 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 diesen Wert fest, wenn es sich um einen Workforce-Pool 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 OAuth2.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
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
FilterTablesOnDefaultDataset Bestimmt den Umfang der Metadaten, die von den Methoden für Tabellen-/Spaltenmetadaten zurückgegeben werden. Wenn FALSE, erfolgt keine Filterung. Sie müssen auch das Attribut DefaultDataset festlegen, um die Filterung zu aktivieren. FALSE Boolesch 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
JobCreationMode Ermöglicht das Aktivieren des Abfragepfads mit geringer Latenz. Wählen Sie eine der folgenden Optionen aus:
  • 1: Der Treiber erstellt Jobs für jede Abfrage (JOB_CREATION_REQUIRED).
  • 2: Der Treiber führt Abfragen ohne Jobs aus (JOB_CREATION_OPTIONAL).
 2 Ganzzahl Nein
KeyFilePath Der Pfad zum Dienstkontoschlüssel bei Verwendung der Dienstkonto-Authentifizierung. – String Nur, wenn OAuthMechanism=0
KMSKeyName Hiermit können Sie den Namen des KMS-Schlüssels angeben, der zum Verschlüsseln und Entschlüsseln von Daten verwendet werden soll. – String Nein
LargeResultsDataSetId Hiermit können Sie das Ziel-Dataset zum Speichern umfangreicher Abfrageergebnisse angeben. – String Nein
LargeResultsDatasetExpirationTime Hiermit können Sie die Lebensdauer aller Tabellen im Dataset mit umfangreichen Ergebnissen in Millisekunden angeben. 3600000 Lang Nein
Location Hiermit können Sie den Speicherort angeben, an dem der Treiber Datasets erstellt oder abfragt. – String Nein
LogLevel Beschränkt die Detailgenauigkeit der vom Treiber protokollierten Informationen während der Interaktionen. Wählen Sie eine der folgenden Optionen aus:
  • 0: OFF
  • 1: ERROR
  • 2: WARNING
  • 3: INFO
 0 Ganzzahl Nein
LogPath Hiermit können Sie das Verzeichnis angeben, in das der Treiber Logdateien schreibt. – String Nein
LogFileCount Hiermit können Sie die maximale Anzahl der Logdateien festlegen, die beibehalten werden sollen. 0 Ganzzahl Nein
LogFileSize Hiermit können Sie die maximale Größe jeder Logdatei in Byte festlegen. 0 Lang Nein
MaxResults Hiermit können Sie die Anzahl der Ergebnisse pro Seite im BigQuery API-Ergebnis angeben. 10000 Lang Nein
MaxThreads Definiert die maximale Anzahl von Threads, die der Connector für die gleichzeitige Verarbeitung in einem Thread-Pool verwenden kann. Wenn Sie diese Eigenschaft als connectorweite Einstellung für Nicht-Windows-Connectors (Linux/macOS) konfigurieren möchten, geben Sie sie 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: Authentifizierung mit Workload Identity- oder Mitarbeiteridentitätsföderation
 – Ganzzahl Ja
ProjectId Die Standardprojekt-ID für den Treiber. Der Treiber verwendet dieses Projekt zum Ausführen von Abfragen und stellt die Ressourcennutzung in Rechnung. – String Ja
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
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
QueryDialect Gibt an, welcher Abfragedialekt verwendet werden soll. Verwenden Sie SQL für GoogleSQL (dringend empfohlen) und BIG_QUERY für Legacy-SQL. SQL String Nein
QueryProperties Konfiguriert Attribute, die das Abfrageverhalten ändern können. – Map<String, String> Nein
UniverseDomain Gibt die Universe-Domain für Ihre Organisation an. googleapis.com String Nein
UseQueryCache Ermöglicht das Aktivieren der Funktion für das Zwischenspeichern von Abfragen in BigQuery. true Boolesch Nein

Abfragen mit dem Treiber ausführen

Dieser Abschnitt enthält Informationen zur Zuordnung von Datentypen und Beispiele für das Ausführen von Abfragen mit dem ODBC-Treiber.

Datentypzuordnung

Wenn Sie Abfragen über den ODBC-Treiber für BigQuery ausführen, erfolgt die folgende Datentypzuordnung (basierend auf Standard-ODBC-SQL-Typen):

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

Beispiele

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

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

Scripts 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

Für Abfragen über den ODBC-Treiber für BigQuery gelten die standardmäßigen Preise für BigQuery-Analysen.