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:
- Der Treiber ist spezifisch für BigQuery und kann nicht mit anderen Produkten oder Diensten verwendet werden.
- Der Datentyp
INTERVALwird von der BigQuery Storage Read API nicht unterstützt. - Es gelten alle Einschränkungen für die Datenbearbeitungssprache (DML).
Hinweis
- Sie sollten mit JDBC-Treibern, Apache Maven und dem Paket
java.sqlvertraut sein. - 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.
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.comOAuthServiceAcctEmailDienstkontoschlüssel (JSON-Objekt) my-sa-keyOAuthPvtKeyDienstkontoschlüsseldatei Dienstkontoschlüsseldatei (vollständiger Pfad) path/to/file/secret.jsonOAuthPvtKeyPathGoogle-Nutzerkonto Client-ID 123-abc.apps.googleusercontent.comOAuthClientIdClientschlüssel _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uVOAuthClientSecretVorgeneriertes Zugriffstoken Zugriffstoken ya29.a0AfH6SMCiH1L-x_yZOAuthAccessTokenVorgeneriertes Aktualisierungstoken Aktualisierungstoken 1/fFAGRNJru1FTz70BzhT3ZgOAuthRefreshTokenClient-ID 123-abc.apps.googleusercontent.comOAuthClientIdClientschlüssel _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uVOAuthClientSecretStandardanmeldedaten für Anwendungen Keine – – Konfigurationsdatei Konfigurationsdatei (JSON-Objekt oder vollständiger Pfad) path/to/file/secret.jsonOAuthPvtKeyKonfigurationsobjekt für externes Konto Kontokonfigurationsobjekt external_account_configuration_objectOAuthPvtKeySonstiges Attribut „Audience“ der Konfigurationsdatei für das externe Konto //iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-providerBYOID_AudienceUriDatei für Tokenabruf und Umgebungsinformationen {\"file\":\"/path/to/file\"}BYOID_CredentialSourceNutzerprojekt (nur bei Verwendung eines Workforce-Pools) my_projectBYOID_PoolUserProjectURI für die Identitätsübernahme des Dienstkontos (nur bei Verwendung eines Workforce-Pools) my-saBYOID_SA_Impersonation_UriSecurity Token Service-Token basierend auf der Tokenaustauschspezifikation urn:ietf:params:oauth:tokentype:id_tokenBYOID_SubjectTokenTypeToken-Austauschendpunkt des Security Token Service https://sts.googleapis.com/v1/tokenBYOID_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:
- Laden Sie die Version 1.6.0 des Treibers herunter.
- 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:
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-Nutzerkonten2: für die Authentifizierung mit einem vorab generierten Aktualisierungs- oder Zugriffstoken3: für die Authentifizierung mit Standardanmeldedaten für Anwendungen4: für andere Authentifizierungsmethoden
AUTH_PROPS: die Authentifizierungsinformationen, die Sie bei der Authentifizierung bei BigQuery notiert haben, im Formatproperty_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 Formatproperty_1=value_1; property_2=value_2;.... Eine vollständige Liste der Verbindungseigenschaften finden Sie unter Verbindungseigenschaften.
Verbinden Sie Ihre Java-Anwendung mit dem JDBC-Treiber für BigQuery entweder mit der Klasse
DriverManageroderDataSource.Stellen Sie eine Verbindung zur Klasse
DriverManagerher:import java.sql.Connection; import java.sql.DriverManager; private static Connection getJdbcConnectionDM(){ Connection connection = DriverManager.getConnection(CONNECTION_STRING); return connection; }
Ersetzen Sie
CONNECTION_STRINGdurch den Verbindungsstring aus dem vorherigen Schritt.Stellen Sie eine Verbindung zur Klasse
DataSourceher: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_STRINGdurch den Verbindungsstring aus dem vorherigen Schritt.Die Klasse
DataSourcehat 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: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:
|
– | 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:
|
-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:SEVERE2:WARNING3:INFO4:CONFIG5:FINE6:FINER7:FINEST8: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()) undBigQueryPreparedStatement(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.paginationerstellt. - Kontextweitergabe: Der JDBC-Treiber gibt den aktiven Kontext an das zugrunde liegende
google-cloud-bigquerySDK 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=trueEnableGcpLogExporter=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.
EnableGcpLogExporterEnableGcpTraceExporterGcpTelemetryCredentialsGcpTelemetryProjectIdUseGlobalOpenTelemetry
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 wennEnableGcpLogExporter=true. - Wenn Sie OTel-Logging aktivieren möchten, muss
LogLevelauf einen Wert größer als 0 festgelegt sein (z. B.5fü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 mitProxyHostundProxyPortkonfiguriert 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:
- Aktivieren Sie die APIs:
- Aktivieren Sie die Cloud Trace API (
cloudtrace.googleapis.com). - Aktivieren Sie die Cloud Logging API (
logging.googleapis.com).
- Aktivieren Sie die Cloud Trace API (
- 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.
- Zum Exportieren von Traces: Weisen Sie dem Hauptkonto oder Dienstkonto die Rolle „Trace-Agent“ (
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_idundspan_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 Einrichtungsanleitungen, Referenzhandbücher für Verbindungs-URL-Attribute, Codebeispiele und Anleitungen für lokale Builds finden Sie im Open-Source-Repository auf GitHub:
- Weitere Informationen zum ODBC-Treiber für BigQuery
- Weitere BigQuery-Entwicklertools kennenlernen