JDBC-Treiber für BigQuery verwenden

Der JDBC-Treiber (Java Database Connectivity) für BigQuery verbindet Ihre Java-Anwendungen mit BigQuery. So können Sie BigQuery-Funktionen mit Ihren bevorzugten Tools und Infrastrukturen nutzen. 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:

• Der Treiber ist spezifisch für BigQuery und kann nicht mit anderen Produkten oder Diensten verwendet werden.
• Der Datentyp INTERVAL wird von der BigQuery Storage Read API nicht unterstützt.
• Es gelten alle Einschränkungen für die Datenbearbeitungssprache (DML).

Hinweis

1. Sie sollten mit JDBC-Treibern, Apache Maven und dem java.sql-Paket vertraut sein.
2. Prüfen Sie, ob auf Ihrem System die 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	Verbindungsproperty (wird später festgelegt)
   Standarddienstkonto	E-Mail-Adresse des Dienstkontos	bq-jdbc-sa@mytestproject.	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
   Vorab generiertes Zugriffstoken	Zugriffstoken	ya29.a0AfH6SMCiH1L-x_yZ	OAuthAccessToken
   Vorab generiertes 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	Zielgruppen-Property der Konfigurationsdatei für das externe Konto	//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider	BYOID_AudienceUri
   	Abrufen von Tokens und Datei mit 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 Mitarbeiteridentitätspools)	my-sa	BYOID_SA_Impersonation_Uri
   	Security Token Service-Token basierend auf der Token Exchange-Spezifikation	urn:ietf:params:oauth:tokentype:id_token	BYOID_SubjectTokenType
   	Security Token Service-Endpunkt für den Tokenaustausch	https://sts.googleapis.com/v1/token	BYOID_TokenUri

JDBC-Treiber installieren und konfigurieren

Sie können den JDBC-Treiber für BigQuery installieren und konfigurieren, indem Sie die Uber-JAR-Datei direkt herunterladen oder Maven verwenden.

Konfiguration für direkten Download

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

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

Informationen zu Funktionsänderungen und Workflow-Aktualisierungen finden Sie im Changelog.

Vorherige Versionen des JDBC-Treibers für BigQuery

• 1.0.0

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.1.0</version>
</dependency>

