JDBC-Treiber für BigQuery verwenden

Der JDBC-Treiber (Java Database Connectivity) für BigQuery verbindet Ihre Java-Anwendungen mit BigQuery, sodass Sie BigQuery-Funktionen mit Ihren bevorzugten Tools und Ihrer bevorzugten Infrastruktur verwenden können. Wenn Sie Nicht-Java-Anwendungen mit BigQuery verbinden möchten, verwenden Sie den ODBC-Treiber (Open Database Connectivity) für BigQuery.

Beschränkungen

Für den JDBC-Treiber für BigQuery gelten die folgenden Einschränkungen:

Hinweis

  1. Sie sollten mit JDBC-Treibern, Apache Maven und dem Paket java.sql vertraut sein.
  2. Prüfen Sie, ob Ihr System mit der Java-Laufzeitumgebung (JRE) 8.0 oder höher konfiguriert ist. Informationen zum Prüfen der JRE-Version finden Sie unter JRE-Umgebung prüfen.
  3. Authentifizieren Sie sich bei BigQuery und notieren Sie sich die folgenden Informationen, die später verwendet werden, wenn Sie eine Verbindung mit dem JDBC-Treiber für BigQuery herstellen. Sie müssen nur die Informationen beachten, die der von Ihnen verwendeten Authentifizierungsmethode entsprechen.

    Authentifizierungsmethode Authentifizierungsinformationen Beispiel Verbindungseigenschaft (wird später festgelegt)
    Standarddienstkonto E-Mail-Adresse des Dienstkontos bq-jdbc-sa@mytestproject.s3ns.iam.gserviceaccount.com OAuthServiceAcctEmail
    Dienstkontoschlüssel (JSON-Objekt) my-sa-key OAuthPvtKey
    Dienstkontoschlüsseldatei Dienstkontoschlüsseldatei (vollständiger Pfad) path/to/file/secret.json OAuthPvtKeyPath
    Google-Nutzerkonto Client-ID 123-abc.apps.googleusercontent.com OAuthClientId
    Clientschlüssel _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV OAuthClientSecret
    Vorgeneriertes Zugriffstoken Zugriffstoken ya29.a0AfH6SMCiH1L-x_yZ OAuthAccessToken
    Vorgeneriertes Aktualisierungstoken Aktualisierungstoken 1/fFAGRNJru1FTz70BzhT3Zg OAuthRefreshToken
    Client-ID 123-abc.apps.googleusercontent.com OAuthClientId
    Clientschlüssel _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV OAuthClientSecret
    Standardanmeldedaten für Anwendungen Keine – –
    Konfigurationsdatei Konfigurationsdatei (JSON-Objekt oder vollständiger Pfad) path/to/file/secret.json OAuthPvtKey
    Konfigurationsobjekt für externes Konto Kontokonfigurationsobjekt external_account_configuration_object OAuthPvtKey
    Sonstiges Attribut „Audience“ der Konfigurationsdatei für das externe Konto //iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider BYOID_AudienceUri
    Datei für Tokenabruf und Umgebungsinformationen {\"file\":\"/path/to/file\"} BYOID_CredentialSource
    Nutzerprojekt (nur bei Verwendung eines Workforce-Pools) my_project BYOID_PoolUserProject
    URI für die Identitätsübernahme des Dienstkontos (nur bei Verwendung eines Workforce-Pools) my-sa BYOID_SA_Impersonation_Uri
    Security Token Service-Token basierend auf der Tokenaustauschspezifikation urn:ietf:params:oauth:tokentype:id_token BYOID_SubjectTokenType
    Token-Austauschendpunkt des Security Token Service https://sts.googleapis.com/v1/token BYOID_TokenUri

JDBC-Treiber installieren und konfigurieren

Sie können den JDBC-Treiber für BigQuery entweder durch direktes Herunterladen der Uber-JAR-Datei oder mithilfe von Maven installieren und konfigurieren.

Konfiguration für direkten Download

So konfigurieren Sie den JDBC-Treiber über den direkten Download:

  1. Laden Sie die Version 1.6.0 des Treibers herunter.
  2. Kopieren Sie die heruntergeladene Datei an den von Ihrer Software angegebenen Speicherort.

Informationen zu Funktionsänderungen und Workflow-Updates finden Sie im Änderungsprotokoll.

Maven-Konfiguration

Der JDBC-Treiber für BigQuery ist auf Maven Central verfügbar.

Wenn Sie Ihre Entwicklungsumgebung mit dem JDBC-Treiber konfigurieren möchten, fügen Sie den Treiber als Abhängigkeit zu Ihrem Projekt hinzu:

Maven

Fügen Sie der Datei pom.xml die folgende Abhängigkeit hinzu:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.6.0</version>
</dependency>

Maven mit Uber-JAR-Datei

Fügen Sie der Datei pom.xml die folgende Abhängigkeit hinzu:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.6.0</version>
    <classifier>all</classifier>
    <exclusions>
      <exclusion>
        <groupId>*</groupId>
        <artifactId>*</artifactId>
      </exclusion>
    </exclusions>
</dependency>

Gradle

Fügen Sie der Datei build.gradle Folgendes hinzu:

dependencies {
// ... other dependencies
implementation("com.google.cloud:google-cloud-bigquery-jdbc:1.6.0")
}

Verbindung herstellen

So stellen Sie mit dem JDBC-Treiber für BigQuery eine Verbindung zwischen Ihrer Java-Anwendung und BigQuery her:

  1. Ermitteln Sie den Verbindungsstring für den JDBC-Treiber für BigQuery. Dieser String enthält alle erforderlichen Informationen, um eine Verbindung zwischen Ihrer Java-Anwendung und BigQuery herzustellen. Der Verbindungsstring hat das folgende Format:

    jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

    Ersetzen Sie Folgendes:

    • HOST: die DNS- oder IP-Adresse des Servers.
    • PORT: die TCP-Portnummer.
    • PROJECT_ID: Die ID Ihres BigQuery-Projekts.
    • AUTH_TYPE: Eine Zahl, die den verwendeten Authentifizierungstyp angibt. Einer der folgenden:
      • 0: für die Dienstkontoauthentifizierung (Standard- und Schlüsseldatei)
      • 1: für die Authentifizierung von Google-Nutzerkonten
      • 2: für die Authentifizierung mit einem vorab generierten Aktualisierungs- oder Zugriffstoken
      • 3: für die Authentifizierung mit Standardanmeldedaten für Anwendungen
      • 4: für andere Authentifizierungsmethoden
    • AUTH_PROPS: die Authentifizierungsinformationen, die Sie bei der Authentifizierung bei BigQuery notiert haben, im Format property_1=value_1; property_2=value_2;..., z. B. OAuthPvtKeyPath=path/to/file/secret.json, wenn Sie sich mit einer Dienstkontoschlüsseldatei authentifiziert haben.
    • OTHER_PROPS (optional): Zusätzliche Verbindungsattribute für den JDBC-Treiber, aufgeführt im Format property_1=value_1; property_2=value_2;.... Eine vollständige Liste der Verbindungseigenschaften finden Sie unter Verbindungseigenschaften.
  2. Verbinden Sie Ihre Java-Anwendung mit dem JDBC-Treiber für BigQuery entweder mit der Klasse DriverManager oder DataSource.

    • Stellen Sie eine Verbindung zur Klasse DriverManager her:

      import java.sql.Connection;
      import java.sql.DriverManager;
      
      private static Connection getJdbcConnectionDM(){
        Connection connection = DriverManager.getConnection(CONNECTION_STRING);
        return connection;
      }

      Ersetzen Sie CONNECTION_STRING durch den Verbindungsstring aus dem vorherigen Schritt.

    • Stellen Sie eine Verbindung zur Klasse DataSource her:

      import com.google.cloud.bigquery.jdbc.DataSource;
      import java.sql.Connection;
      import java.sql.SQLException;
      
      private static public Connection getJdbcConnectionDS() throws SQLException {
        Connection connection = null;
        DataSource dataSource = new com.google.cloud.bigquery.jdbc.DataSource();
        dataSource.setURL(CONNECTION_STRING);
        connection = dataSource.getConnection();
        return connection;
      }

      Ersetzen Sie CONNECTION_STRING durch den Verbindungsstring aus dem vorherigen Schritt.

      Die Klasse DataSource hat auch Setter-Methoden, mit denen Sie Verbindungsattribute festlegen können, anstatt sie in den Verbindungsstring aufzunehmen. Hier ein Beispiel:

      private static Connection getConnection() throws SQLException {
        DataSource ds = new DataSource();
        ds.setURL(jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;);
        ds.setAuthType(3);  // Application Default Credentials
        ds.setProjectId("MyTestProject");
        ds.setEnableHighThroughputAPI(true);
        ds.setLogLevel("6");
        ds.setUseQueryCache(false);
        return ds.getConnection();
      }

Verbindungsattribute

Verbindungsattribute für JDBC-Treiber sind Konfigurationsparameter, die Sie in den Verbindungsstring einfügen oder über Setter-Methoden übergeben, wenn Sie eine Verbindung zu einer Datenbank herstellen. Die folgenden Verbindungsattribute werden vom JDBC-Treiber für BigQuery unterstützt.

Verbindungsattribut 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 das Attribut ProjectId festgelegt wird. – Kommagetrennter String Nein
AllowLargeResults Bestimmt, ob der Treiber Abfrageergebnisse verarbeitet, die größer als 128 MB sind, wenn das Attribut QueryDialect auf BIG_QUERY gesetzt ist. Wenn das Attribut QueryDialect auf SQL gesetzt ist, verarbeitet der Treiber immer große Abfrageergebnisse. TRUE Boolesch Nein
BYOID_AudienceUri Das Attribut „audience“ in einer Konfigurationsdatei für ein externes Konto. Das Attribut „audience“ kann den Ressourcennamen für den Workload Identity-Pool oder Workforce Identity-Pool sowie die Anbieter-ID in diesem Pool enthalten. – String Nur wenn OAuthType=4
BYOID_CredentialSource Der Tokenabruf und die Umgebungsinformationen. – String Nur wenn OAuthType=4
BYOID_PoolUserProject Das Nutzerprojekt, wenn ein Workforce-Pool für die Authentifizierung verwendet wird. – String Nur wenn OAuthType=4 und der Personalpool verwendet wird
BYOID_SA_Impersonation_Uri Der URI für die Identitätsübernahme des Dienstkontos, wenn ein Workforce-Pool für die Authentifizierung verwendet wird. – String Nur wenn OAuthType=4 und der Personalpool verwendet wird
BYOID_SubjectTokenType Das Security Token Service-Token basierend auf der Tokenaustauschspezifikation. Einer der folgenden:
  • 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
urn:ietf:params:oauth:tokentype:id_token String Nur wenn OAuthType=4
BYOID_TokenUri Der Token-Austausch-Endpunkt des Security Token Service. https://sts.googleapis.com/v1/token String Nein
ConnectionPoolSize Die Größe des Verbindungspools, wenn Verbindungs-Pooling aktiviert ist. 10 Lang Nein
DefaultDataset Das Dataset, das verwendet wird, wenn in einer Abfrage kein Dataset angegeben ist. – String Nein
EnableGcpLogExporter Bestimmt, ob der Treiber Logs automatisch nach Cloud Logging exportiert (wenn keine benutzerdefinierte oder globale OpenTelemetry-Instanz verwendet wird). Weitere Informationen finden Sie unter OpenTelemetry. FALSE Boolesch Nein
EnableGcpTraceExporter Bestimmt, ob der Treiber Traces automatisch in Cloud Trace exportiert (wenn keine benutzerdefinierte oder globale OpenTelemetry-Instanz verwendet wird). Weitere Informationen finden Sie unter OpenTelemetry. FALSE Boolesch Nein
EnableHighThroughputAPI Bestimmt, ob die Storage Read API verwendet werden kann. Die Attribute HighThroughputActivationRatio und HighThroughputMinTableSize müssen ebenfalls auf TRUE gesetzt sein, um die Storage Read API zu verwenden. FALSE Boolesch Nein
EnableProjectDiscovery Bestimmt, ob Datenbankmetadaten-Methoden Datasets in allen zugänglichen Cloud de Confiance -Projekten erkennen. Wenn FALSE festgelegt ist, ist die Erkennung auf die Standard-ProjectId beschränkt. FALSE Boolesch Nein
EnableSession Bestimmt, ob die Verbindung eine Sitzung startet. Wenn TRUE festgelegt ist, wird die Sitzungs-ID an alle nachfolgenden Abfragen übergeben. FALSE Boolesch Nein
EnableTimestampPicos Bestimmt, ob der Treiber TIMESTAMP(12)-Werte mit Pikosekunden-Genauigkeit abruft. Wenn der Wert auf TRUE gesetzt ist, werden TIMESTAMP(12)-Werte von den Methoden getString() und getObject() als UTC-formatierte String-Objekte zurückgegeben. Wenn der Wert auf FALSE gesetzt ist, werden TIMESTAMP(12)-Werte auf eine 6-stellige Mikrosekundenpräzision gekürzt. Dieses Attribut ist nicht mit Legacy-SQL (QueryDialect=BIG_QUERY) kompatibel. FALSE Boolesch Nein
EnableWriteAPI Bestimmt, ob die Storage Write API (gRPC) verwendet werden kann. Er muss auf TRUE gesetzt sein, um Bulk-Einfügungen zu aktivieren. FALSE Boolesch Nein
EndpointOverrides Benutzerdefinierte Endpunkte zum Überschreiben der folgenden Elemente:
  • BIGQUERY=https://bigquery.googleapis.com
  • READ_API=https://bigquerystorage.googleapis.com
  • OAUTH2=https://oauth2.googleapis.com
  • STS=https://sts.googleapis.com
– Kommagetrennter String Nein
FilterTablesOnDefaultDataset Bestimmt den Umfang der Metadaten, die von den Methoden DatabaseMetaData.getTables() und DatabaseMetaData.getColumns() zurückgegeben werden. Wenn FALSE festgelegt ist, wird keine Filterung durchgeführt. Das Attribut DefaultDataset muss ebenfalls festgelegt werden, um das Filtern zu aktivieren. FALSE Boolesch Nein
GcpTelemetryCredentials Die Anmeldedaten, die zur Authentifizierung von Telemetrie-Exportern verwendet werden. Akzeptiert einen Pfad zu einem JSON-Schlüssel des Dienstkontos oder den JSON-Rohstring. Wenn keine Angabe erfolgt, werden standardmäßig die Anmeldedaten für die Verbindung verwendet. Weitere Informationen finden Sie unter OpenTelemetry. – String Nein
GcpTelemetryProjectId Die Ziel-Projekt-ID von Cloud de Confiance by S3NS für Telemetriedaten. Die Standardeinstellung ist die primäre ProjectId. Weitere Informationen finden Sie unter OpenTelemetry. – String Nein
HighThroughputActivationRatio Der Schwellenwert für die Anzahl der Seiten in einer Abfrageantwort. Wenn diese Anzahl überschritten wird und die Bedingungen EnableHighThroughputAPI und HighThroughputMinTableSize erfüllt sind, verwendet der Treiber die Storage Read API. 2 Ganzzahl Nein
HighThroughputMinTableSize Der Grenzwert für die Anzahl der Zeilen in einer Abfrageantwort. Wenn diese Anzahl überschritten wird und die Bedingungen EnableHighThroughputAPI und HighThroughputActivationRatio erfüllt sind, verwendet der Treiber die Storage Read API. 10000 Ganzzahl Nein
JobCreationMode Bestimmt, ob Abfragen mit oder ohne Jobs ausgeführt werden. Der Wert 1 bedeutet, dass für jede Abfrage Jobs erstellt werden. Der Wert 2 bedeutet, dass Abfragen ohne Jobs ausgeführt werden können. 2 Ganzzahl Nein
JobTimeout Das Zeitlimit für den Job (in Sekunden), nach dem der Job auf dem Server abgebrochen wird. 0 Lang Nein
KMSKeyName Der KMS-Schlüsselname zum Verschlüsseln von Daten. – String Nein
Labels Labels, die mit der Abfrage verknüpft sind, um Abfragejobs zu organisieren und zu gruppieren. – Map<String, String> Nein
LargeResultDataset Das Ziel-Dataset für große Abfrageergebnisse, nur wenn das Attribut LargeResultTable festgelegt ist. Wenn Sie dieses Attribut festlegen, umgehen Datenschreibvorgänge den Ergebniscache und lösen für jede Abfrage eine Abrechnung aus, auch wenn die Ergebnisse klein sind. _google_jdbc String Nein
LargeResultsDatasetExpirationTime Die Lebensdauer aller Tabellen in einem großen Ergebnis-Dataset in Millisekunden. Diese Property wird ignoriert, wenn für das Dataset bereits eine Standardablaufzeit festgelegt ist. 3600000 Lang Nein
LargeResultTable Die Zieltabelle für große Abfrageergebnisse, nur wenn das Attribut LargeResultDataset festgelegt ist. Wenn Sie dieses Attribut festlegen, werden Datenschreibvorgänge am Ergebniscache vorbeigeleitet und für jede Abfrage wird eine Abrechnung ausgelöst, auch wenn die Ergebnisse klein sind. temp_table... String Nein
ListenerPoolSize Die Größe des Listener-Pools, wenn Verbindungs-Pooling aktiviert ist. 10 Lang Nein
Location Der Standort, an dem Datasets erstellt oder abgefragt werden. BigQuery bestimmt den Standort automatisch, wenn dieses Attribut nicht festgelegt ist. – String Nein
LogLevel Der Detaillierungsgrad, der vom Treiber protokolliert wird. Weitere Informationen finden Sie unter Logging. 0 Ganzzahl Nein
LogPath Das Verzeichnis, in das Logdateien geschrieben werden. – String Nein
MaximumBytesBilled Das Limit für die abgerechneten Byte. Abfragen mit abgerechneten Byte, die diese Anzahl überschreiten, schlagen fehl, ohne dass eine Gebühr anfällt. 0 Lang Nein
MaxResults Die maximale Anzahl von Ergebnissen pro Seite. 10000 Lang Nein
MetaDataFetchThreadCount Die Anzahl der Threads, die für Datenbankmetadatenmethoden verwendet werden. 32 Ganzzahl Nein
OAuthAccessToken Das Zugriffstoken, das für die Authentifizierung mit einem vorab generierten Zugriffstoken verwendet wird. – String Nur wenn OAUTH_TYPE=2
OAuthClientId Die Client-ID für die Authentifizierung mit vorab generierten Aktualisierungstokens und die Authentifizierung von Nutzerkonten. – String Nur wenn OAUTH_TYPE=1 oder OAUTH_TYPE=2
OAuthClientSecret Der Clientschlüssel für die Authentifizierung mit einem vorab generierten Aktualisierungstoken und die Authentifizierung des Nutzerkontos. – String Nur wenn OAUTH_TYPE=1 oder OAUTH_TYPE=2
OAuthP12Password Das Passwort für die PKCS12-Schlüsseldatei. notasecret String Nein
OAuthPvtKey Der Dienstkontoschlüssel, wenn die Dienstkontoauthentifizierung verwendet wird. Dieser Wert kann ein JSON-Rohschlüsseldateiobjekt oder ein Pfad zur JSON-Schlüsseldatei sein. – String Nur wenn OAUTH_TYPE=0 und der Wert OAuthPvtKeyPath nicht festgelegt ist
OAuthPvtKeyPath Der Pfad zum Dienstkontoschlüssel, wenn Sie die Dienstkontoauthentifizierung verwenden. – String Nur wenn OAUTH_TYPE=0 und die Werte OAuthPvtKey und OAuthServiceAcctEmail nicht festgelegt sind
OAuthRefreshToken Das Aktualisierungstoken für die Authentifizierung mit einem vorab generierten Aktualisierungstoken. – String Nur wenn OAUTH_TYPE=2
OAuthServiceAcctEmail Die E-Mail-Adresse des Dienstkontos, wenn die Dienstkontoauthentifizierung verwendet wird. – String Nur wenn OAUTH_TYPE=0 und der Wert OAuthPvtKeyPath nicht festgelegt ist
OAuthType Der Authentifizierungstyp. Einer der folgenden:
  • 0: Dienstkonto-Authentifizierung
  • 1: Nutzerkonto-Authentifizierung
  • 2: Authentifizierung mit vorab generiertem Aktualisierungs- oder Zugriffstoken
  • 3: Authentifizierung mit Standardanmeldedaten für Anwendungen
  • 4: andere Authentifizierungsmethoden
-1 Ganzzahl Ja
PartnerToken Ein Token, das von Cloud de Confiance -Partnern verwendet wird, um die Nutzung des Treibers zu verfolgen. – String Nein
ProjectId Die Standardprojekt-ID für den Treiber. Dieses Projekt wird zum Ausführen von Abfragen verwendet und die Ressourcennutzung wird in Rechnung gestellt. Wenn nicht festgelegt, leitet der Treiber eine Projekt-ID ab. – String Nein, aber dringend empfohlen
ProxyHost Der Hostname oder die IP-Adresse eines Proxyservers, über den die JDBC-Verbindung weitergeleitet wird. – String Nein
ProxyPort Die Portnummer, über die der Proxyserver auf Verbindungen wartet. – String Nein
ProxyPwd Das Passwort für die Authentifizierung, wenn die Verbindung über einen Proxyserver hergestellt wird, der dies erfordert. – String Nein
ProxyUid Der Nutzername für die Authentifizierung, wenn die Verbindung über einen Proxyserver hergestellt wird, der dies erfordert. – String Nein
QueryDialect Der SQL-Dialekt für die Abfrageausführung. Verwenden Sie SQL für GoogleSQL (dringend empfohlen) und BIG_QUERY für Legacy-SQL. SQL String Nein
QueryProperties REST-Verbindungsattribute, mit denen das Abfrageverhalten angepasst wird. – Map<String, String> Nein
RequestGoogleDriveScope Fügt der Verbindung den Drive-Bereich mit Lesezugriff hinzu, wenn der Wert auf 1 gesetzt ist. 0 Ganzzahl Nein
RetryInitialDelay Legt die Verzögerung (in Sekunden) vor dem ersten Wiederholungsversuch fest. 0 Lang Nein
RetryMaxDelay Legt das maximale Limit (in Sekunden) für die Wiederholungsverzögerung fest. 0 Lang Nein
ServiceAccountImpersonationChain Eine durch Kommas getrennte Liste von Dienstkonto-E-Mails in der Identitätswechselkette. – String Nein
ServiceAccountImpersonationEmail Die E-Mail-Adresse des Dienstkontos, dessen Identität übernommen werden soll. – String Nein
ServiceAccountImpersonationScopes Eine durch Kommas getrennte Liste von OAuth2-Bereichen, die mit dem imitierten Konto verwendet werden sollen. https://www.googleapis.com/auth/bigquery String Nein
ServiceAccountImpersonationTokenLifetime Die Lebensdauer des Tokens für das Konto, dessen Identität übernommen wurde (in Sekunden). 3600 Ganzzahl Nein
SSLTrustStore Der vollständige Pfad zum Java TrustStore, der vertrauenswürdige Zertifikate der Zertifizierungsstelle enthält. Der Treiber verwendet diesen Truststore, um die Identität des Servers während des SSL/TLS-Handshakes zu validieren. – String Nein
SSLTrustStoreProvider Der JCE-Anbieter (Java Cryptography Extension), der für das Attribut SSLTrustStore verwendet wird. – String Nein
SSLTrustStorePwd Das Passwort für den Java TrustStore, der im Attribut SSLTrustStore angegeben ist. – String Nur wenn der Java-TrustStore passwortgeschützt ist
SSLTrustStoreType Das Format der Truststore-Datei, die im Attribut SSLTrustStore angegeben ist (z. B. JKS, PKCS12 oder ROTKS). – String Nein
SWA_ActivationRowCount Der Schwellenwert von executeBatch insert Zeilen, bei dessen Überschreitung der Connector zur Storage Write API (gRPC) wechselt. 3 Ganzzahl Nein
SWA_AppendRowCount Die Größe des Schreibstreams. 1000 Ganzzahl Nein
Timeout Die Zeitspanne in Sekunden, die der Connector einen fehlgeschlagenen API-Aufruf wiederholt, bevor ein Zeitüberschreitungsfehler auftritt. 0 Lang Nein
UniverseDomain Die Top-Level-Domain, die mit den Cloud de Confiance -Ressourcen Ihrer Organisation verknüpft ist. googleapis.com String Nein
UnsupportedHTAPIFallback Bestimmt, ob der Connector auf die REST API zurückgreift (wenn auf TRUE festgelegt) oder einen Fehler zurückgibt (wenn auf FALSE festgelegt). TRUE Boolesch Nein
UseGlobalOpenTelemetry Bestimmt, ob der Treiber GlobalOpenTelemetry.get() für die Instrumentierung verwendet. Weitere Informationen finden Sie unter OpenTelemetry. FALSE Boolesch Nein
UseQueryCache Aktiviert das Abfrage-Caching. TRUE Boolesch Nein

Abfragen mit dem Treiber ausführen

Wenn Ihre Java-Anwendung über den JDBC-Treiber mit BigQuery verbunden ist, können Sie jetzt Abfragen in Ihrer Entwicklungsumgebung über den standardmäßigen JDBC-Prozess ausführen. Es gelten alle BigQuery-Kontingente und -Limits.

Datentypzuordnung

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

GoogleSQL-Typ Java-Typ
ARRAY Array
BIGNUMERIC BigDecimal
BOOL Boolean
BYTES byte[]
DATE Date
DATETIME String
FLOAT64 Double
GEOGRAPHY String
INT64 Long
INTERVAL String
JSON String
NUMERIC BigDecimal
STRING String
STRUCT Struct
TIME Time
TIMESTAMP Timestamp

Beispiele

In den folgenden Abschnitten finden Sie Beispiele für die Verwendung von BigQuery-Features über den JDBC-Treiber für BigQuery.

Positionsparameter

Im folgenden Beispiel wird eine Abfrage mit einem Positionsparameter ausgeführt:

PreparedStatement preparedStatement = connection.prepareStatement(
    "SELECT * FROM MyTestTable where testColumn = ?");
preparedStatement.setString(1, "string2");
ResultSet resultSet = statement.executeQuery(selectQuery);

Verschachtelte und wiederkehrende Datensätze

Im folgenden Beispiel wird der Basisdatensatz der Struct-Daten abgefragt:

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct obj = (Struct) resultSet.getObject(1);
    System.out.println(obj.toString());

Der Treiber gibt den Basisdatensatz als Struct-Objekt oder als Stringdarstellung eines JSON-Objekts zurück. Das Ergebnis sieht etwa so aus:

{
  "v": {
    "f": [
      {
        "v": "Adam"
      },
      {
        "v": "5"
      }
    ]
  }
}

Im folgenden Beispiel werden die Unterkomponenten eines Struct-Objekts abgefragt:

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct structObject = (Struct) resultSet.getObject(1);
    Object[] structComponents = structObject.getAttributes();
    for (Object component : structComponents){
      System.out.println(component.toString());
    }

Im folgenden Beispiel wird ein Standard-Array mit wiederholten Daten abgefragt und das Ergebnis überprüft:

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT [1,2,3]");
resultSet.next();
Object[] arrayObject = (Object[]) resultSet.getArray(1).getArray();

// Verify Result
int count =0;
for (; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

Im folgenden Beispiel wird ein Struct-Array mit wiederholten Daten abgefragt und dann das Ergebnis überprüft:

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT "
    + "[STRUCT(\"Adam\" as name, 12 as age), "
    + "STRUCT(\"Lily\" as name, 17 as age)]");

Struct[] arrayObject = (Struct[]) resultSet.getArray(1).getArray();

// Verify Result
for (int count =0; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

Bulk-Einfügung

Im folgenden Beispiel wird ein Bulk-Insert-Vorgang mit der Methode executeBatch ausgeführt.

Connection conn = DriverManager.getConnection(connectionUrl);
PreparedStatement statement = null;
Statement st = conn.createStatement();
final String insertQuery = String.format(
        "INSERT INTO `%s.%s.%s` "
      + " (StringField, IntegerField, BooleanField) VALUES(?, ?, ?);",
        DEFAULT_CATALOG, DATASET, TABLE_NAME);

statement = conn.prepareStatement(insertQuery1);

for (int i=0; i<2000; ++i) {
      statement.setString(1, i+"StringField");
      statement.setInt(2, i);
      statement.setBoolean(3, true);
      statement.addBatch();
}

statement.executeBatch();

Logging

Wenn Sie Probleme mit dem JDBC-Treiber für BigQuery beheben möchten, können Sie das Logging aktivieren, indem Sie Verbindungsattribute oder Umgebungsvariablen festlegen. Das Logging kann die Leistung beeinträchtigen und Speicherplatz belegen. Aktivieren Sie es daher nur vorübergehend, um ein Problem zu erfassen.

Logebenen

Das Attribut LogLevel bestimmt den Detaillierungsgrad, der vom Paket java.util.logging protokolliert wird:

  • 0: OFF (Standard)
  • 1: SEVERE
  • 2: WARNING
  • 3: INFO
  • 4: CONFIG
  • 5: FINE
  • 6: FINER
  • 7: FINEST
  • 8: ALL

Wir empfehlen Stufe 6 für die allgemeine Fehlerbehebung. Die Stufen 7 und 8 sind auf ResultSet-Vorgänge beschränkt und generieren eine große Menge an Logs.

Logging im Verbindungsstring aktivieren

Wenn Sie das Logging im Verbindungsstring aktivieren möchten, fügen Sie die Verbindungseigenschaften LogLevel und LogPath hinzu, z. B.:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=MyTestProject;OAuthType=3;LogLevel=6;LogPath=/tmp/jdbc-logs;

Logging mit Umgebungsvariablen aktivieren

Wenn Ihr Entwicklungstool keine Bearbeitung von Verbindungsstrings zulässt, können Sie die Logebene und den Logpfad auch mit den folgenden Umgebungsvariablen festlegen, bevor Sie Ihre Anwendung ausführen:

  • BIGQUERY_JDBC_LOG_LEVEL: die Logebene (0–8).
  • BIGQUERY_JDBC_LOG_PATH: das Verzeichnis für Logdateien.

Führen Sie in einer Linux- oder macOS-Umgebung beispielsweise Folgendes aus:

export BIGQUERY_JDBC_LOG_LEVEL=6
export BIGQUERY_JDBC_LOG_PATH=/tmp/jdbc-logs

OpenTelemetry

Der JDBC-Treiber für BigQuery unterstützt OpenTelemetry (OTel) für verteiltes Tracing und Logging. So können Sie die Leistung Ihrer Datenbankinteraktionen überwachen und Probleme effektiv beheben.

Verfolgte Vorgänge

Wenn OpenTelemetry aktiviert ist, generiert der Treiber Spans für die folgenden Vorgänge:

  • Abfrageausführung: Spans werden für BigQueryStatement (execute(), executeQuery(), executeLargeUpdate(), executeBatch()) und BigQueryPreparedStatement (execute(), executeQuery(), executeLargeUpdate()) generiert.
  • Metadatenvorgänge: Spans werden für bestimmte DatabaseMetaData-Methoden (getCatalogs(), getSchemas(), getTables(), getColumns()) generiert.
  • Paginierung: Asynchrone Abrufe für zusätzliche Ergebnisseiten (bei Verwendung des REST API-Pfads) werden verfolgt und mithilfe von OpenTelemetry-Span-Links kausal mit dem ursprünglichen Abfrageausführungs-Span verknüpft. Für diese Vorgänge wird ein Span mit dem Namen BigQueryStatement.pagination erstellt.
  • Kontextweitergabe: Der JDBC-Treiber gibt den aktiven Kontext an das zugrunde liegende google-cloud-bigquery SDK weiter. Daher werden vom SDK generierte Spans (z. B. HTTP-RPC-Aufrufe) automatisch als untergeordnete Elemente der JDBC-Spans angezeigt, was eine vollständige End-to-End-Trace-Hierarchie ermöglicht.

Konfigurationsmodi

Sie können OpenTelemetry im JDBC-Treiber mit einem der folgenden Modi konfigurieren, je nach Architektur und Anforderungen Ihrer Anwendung.

Anwendungsverwaltete Telemetrie

Wenn Ihre Anwendung bereits OpenTelemetry verwendet, können Sie Ihre OpenTelemetry-Instanz in den JDBC-Treiber einfügen, damit die Telemetriedaten des Treibers mit den Telemetriedaten Ihrer Anwendung korreliert werden.

Verwenden Sie dazu die BigQueryDataSource API:

BigQueryDataSource dataSource = new BigQueryDataSource();
// ... set other properties ...
dataSource.setCustomOpenTelemetry(yourOpenTelemetryInstance);

Globale OpenTelemetry-Unterstützung

Wenn Sie OpenTelemetry global in Ihrer Anwendung initialisiert haben (z. B. mit dem OpenTelemetry Java Agent oder durch Aufrufen der Funktion GlobalOpenTelemetry.set()), können Sie den Treiber so konfigurieren, dass er diese globale Instanz verwendet.

Wenn Sie die globale Instanz aktivieren möchten, setzen Sie die Verbindungseigenschaft UseGlobalOpenTelemetry auf TRUE.

Cloud de Confiance -Telemetrie ohne Konfiguration

Wenn Sie Cloud de Confiance verwenden und eine schnelle Einrichtung wünschen, können Sie den automatischen Export von Traces und Logs in die Beobachtbarkeit von Cloud de Confiance (Trace und Logging) aktivieren.

Wenn Sie diesen Export aktivieren möchten, legen Sie die folgenden Verbindungsattribute in Ihrer JDBC-URL fest:

  • EnableGcpTraceExporter=true
  • EnableGcpLogExporter=true

Hier ist eine Beispiel-Verbindungs-URL:

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=your-project-id;EnableGcpTraceExporter=true;EnableGcpLogExporter=true;

OpenTelemetry-Verbindungsattribute

Die folgenden Verbindungseigenschaften werden für OpenTelemetry unterstützt. Ausführliche Beschreibungen und Standardwerte finden Sie unter Verbindungseigenschaften.

  • EnableGcpLogExporter
  • EnableGcpTraceExporter
  • GcpTelemetryCredentials
  • GcpTelemetryProjectId
  • UseGlobalOpenTelemetry

Was Sie bedenken sollten

Beachten Sie bei der Bereitstellung der OpenTelemetry-Integration die folgenden Hinweise zu Logging-Verhalten, Authentifizierung, Proxy-Konfiguration und Preisen.

Interaktion mit LogLevel

Die vorhandene Verbindungseigenschaft LogLevel fungiert als primärer Gatekeeper für das Logging.

  • Wenn LogLevel=0 (AUS) festgelegt ist, werden keine Logeinträge generiert. Daher werden keine Logs mit OpenTelemetry oder nach Logging exportiert, auch wenn EnableGcpLogExporter=true.
  • Wenn Sie OTel-Logging aktivieren möchten, muss LogLevel auf einen Wert größer als 0 festgelegt sein (z. B. 5 für detaillierte Logs).

Authentifizierung für Telemetrie

Der Telemetrieexport (Tracing und Logging) mit dem automatischen FallbackCloud de Confiance unterstützt sowohl Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) als auch explizite Dienstkonto-Anmeldedaten, die über GcpTelemetryCredentials bereitgestellt werden.

Wenn GcpTelemetryProjectId oder GcpTelemetryCredentials angegeben ist, werden sowohl Logs als auch Traces mit denselben konfigurierten Anmeldedaten an dasselbe angegebene Zielprojekt gesendet.

Proxykonfiguration mit OpenTelemetry und Logging

Wenn Ihre Anwendung über einen Proxyserver eine Verbindung zu BigQuery herstellt, verarbeitet der Treiber das Proxy-Routing so:

  • Trace-Export (HTTP). Wenn Sie das Standard-HTTP-Protokoll für den OpenTelemetry-Trace-Export (otel.exporter.otlp.protocol=http/protobuf) verwenden, leitet der Treiber den Trace-Export-Traffic automatisch über den Proxy weiter, der in den Verbindungseigenschaften mit ProxyHost und ProxyPort konfiguriert ist.
  • Logexport und gRPC-Telemetrie. Der automatische Log-Exporter von Cloud de Confiance (EnableGcpLogExporter=true) und gRPC-basierte OpenTelemetry-Exporter (otel.exporter.otlp.protocol=grpc) verwenden gRPC, das keine Proxykonfiguration pro Verbindung unterstützt. Wenn Sie den Logexport- und gRPC-Telemetrie-Traffic über einen Proxyserver weiterleiten möchten, konfigurieren Sie die Proxy-Einstellungen auf JVM-Ebene mit den folgenden Systemeigenschaften:

    -Dhttps.proxyHost=PROXY_HOST -Dhttps.proxyPort=PROXY_PORT

Erforderliche APIs und IAM-Berechtigungen

Damit Telemetriedaten erfolgreich in die Observability von Cloud de Confiance by S3NS geschrieben werden können, müssen Sie in Ihrem Zielprojekt von Cloud de Confiance die folgende Einrichtung vornehmen:

  1. Aktivieren Sie die APIs:
    • Aktivieren Sie die Cloud Trace API (cloudtrace.googleapis.com).
    • Aktivieren Sie die Cloud Logging API (logging.googleapis.com).
  2. Weisen Sie IAM-Rollen zu:
    • Zum Exportieren von Traces: Weisen Sie dem Hauptkonto oder Dienstkonto die Rolle „Trace-Agent“ (roles/cloudtrace.agent) zu.
    • Zum Exportieren von Logs: Weisen Sie dem Hauptkonto oder Dienstkonto die Rolle „Logautor“ (roles/logging.logWriter) zu.

Preise und Abrechnung

Wenn Sie die Cloud de Confiance -Telemetrie ohne Konfiguration (EnableGcpTraceExporter=true oder EnableGcpLogExporter=true) verwenden, werden Telemetriedaten an Trace und Logging gesendet. Für diese Dienste können Gebühren anfallen, die auf dem Volumen der Datenaufnahme basieren. Weitere Informationen finden Sie unter Google Cloud Observability.

Messwerte

Diese Integration unterstützt keine OpenTelemetry-Messwerte.

Schattierung von Abhängigkeiten

Um Konflikte mit dem Klassenpfad Ihrer Anwendung zu vermeiden, schattet der Treiber die OpenTelemetry SDK- und Exporter-Abhängigkeiten ab. Die OpenTelemetry API bleibt unverschattet, um die Interoperabilität mit dem von Ihrer Anwendung bereitgestellten SDK zu ermöglichen.

Korrelation zwischen Logging und Tracing

Wenn OpenTelemetry aktiviert ist, korreliert der Treiber Logs automatisch mit Traces:

  • db.connection_id: Wird als Span-Attribut an alle JDBC-Spans angehängt.
  • jdbc.connection_id: Wird als Baggage-Schlüssel verwendet und als Label an alle Logeinträge angehängt, die vom Treiber an Logging gesendet werden.
  • Trace-ID und Span-ID: Logs, die im Rahmen einer Abfrageausführung generiert werden, enthalten automatisch die aktive trace_id und span_id.

Preise

Sie können den JDBC-Treiber für BigQuery kostenlos herunterladen. Wenn Sie den Treiber verwenden, gelten jedoch die BigQuery-Standardpreise.

Nächste Schritte