Maven mit Uber-JAR

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.1.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.1.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 Verbindungs-String 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: Der DNS-Name oder die IP-Adresse des Servers.
   • PORT: die TCP-Portnummer.
   • PROJECT_ID: die ID Ihres BigQuery-Projekts.
   • AUTH_TYPE: Eine Zahl, die den von Ihnen verwendeten Authentifizierungstyp angibt. Einer der folgenden:
     • 0: für die Dienstkonto-Authentifizierung (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 beim Authentifizieren 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 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 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 Verbindungseigenschaften 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

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

Hinweis :Bei allen Namen von Verbindungseigenschaften wird nicht zwischen Groß- und Kleinschreibung unterschieden. Boolesche Verbindungseigenschaften akzeptieren sowohl TRUE/FALSE als auch 1/0.

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
AllowLargeResults	Bestimmt, ob der Treiber Abfrageergebnisse verarbeitet, die größer als 128 MB sind, wenn die Eigenschaft 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. Die Eigenschaft „audience“ kann den Ressourcennamen für den Workload Identity-Pool oder Personalpool sowie die Anbieter-ID in diesem Pool enthalten.	–	String	Nur bei OAuthType=4
BYOID_CredentialSource	Der Token-Abruf und die Umgebungsinformationen.	–	String	Nur bei OAuthType=4
BYOID_PoolUserProject	Das Nutzerprojekt, wenn ein Workforce-Pool für die Authentifizierung verwendet wird.	–	String	Nur bei OAuthType=4 und Verwendung des Personalpools
BYOID_SA_Impersonation_Uri	Der URI für die Identitätsübernahme des Dienstkontos, wenn ein Workforce-Pool zur Authentifizierung verwendet wird.	–	String	Nur bei OAuthType=4 und Verwendung des Personalpools
BYOID_SubjectTokenType	Das Security Token Service-Token, das auf der Token Exchange-Spezifikation basiert. Einer der folgenden 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	urn:ietf:params:oauth:tokentype:id_token	String	Nur bei OAuthType=4
BYOID_TokenUri	Der Endpunkt für den Tokenaustausch des Security Token Service.	https://sts.googleapis.com/v1/token	String	Nein
ConnectionPoolSize	Die Größe des Verbindungspools, wenn das Verbindungs-Pooling aktiviert ist.	10	Lang	Nein
DefaultDataset	Das Dataset, das verwendet wird, wenn in einer Abfrage keines angegeben ist.	–	String	Nein
EnableGcpLogExporter	Gibt an, 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 automatisch Traces in Cloud Trace exportiert, wenn keine benutzerdefinierte oder globale OpenTelemetry-Instanz verwendet wird. Weitere Informationen finden Sie unter OpenTelemetry.	FALSE	Boolesch	Nein
EnableHighThroughputAPI	Gibt an, ob die Storage Read API verwendet werden kann. Die Attribute HighThroughputActivationRatio und HighThroughputMinTableSize müssen ebenfalls auf TRUE gesetzt sein, damit die Storage Read API verwendet werden kann.	FALSE	Boolesch	Nein
EnableProjectDiscovery	Gibt an, ob mit Datenbankmetadatenmethoden Datasets in allen zugänglichen Google Cloud Projekten ermittelt werden. Wenn der Wert auf FALSE festgelegt ist, wird die Erkennung auf die Standard-ProjectId beschränkt.	FALSE	Boolesch	Nein
EnableSession	Legt fest, ob mit der Verbindung eine Sitzung gestartet wird. Wenn TRUE festgelegt ist, wird die Sitzungs-ID an alle nachfolgenden Anfragen übergeben.	FALSE	Boolesch	Nein
EnableWriteAPI	Gibt an, ob die Storage Write API (gRPC) verwendet werden kann. Sie 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, findet keine Filterung statt. Das Attribut DefaultDataset muss ebenfalls festgelegt werden, damit die Filterung möglich ist.	FALSE	Boolesch	Nein
GcpTelemetryCredentials	Die Anmeldedaten, die zur Authentifizierung von Telemetrie-Exportern verwendet werden. Akzeptiert einen Pfad zu einem JSON-Schlüssel für ein Dienstkonto oder den rohen JSON-String. Wenn kein Wert festgelegt ist, werden standardmäßig die Anmeldedaten für die Verbindung verwendet. Weitere Informationen finden Sie unter OpenTelemetry.	–	String	Nein
GcpTelemetryProjectId	Die Zielprojekt-ID Google Cloud für die Telemetrie. Die Standardeinstellung ist die primäre ProjectId. Weitere Informationen finden Sie unter OpenTelemetry.	–	String	Nein
HighThroughputActivationRatio	Der Grenzwert für die Anzahl der Seiten in einer Abfrageantwort. Wenn diese Zahl überschritten wird und die Bedingungen EnableHighThroughputAPI und HighThroughputMinTableSize erfüllt sind, beginnt der Treiber mit der Verwendung der Storage Read API.	2	Ganzzahl	Nein
HighThroughputMinTableSize	Der Grenzwert für die Anzahl der Zeilen in einer Antwort auf eine Abfrage. Wenn diese Zahl überschritten wird und die Bedingungen EnableHighThroughputAPI und HighThroughputActivationRatio erfüllt sind, beginnt der Treiber mit der Verwendung der Storage Read API.	10000	Ganzzahl	Nein
JobCreationMode	Bestimmt, ob Abfragen mit oder ohne Jobs ausgeführt werden. Ein Wert von 1 bedeutet, dass für jede Abfrage Jobs erstellt werden, und ein Wert von 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 für die Verschlüsselung von Daten.	–	String	Nein
Labels	Labels, die der Abfrage zugeordnet sind, um Abfragejobs zu organisieren und zu gruppieren.	–	Map<String, String>	Nein
LargeResultDataset	Das Ziel-Dataset für umfangreiche Abfrageergebnisse, nur wenn das Attribut LargeResultTable festgelegt ist. Wenn Sie diese Eigenschaft festlegen, werden Daten, die geschrieben werden, nicht im Ergebnis-Cache gespeichert. Für jede Abfrage wird eine Abrechnung ausgelöst, 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 umfangreiche Abfrageergebnisse, nur wenn das Attribut LargeResultDataset festgelegt ist. Wenn Sie diese Eigenschaft festlegen, werden Daten, die geschrieben werden, nicht im Ergebnis-Cache gespeichert. Außerdem wird jede Abfrage in Rechnung gestellt, auch wenn die Ergebnisse klein sind.	temp_table...	String	Nein
ListenerPoolSize	Die Größe des Listener-Pools, wenn das Verbindungs-Pooling aktiviert ist.	10	Lang	Nein
Location	Der Speicherort, an dem Datasets erstellt oder abgefragt werden. BigQuery ermittelt den Standort automatisch, wenn diese Eigenschaft 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 berechneten Byte. Abfragen mit abgerechneten Bytes, die diese Zahl ü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 bei OAUTH_TYPE=2
OAuthClientId	Die Client-ID für die Authentifizierung mit einem vorab generierten Aktualisierungstoken und die Authentifizierung von Nutzerkonten.	–	String	Nur bei OAUTH_TYPE=1 oder OAUTH_TYPE=2
OAuthClientSecret	Der Clientschlüssel für die Authentifizierung mit einem vorab generierten Aktualisierungstoken und die Authentifizierung von Nutzerkonten.	–	String	Nur bei OAUTH_TYPE=1 oder OAUTH_TYPE=2
OAuthP12Password	Das Passwort für die PKCS12-Schlüsseldatei.	notasecret	String	Nein
OAuthPvtKey	Der Dienstkontoschlüssel bei Verwendung der Dienstkonto-Authentifizierung. Dieser Wert kann ein rohes JSON-Schlüsseldatei-Objekt oder ein Pfad zur JSON-Schlüsseldatei sein.	–	String	Nur, wenn OAUTH_TYPE=0 und der OAuthPvtKeyPath-Wert nicht festgelegt sind
OAuthPvtKeyPath	Der Pfad zum Dienstkontoschlüssel bei Verwendung der Dienstkonto-Authentifizierung.	–	String	Nur, wenn OAUTH_TYPE=0 und die Werte für OAuthPvtKey und OAuthServiceAcctEmail nicht festgelegt sind
OAuthRefreshToken	Das Aktualisierungstoken für die Authentifizierung mit einem vorab generierten Aktualisierungstoken.	–	String	Nur bei OAUTH_TYPE=2
OAuthServiceAcctEmail	Die E-Mail-Adresse des Dienstkontos bei Verwendung der Dienstkonto-Authentifizierung.	–	String	Nur, wenn OAUTH_TYPE=0 und der OAuthPvtKeyPath-Wert nicht festgelegt sind
OAuthType	Der Authentifizierungstyp. Einer der folgenden Werte: 0: Dienstkonto-Authentifizierung 1: Authentifizierung des Nutzerkontos 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 Google Cloud Partnern verwendet wird, um die Nutzung des Treibers zu verfolgen.	–	String	Nein
ProjectId	Die Standardprojekt-ID für den Treiber. In diesem Projekt werden Abfragen ausgeführt und die Ressourcennutzung wird abgerechnet. Wenn sie nicht festgelegt ist, 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 bei der Verbindung über einen Proxyserver, der dies erfordert.	–	String	Nein
ProxyUid	Der Nutzername für die Authentifizierung beim Verbindungsaufbau über einen Proxyserver, der dies erfordert.	–	String	Nein
QueryDialect	Der SQL-Dialekt für die Ausführung von Abfragen. 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 schreibgeschützten Drive-Bereich hinzu, wenn er auf 1 festgelegt 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-Mail-Adressen in der Imitierungskette.	–	String	Nein
ServiceAccountImpersonationEmail	Die E-Mail-Adresse des Dienstkontos, dessen Identität angenommen 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 imitierte Konto 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 für die Eigenschaft SSLTrustStore verwendete JCE-Anbieter (Java Cryptography Extension).	–	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 in der Property SSLTrustStore angegeben ist (z. B. JKS, PKCS12 oder ROTKS).	–	String	Nein
SWA_ActivationRowCount	Der Grenzwert 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 das Zeitlimit überschritten wird.	0	Lang	Nein
UniverseDomain	Die Top-Level-Domain, die den Google Cloud -Ressourcen Ihrer Organisation zugeordnet ist.	googleapis.com	String	Nein
UnsupportedHTAPIFallback	Gibt an, 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	Gibt an, ob der Treiber GlobalOpenTelemetry.get() für die Instrumentierung verwendet. Weitere Informationen finden Sie unter OpenTelemetry.	FALSE	Boolesch	Nein
UseQueryCache	Aktiviert das Zwischenspeichern von Abfragen.	TRUE	Boolesch	Nein

Abfragen mit dem Treiber ausführen

Nachdem Ihre Java-Anwendung über den JDBC-Treiber mit BigQuery verbunden ist, können Sie Abfragen in Ihrer Entwicklungsumgebung über den Standard-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-Funktionen ü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 von 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 Strukturobjekt 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 Standardarray 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 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-Insert

Im folgenden Beispiel wird ein Bulk-Insert-Vorgang mit der executeBatch-Methode 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 die Protokollierung aktivieren, indem Sie Verbindungseigenschaften oder Umgebungsvariablen festlegen. Die Protokollierung kann sich auf die Leistung auswirken und Speicherplatz belegen. Aktivieren Sie sie daher nur vorübergehend, um ein Problem zu erfassen.

Protokollebenen

Mit der Eigenschaft LogLevel wird die Detailgenauigkeit festgelegt, die 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

Für die allgemeine Fehlerbehebung empfehlen wir Stufe 6. 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 die Protokollierung 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 den Protokollierungsgrad und den Protokollierungspfad 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 beispielsweise in einer Linux- oder macOS-Umgebung 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.

Nachverfolgte 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 Bereich mit dem Namen BigQueryStatement.pagination erstellt.
• Kontextweitergabe: Der JDBC-Treiber gibt den aktiven Kontext an das zugrunde liegende google-cloud-bigquery SDK weiter. Spans, die vom SDK generiert werden (z. B. HTTP-RPC-Aufrufe), werden automatisch als untergeordnete Elemente der JDBC-Spans angezeigt. So entsteht eine vollständige End-to-End-Trace-Hierarchie.

Konfigurationsmodi

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

Von der Anwendung verwaltete Telemetrie

Wenn Ihre Anwendung bereits OpenTelemetry verwendet, können Sie Ihre OpenTelemetry-Instanz in den JDBC-Treiber einschleusen, um sicherzustellen, dass die Telemetrie des Treibers mit der Telemetrie Ihrer Anwendung korreliert wird.

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.

Um die globale Instanz zu aktivieren, legen Sie die Verbindungseigenschaft UseGlobalOpenTelemetry auf TRUE fest.

Telemetrie ohne Konfiguration Google Cloud

Wenn Sie Google Cloud verwenden und eine schnelle Einrichtung wünschen, können Sie den automatischen Export von Traces und Logs in die Google Cloud -Beobachtbarkeit (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 ein Beispiel für eine 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. Detaillierte 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 Aspekte in Bezug auf das Logging-Verhalten, die Authentifizierung und die Preisgestaltung.

Interaktion mit LogLevel

Die vorhandene Verbindungseigenschaft LogLevel fungiert als primäre Voraussetzung für die Protokollierung.

• Wenn LogLevel=0 (AUS) festgelegt ist, werden keine Logeinträge generiert. Folglich werden keine Logs mit OpenTelemetry oder in 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 die Telemetrie

Der Telemetrieexport (sowohl Tracing als auch Logging) mit dem automatischenGoogle Cloud -Fallback unterstützt sowohl Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) als auch explizite Dienstkontoanmeldedaten, die über GcpTelemetryCredentials bereitgestellt werden.

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

Erforderliche APIs und IAM-Berechtigungen

Damit Telemetriedaten erfolgreich in Google Cloud observability geschrieben werden können, müssen Sie die folgenden Schritte in Ihrem Zielprojekt Google Cloud ausführen:

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

Preise und Abrechnung

Bei der Verwendung der Telemetrie ohne Konfiguration Google Cloud (EnableGcpTraceExporter=true oder EnableGcpLogExporter=true) werden Telemetriedaten an Trace und Logging gesendet. Für diese Dienste können je nach Menge der aufgenommenen Daten Gebühren anfallen. Weitere Informationen finden Sie unter Google Cloud Observability.

Messwerte

Diese Integration unterstützt keine OpenTelemetry-Messwerte.

Verschleierung von Abhängigkeiten

Um Classpath-Konflikte mit Ihrer Anwendung zu vermeiden, werden die OpenTelemetry SDK- und Exportabhängigkeiten des Treibers verschleiert. Die OpenTelemetry API bleibt unverschleiert, um die Interoperabilität mit dem von Ihrer Anwendung bereitgestellten SDK zu ermöglichen.

Korrelation zwischen Logging und Traces

Wenn OpenTelemetry aktiviert ist, werden Logs automatisch mit Traces korreliert:

• db.connection_id: Wird als Spannenattribut an alle JDBC-Spannen angehängt.
• jdbc.connection_id: Wird als Gepäckschlüssel verwendet und als Label an alle Logeinträge angehängt, die vom Treiber an Logging ausgegeben werden.
• Trace-ID und Span-ID: Logs, die im Rahmen der Ausführung einer Abfrage 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

• Weitere Informationen zum ODBC-Treiber für BigQuery
• Weitere BigQuery-Entwicklertools