Utilizza il driver JDBC per BigQuery

Il driver Java Database Connectivity (JDBC) per BigQuery connette le tue applicazioni Java a BigQuery, consentendoti di utilizzare le funzionalità di BigQuery con gli strumenti e l'infrastruttura che preferisci. Per connettere applicazioni non Java a BigQuery, utilizza il driver Open Database Connectivity (ODBC) per BigQuery.

Limitazioni

Il driver JDBC per BigQuery è soggetto alle seguenti limitazioni:

• Il driver è specifico per BigQuery e non può essere utilizzato con altri prodotti o servizi.
• Il tipo di dati INTERVAL non è supportato con l'API BigQuery Storage Read.
• Si applicano tutte le limitazioni del data manipulation language (DML).

Prima di iniziare

1. Assicurati di avere familiarità con i driver JDBC, Apache Maven e il pacchetto java.sql.
2. Verifica che il sistema sia configurato con Java Runtime Environment (JRE) 8.0 o versioni successive. Per informazioni su come controllare la versione di JRE, consulta Verifica dell'ambiente JRE.

3. Autenticati in BigQuery e prendi nota delle seguenti informazioni, che verranno utilizzate in un secondo momento per stabilire una connessione con il driver JDBC per BigQuery. Devi solo annotare le informazioni corrispondenti al metodo di autenticazione che utilizzi.

   Metodo di autenticazione	Informazioni di autenticazione	Esempio	Proprietà di connessione (da impostare in un secondo momento)
   Account di servizio standard	Email dell'account di servizio	[e-mail]	OAuthServiceAcctEmail
   	Chiave del service account (oggetto JSON)	my-sa-key	OAuthPvtKey
   File della chiave del service account	File della chiave del service account (percorso completo)	path/to/file/secret.json	OAuthPvtKeyPath
   Account utente Google	ID client	123-abc.apps.googleusercontent.com	OAuthClientId
   	Client secret	_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV	OAuthClientSecret
   Token di accesso pregenerato	Token di accesso	ya29.a0AfH6SMCiH1L-x_yZ	OAuthAccessToken
   Token di aggiornamento pregenerato	Token di aggiornamento	1/fFAGRNJru1FTz70BzhT3Zg	OAuthRefreshToken
   	ID client	123-abc.apps.googleusercontent.com	OAuthClientId
   	Client secret	_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV	OAuthClientSecret
   Credenziali predefinite dell'applicazione	Nessuno	N/D	N/D
   File di configurazione	File di configurazione (oggetto JSON o percorso completo)	path/to/file/secret.json	OAuthPvtKey
   Oggetto di configurazione dell'account esterno	Oggetto di configurazione dell'account	external_account_configuration_object	OAuthPvtKey
   Altro	Proprietà Audience del file di configurazione dell'account esterno	//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider	BYOID_AudienceUri
   	File di recupero dei token e informazioni sull'ambiente	{\"file\":\"/path/to/file\"}	BYOID_CredentialSource
   	Progetto utente (solo se utilizzi un pool di forza lavoro)	my_project	BYOID_PoolUserProject
   	URI per la simulazione dell'identità dei account di servizio (solo se utilizzi un pool di forza lavoro)	my-sa	BYOID_SA_Impersonation_Uri
   	Token del servizio token di sicurezza basato sulla specifica di scambio dei token	urn:ietf:params:oauth:tokentype:id_token	BYOID_SubjectTokenType
   	Endpoint di scambio di token di Security Token Service	https://sts.googleapis.com/v1/token	BYOID_TokenUri

Installa e configura il driver JDBC

Puoi installare e configurare il driver JDBC per BigQuery scaricando direttamente il file uber-JAR o utilizzando Maven.

Configurazione del download diretto

Per configurare il driver JDBC tramite download diretto:

1. Scarica la versione 1.6.0 del driver.
2. Copia il file scaricato nella posizione specificata dal software.

Per informazioni sulle modifiche alle funzionalità e sugli aggiornamenti del workflow, consulta il log delle modifiche.

Versioni precedenti del driver JDBC per BigQuery

• 1.5.0
• 1.4.0
• 1.3.0
• 1.2.0
• 1.1.0
• 1.0.0

Configurazione Maven

Il driver JDBC per BigQuery è disponibile su Maven Central.

Per configurare l'ambiente di sviluppo con il driver JDBC, aggiungi il driver come dipendenza al progetto:

Maven

Aggiungi la seguente dipendenza al file pom.xml:

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

Maven con uber-JAR

Aggiungi la seguente dipendenza al file pom.xml:

<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

Aggiungi quanto segue al tuo file build.gradle:

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

Stabilisci una connessione

Per stabilire una connessione tra la tua applicazione Java e BigQuery con il driver JDBC per BigQuery, segui questi passaggi:

1. Identifica la stringa di connessione per il driver JDBC per BigQuery. Questa stringa acquisisce tutte le informazioni necessarie per stabilire una connessione tra l'applicazione Java e BigQuery. La stringa di connessione ha il seguente formato:

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

   Sostituisci quanto segue:

   • HOST: il DNS o l'indirizzo IP del server.
   • PORT: il numero di porta TCP.
   • PROJECT_ID: l'ID del tuo progetto BigQuery.
   • AUTH_TYPE: un numero che specifica il tipo di autenticazione che hai utilizzato. Uno dei seguenti:
     • 0: per l'autenticazione del account di servizio (standard e file di chiavi)
     • 1: per l'autenticazione dell'account utente Google
     • 2: per l'autenticazione con token di accesso o di aggiornamento pregenerato
     • 3: per l'autenticazione delle credenziali predefinite dell'applicazione
     • 4: per altri metodi di autenticazione
   • AUTH_PROPS: le informazioni di autenticazione che hai annotato quando hai eseguito l'autenticazione in BigQuery, elencate nel formato property_1=value_1; property_2=value_2;..., ad esempio OAuthPvtKeyPath=path/to/file/secret.json, se hai eseguito l'autenticazione con un file della chiave del account di servizio.
   • OTHER_PROPS (facoltativo): proprietà di connessione aggiuntive per il driver JDBC, elencate nel formato property_1=value_1; property_2=value_2;.... Per un elenco completo delle proprietà di connessione, consulta Proprietà di connessione.

2. Connetti la tua applicazione Java al driver JDBC per BigQuery con la classe DriverManager o DataSource.

   • Connettiti con la classe DriverManager:

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

     Sostituisci CONNECTION_STRING con la stringa di connessione del passaggio precedente.

   • Connettiti con la classe DataSource:

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

     Sostituisci CONNECTION_STRING con la stringa di connessione del passaggio precedente.

     La classe DataSource ha anche metodi setter che puoi utilizzare per impostare le proprietà di connessione, anziché includerle nella stringa di connessione. Ecco un esempio:

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

Proprietà di connessione

Le proprietà di connessione del driver JDBC sono parametri di configurazione che includi nella stringa di connessione o passi tramite i metodi setter quando stabilisci una connessione a un database. Le seguenti proprietà di connessione sono supportate dal driver JDBC per BigQuery.

Nota: i nomi di tutte le proprietà di connessione non fanno distinzione tra maiuscole e minuscole. Le proprietà di connessione booleane accettano sia TRUE/FALSE sia 1/0.

Proprietà della connessione	Descrizione	Valore predefinito	Tipo di dati	Obbligatorio
AdditionalProjects	Progetti a cui il driver può accedere per query e operazioni sui metadati, oltre al progetto principale impostato dalla proprietà ProjectId.	N/D	Stringa separata da virgole	No
AllowLargeResults	Determina se il driver elabora i risultati delle query di dimensioni superiori a 128 MB quando la proprietà QueryDialect è impostata su BIG_QUERY. Se la proprietà QueryDialect è impostata su SQL, il driver elabora sempre risultati di query di grandi dimensioni.	TRUE	Booleano	No
BYOID_AudienceUri	La proprietà audience in un file di configurazione dell'account esterno. La proprietà audience può contenere il nome della risorsa per il pool di identità del workload o il pool di forza lavoro, nonché l'identificatore del provider in quel pool.	N/D	Stringa	Solo quando OAuthType=4
BYOID_CredentialSource	Il recupero del token e le informazioni sull'ambiente.	N/D	Stringa	Solo quando OAuthType=4
BYOID_PoolUserProject	Il progetto utente quando viene utilizzato un pool di forza lavoro per l'autenticazione.	N/D	Stringa	Solo quando OAuthType=4 e utilizzi il pool di forza lavoro
BYOID_SA_Impersonation_Uri	L'URI per la simulazione dell'identità dei account di servizio quando viene utilizzato un pool di forza lavoro per l'autenticazione.	N/D	Stringa	Solo quando OAuthType=4 e utilizzi il pool di forza lavoro
BYOID_SubjectTokenType	Il token di Security Token Service basato sulla specifica di scambio dei token. Uno dei seguenti: 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	Stringa	Solo quando OAuthType=4
BYOID_TokenUri	L'endpoint di scambio di token di Security Token Service.	https://sts.googleapis.com/v1/token	Stringa	No
ConnectionPoolSize	La dimensione del pool di connessioni, se il pooling delle connessioni è abilitato.	10	Lungo	No
DefaultDataset	Il set di dati utilizzato quando non ne viene specificato uno in una query.	N/D	Stringa	No
EnableGcpLogExporter	Determina se il driver esporta automaticamente i log in Cloud Logging (se non viene utilizzata un'istanza OpenTelemetry personalizzata o globale). Per saperne di più, consulta OpenTelemetry.	FALSE	Booleano	No
EnableGcpTraceExporter	Determina se il driver esporta automaticamente le tracce in Cloud Trace (se non viene utilizzata un'istanza OpenTelemetry personalizzata o globale). Per saperne di più, consulta OpenTelemetry.	FALSE	Booleano	No
EnableHighThroughputAPI	Determina se è possibile utilizzare l'API Storage Read. Per utilizzare l'API Storage Read, è necessario impostare anche le proprietà HighThroughputActivationRatio e HighThroughputMinTableSize su TRUE.	FALSE	Booleano	No
EnableProjectDiscovery	Determina se i metodi dei metadati del database rilevano i set di dati in tutti i progetti Google Cloud accessibili. Se impostato su FALSE, il rilevamento è limitato al valore predefinito ProjectId.	FALSE	Booleano	No
EnableSession	Determina se la connessione avvia una sessione. Se impostato su TRUE, l'ID sessione viene passato a tutte le query successive.	FALSE	Booleano	No
EnableTimestampPicos	Determina se il driver recupera i valori TIMESTAMP(12) con precisione al picosecondo. Se impostato su TRUE, i valori TIMESTAMP(12) vengono restituiti come oggetti String formattati in UTC dai metodi getString() e getObject(). Se impostato su FALSE, i valori TIMESTAMP(12) vengono troncati alla precisione di 6 cifre in microsecondi. Questa proprietà non è compatibile con l'SQL precedente (QueryDialect=BIG_QUERY).	FALSE	Booleano	No
EnableWriteAPI	Determina se è possibile utilizzare l'API Storage Write (gRPC). Deve essere impostato su TRUE per abilitare gli inserimenti collettivi.	FALSE	Booleano	No
EndpointOverrides	Endpoint personalizzati per sovrascrivere quanto segue: BIGQUERY=https://bigquery.googleapis.com READ_API=https://bigquerystorage.googleapis.com OAUTH2=https://oauth2.googleapis.com STS=https://sts.googleapis.com	N/D	Stringa separata da virgole	No
FilterTablesOnDefaultDataset	Determina l'ambito dei metadati restituiti dai metodi DatabaseMetaData.getTables() e DatabaseMetaData.getColumns(). Se impostato su FALSE, non viene applicato alcun filtro. Per attivare il filtro, deve essere impostata anche la proprietà DefaultDataset.	FALSE	Booleano	No
GcpTelemetryCredentials	Le credenziali utilizzate per autenticare gli esportatori di telemetria. Accetta un percorso a una chiave JSON del account di servizio o alla stringa JSON non elaborata. Se non impostato, il valore predefinito corrisponde alle credenziali di connessione. Per saperne di più, consulta OpenTelemetry.	N/D	Stringa	No
GcpTelemetryProjectId	L'ID progetto Google Cloud di destinazione per la telemetria. Il valore predefinito è ProjectId principale. Per saperne di più, consulta OpenTelemetry.	N/D	Stringa	No
HighThroughputActivationRatio	La soglia per il numero di pagine in una risposta alla query. Quando questo numero viene superato e le condizioni EnableHighThroughputAPI e HighThroughputMinTableSize sono soddisfatte, il driver inizia a utilizzare l'API Storage Read.	2	Numero intero	No
HighThroughputMinTableSize	La soglia per il numero di righe in una risposta alla query. Quando questo numero viene superato e le condizioni EnableHighThroughputAPI e HighThroughputActivationRatio sono soddisfatte, il driver inizia a utilizzare l'API Storage Read.	10000	Numero intero	No
JobCreationMode	Determina se le query vengono eseguite con o senza job. Un valore 1 indica che i job vengono creati per ogni query, mentre un valore 2 indica che le query possono essere eseguite senza job.	2	Numero intero	No
JobTimeout	Il timeout del job (in secondi) dopo il quale il job viene annullato sul server.	0	Lungo	No
KMSKeyName	Il nome della chiave KMS per la crittografia dei dati.	N/D	Stringa	No
Labels	Etichette associate alla query per organizzare e raggruppare i job di query.	N/D	Map<String, String>	No
LargeResultDataset	Il set di dati di destinazione per i risultati di query di grandi dimensioni, solo quando è impostata la proprietà LargeResultTable. Quando imposti questa proprietà, le scritture dei dati bypassano la cache dei risultati e attivano la fatturazione per ogni query, anche se i risultati sono di piccole dimensioni.	_google_jdbc	Stringa	No
LargeResultsDatasetExpirationTime	La durata di tutte le tabelle in un set di dati di risultati di grandi dimensioni, in millisecondi. Questa proprietà viene ignorata se il set di dati ha già un tempo di scadenza predefinito impostato.	3600000	Lungo	No
LargeResultTable	La tabella di destinazione per i risultati di query di grandi dimensioni, solo quando la proprietà LargeResultDataset è impostata. Quando imposti questa proprietà, le scritture di dati bypassano la cache dei risultati e attivano la fatturazione per ogni query, anche se i risultati sono di piccole dimensioni.	temp_table...	Stringa	No
ListenerPoolSize	La dimensione del pool di listener, se il pooling delle connessioni è abilitato.	10	Lungo	No
Location	La località in cui vengono creati o interrogati i set di dati. BigQuery determina automaticamente la località se questa proprietà non è impostata.	N/D	Stringa	No
LogLevel	Il livello di dettaglio registrato dal driver. Per saperne di più, consulta Logging.	0	Numero intero	No
LogPath	La directory in cui vengono scritti i file di log.	N/D	Stringa	No
MaximumBytesBilled	Il limite di byte fatturati. Le query con byte fatturati superiori a questo numero non riescono senza comportare addebiti.	0	Lungo	No
MaxResults	Il numero massimo di risultati per pagina.	10000	Lungo	No
MetaDataFetchThreadCount	Il numero di thread utilizzati per i metodi dei metadati del database.	32	Numero intero	No
OAuthAccessToken	Il token di accesso utilizzato per l'autenticazione con token di accesso pregenerato.	N/D	Stringa	Solo quando OAUTH_TYPE=2
OAuthClientId	L'ID client per l'autenticazione del token di aggiornamento pregenerato e l'autenticazione dell'account utente.	N/D	Stringa	Solo quando OAUTH_TYPE=1 o OAUTH_TYPE=2
OAuthClientSecret	Il client secret per l'autenticazione del token di aggiornamento pregenerato e l'autenticazione dell'account utente.	N/D	Stringa	Solo quando OAUTH_TYPE=1 o OAUTH_TYPE=2
OAuthP12Password	La password del file della chiave PKCS12.	notasecret	Stringa	No
OAuthPvtKey	La chiave del account di servizio quando utilizzi l'autenticazione del account di servizio. Questo valore può essere un oggetto file di chiavi JSON non elaborato o un percorso al file di chiavi JSON.	N/D	Stringa	Solo quando OAUTH_TYPE=0 e il valore OAuthPvtKeyPath non sono impostati
OAuthPvtKeyPath	Il percorso della chiave del account di servizio quando utilizzi l'autenticazione del account di servizio.	N/D	Stringa	Solo quando OAUTH_TYPE=0 e i valori OAuthPvtKey e OAuthServiceAcctEmail non sono impostati
OAuthRefreshToken	Il token di aggiornamento per l'autenticazione con token di aggiornamento pregenerato.	N/D	Stringa	Solo quando OAUTH_TYPE=2
OAuthServiceAcctEmail	L'indirizzo email del account di servizio quando utilizzi l'autenticazione del account di servizio.	N/D	Stringa	Solo quando OAUTH_TYPE=0 e il valore OAuthPvtKeyPath non sono impostati
OAuthType	Il tipo di autenticazione. Uno dei seguenti: 0: autenticazione del account di servizio 1: autenticazione dell'account utente 2: autenticazione con token di aggiornamento o token di accesso pregenerato 3: autenticazione con credenziali predefinite dell'applicazione 4: altri metodi di autenticazione	-1	Numero intero	Sì
PartnerToken	Un token utilizzato dai partner Google Cloud per monitorare l'utilizzo del driver.	N/D	Stringa	No
ProjectId	L'ID progetto predefinito per il driver. Questo progetto viene utilizzato per eseguire query e viene fatturato per l'utilizzo delle risorse. Se non viene impostato, il driver deduce un ID progetto.	N/D	Stringa	No, ma vivamente consigliato
ProxyHost	Il nome host o l'indirizzo IP di un server proxy tramite il quale viene instradata la connessione JDBC.	N/D	Stringa	No
ProxyPort	Il numero di porta su cui il server proxy è in ascolto per le connessioni.	N/D	Stringa	No
ProxyPwd	La password per l'autenticazione quando ci si connette tramite un server proxy che la richiede.	N/D	Stringa	No
ProxyUid	Il nome utente per l'autenticazione durante la connessione tramite un server proxy che la richiede.	N/D	Stringa	No
QueryDialect	Il dialetto SQL per l'esecuzione delle query. Utilizza SQL per GoogleSQL (vivamente consigliato) e BIG_QUERY per l'SQL precedente.	SQL	Stringa	No
QueryProperties	Proprietà di connessione REST che personalizzano il comportamento delle query.	N/D	Map<String, String>	No
RequestGoogleDriveScope	Aggiunge l'ambito di Drive di sola lettura alla connessione se impostato su 1.	0	Numero intero	No
RetryInitialDelay	Imposta il ritardo (in secondi) prima del primo nuovo tentativo.	0	Lungo	No
RetryMaxDelay	Imposta il limite massimo (in secondi) per il ritardo dei nuovi tentativi.	0	Lungo	No
ServiceAccountImpersonationChain	Un elenco separato da virgole di indirizzi email dei account di servizio nella catena di simulazione.	N/D	Stringa	No
ServiceAccountImpersonationEmail	L'indirizzo email del account di servizio di cui simulare l'identità.	N/D	Stringa	No
ServiceAccountImpersonationScopes	Un elenco separato da virgole di ambiti OAuth2 da utilizzare con l'account di cui è stata simulata l'identità.	https://www.googleapis.com/auth/bigquery	Stringa	No
ServiceAccountImpersonationTokenLifetime	La durata del token dell'account di cui è stata eseguita la simulazione (in secondi).	3600	Numero intero	No
SSLTrustStore	Il percorso completo del TrustStore Java che contiene i certificati delle autorità di certificazione (CA) attendibili. Il driver utilizza questo truststore per convalidare l'identità del server durante l'handshake SSL/TLS.	N/D	Stringa	No
SSLTrustStoreProvider	Il provider Java Cryptography Extension (JCE) utilizzato per la proprietà SSLTrustStore.	N/D	Stringa	No
SSLTrustStorePwd	La password del truststore Java specificato nella proprietà SSLTrustStore.	N/D	Stringa	Solo se il TrustStore Java è protetto da password
SSLTrustStoreType	Il formato del file truststore specificato nella proprietà SSLTrustStore (ad esempio JKS, PKCS12 o ROTKS).	N/D	Stringa	No
SWA_ActivationRowCount	La soglia di executeBatch insert righe che, se superata, fa sì che il connettore passi all'API Storage Write (gRPC).	3	Numero intero	No
SWA_AppendRowCount	Le dimensioni dello stream di scrittura.	1000	Numero intero	No
Timeout	Il periodo di tempo, in secondi, durante il quale il connettore riprova una chiamata API non riuscita prima del timeout.	0	Lungo	No
UniverseDomain	Il dominio di primo livello associato alle risorse Google Cloud della tua organizzazione.	googleapis.com	Stringa	No
UnsupportedHTAPIFallback	Determina se il connettore esegue il fallback all'API REST (se impostato su TRUE) o restituisce un errore (se impostato su FALSE).	TRUE	Booleano	No
UseGlobalOpenTelemetry	Determina se il driver utilizza GlobalOpenTelemetry.get() per la strumentazione. Per saperne di più, consulta OpenTelemetry.	FALSE	Booleano	No
UseQueryCache	Abilita la memorizzazione nella cache delle query.	TRUE	Booleano	No

Esegui query con il driver

Con l'applicazione Java connessa a BigQuery tramite il driver JDBC, ora puoi eseguire query nel tuo ambiente di sviluppo tramite il processo JDBC standard. Si applicano tutte le quote e i limiti di BigQuery.

Mappatura dei tipi di dati

Quando esegui query tramite il driver JDBC per BigQuery, si verifica la seguente mappatura dei tipi di dati:

Tipo GoogleSQL	Tipo Java
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

Esempi

Le sezioni seguenti forniscono esempi che utilizzano le funzionalità di BigQuery tramite il driver JDBC per BigQuery.

Parametri posizionali

L'esempio seguente esegue una query con un parametro posizionale:

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

Record nidificati e ripetuti

L'esempio seguente esegue una query sul record di base dei dati Struct:

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

Il driver restituisce il record di base come oggetto struct o come rappresentazione di stringa di un oggetto JSON. Il risultato è simile al seguente:

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

L'esempio seguente esegue una query sui componenti secondari di un oggetto Struct:

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

L'esempio seguente esegue una query su un array standard di dati ripetuti, quindi verifica il risultato:

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

L'esempio seguente esegue una query su un array Struct di dati ripetuti, quindi verifica il risultato:

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

Inserimento collettivo

L'esempio seguente esegue un'operazione di inserimento collettivo con il metodo executeBatch.

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

Per risolvere i problemi relativi al driver JDBC per BigQuery, puoi attivare il logging impostando le proprietà di connessione o le variabili di ambiente. Il logging può influire sulle prestazioni e occupare spazio su disco, quindi attivalo solo temporaneamente per acquisire un problema.

Livelli di log

La proprietà LogLevel determina il livello di dettaglio registrato dal pacchetto java.util.logging:

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

Consigliamo il livello 6 per la risoluzione dei problemi generali. I livelli 7 e 8 sono limitati alle operazioni ResultSet e generano un volume elevato di log.

Abilita il logging nella stringa di connessione

Per attivare il logging nella stringa di connessione, aggiungi le proprietà di connessione LogLevel e LogPath, ad esempio:

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

Abilita il logging con le variabili di ambiente

Se lo strumento per sviluppatori non consente la modifica della stringa di connessione, puoi anche impostare il livello e il percorso di log con le seguenti variabili di ambiente prima di eseguire l'applicazione:

• BIGQUERY_JDBC_LOG_LEVEL: il livello di log (0-8).
• BIGQUERY_JDBC_LOG_PATH: la directory dei file di log.

Ad esempio, in un ambiente Linux o macOS, esegui questo comando:

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

OpenTelemetry

Il driver JDBC per BigQuery supporta OpenTelemetry (OTel) per fornire il tracciamento e il logging distribuiti, che ti consentono di monitorare le prestazioni delle interazioni con il database e risolvere i problemi in modo efficace.

Operazioni tracciate

Quando OpenTelemetry è abilitato, il driver genera intervalli per le seguenti operazioni:

• Esecuzione delle query: gli intervalli vengono generati per BigQueryStatement (execute(), executeQuery(), executeLargeUpdate(), executeBatch()) e BigQueryPreparedStatement (execute(), executeQuery(), executeLargeUpdate()).
• Operazioni sui metadati: gli intervalli vengono generati per metodi DatabaseMetaData specifici (getCatalogs(), getSchemas(), getTables(), getColumns()).
• Paginazione: i recuperi asincroni per pagine di risultati aggiuntive (quando si utilizza il percorso dell'API REST) vengono tracciati e collegati in modo causale allo span di esecuzione della query originale utilizzando i link agli span di OpenTelemetry. Per queste operazioni viene creato un intervallo denominato BigQueryStatement.pagination.
• Propagazione del contesto: il driver JDBC propaga il contesto attivo all'SDK google-cloud-bigquery sottostante. Di conseguenza, gli intervalli generati dall'SDK (come le chiamate RPC HTTP) vengono visualizzati automaticamente come elementi secondari degli intervalli JDBC, fornendo una gerarchia di tracce end-to-end completa.

Modalità di configurazione

Puoi configurare OpenTelemetry nel driver JDBC utilizzando una delle seguenti modalità, a seconda dell'architettura e dei requisiti della tua applicazione.

Telemetria gestita dall'applicazione

Se la tua applicazione utilizza già OpenTelemetry, puoi inserire la tua istanza OpenTelemetry nel driver JDBC per assicurarti che la telemetria del driver sia correlata a quella della tua applicazione.

Per farlo, utilizza l'API BigQueryDataSource:

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

Supporto globale di OpenTelemetry

Se hai inizializzato OpenTelemetry a livello globale nella tua applicazione (ad esempio, utilizzando l'agente Java OpenTelemetry o chiamando la funzione GlobalOpenTelemetry.set()), puoi configurare il driver in modo che utilizzi questa istanza globale.

Per abilitare l'istanza globale, imposta la proprietà di connessione UseGlobalOpenTelemetry su TRUE.

Telemetria Google Cloud senza configurazione

Se utilizzi Google Cloud e vuoi una configurazione rapida, puoi attivare l'esportazione automatica di tracce e log nell'osservabilità di Google Cloud (Trace e Logging).

Per attivare questa esportazione, imposta le seguenti proprietà di connessione nell'URL JDBC:

• EnableGcpTraceExporter=true
• EnableGcpLogExporter=true

Di seguito è riportato un URL di connessione di esempio:

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

Proprietà di connessione OpenTelemetry

Per OpenTelemetry sono supportate le seguenti proprietà di connessione. Per descrizioni dettagliate e valori predefiniti, consulta Proprietà di connessione.

• EnableGcpLogExporter
• EnableGcpTraceExporter
• GcpTelemetryCredentials
• GcpTelemetryProjectId
• UseGlobalOpenTelemetry

Considerazioni importanti

Quando esegui il deployment dell'integrazione di OpenTelemetry, tieni presente le seguenti considerazioni relative al comportamento di logging, all'autenticazione, alla configurazione del proxy e ai prezzi.

Interazione con LogLevel

La proprietà di connessione LogLevel esistente funge da gatekeeper principale per il logging.

• Se è impostato LogLevel=0 (OFF), non vengono generati record di log. Di conseguenza, non vengono esportati log utilizzando OpenTelemetry o in Logging, anche se EnableGcpLogExporter=true.
• Per attivare il logging OTel, assicurati che LogLevel sia impostato su un valore maggiore di 0 (ad esempio, 5 per i log dettagliati).

Autenticazione per la telemetria

L'esportazione della telemetria (sia il tracciamento che il logging) con il fallback automaticoGoogle Cloud supporta sia le Credenziali predefinite dell'applicazione (ADC) sia le credenziali esplicite del service account fornite utilizzandoGcpTelemetryCredentials.

Quando viene fornito GcpTelemetryProjectId o GcpTelemetryCredentials, sia i log che le tracce vengono inviati allo stesso progetto di destinazione specificato utilizzando le stesse credenziali configurate.

Configurazione del proxy con OpenTelemetry e logging

Se la tua applicazione si connette a BigQuery tramite un server proxy, il driver gestisce il routing del proxy come segue:

• Esportazione di tracce (HTTP). Quando utilizzi il protocollo HTTP predefinito per l'esportazione delle tracce OpenTelemetry (otel.exporter.otlp.protocol=http/protobuf), il driver instrada automaticamente il traffico di esportazione delle tracce tramite il proxy configurato nelle proprietà di connessione utilizzando ProxyHost e ProxyPort.

• Esportazione dei log e telemetria gRPC. L'esportatore automatico di log Google Cloud (EnableGcpLogExporter=true) e gli esportatori OpenTelemetry basati su gRPC (otel.exporter.otlp.protocol=grpc) utilizzano gRPC, che non supporta la configurazione del proxy per connessione. Per instradare il traffico di esportazione dei log e di telemetria gRPC tramite un server proxy, configura le impostazioni del proxy a livello di JVM utilizzando le seguenti proprietà di sistema:

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

API e autorizzazioni IAM richieste

Per scrivere correttamente i dati di telemetria nell'osservabilità di Google Cloud , esegui la seguente configurazione nel progetto Google Cloud di destinazione:

1. Abilita le API:
   • Abilita l'Cloud Trace API (cloudtrace.googleapis.com).
   • Abilita l'API Cloud Logging (logging.googleapis.com).
2. Concedi i ruoli IAM:
   • Per esportare le tracce: concedi all'entità o account di servizio il ruolo Trace Agent (roles/cloudtrace.agent).
   • Per esportare i log: concedi all'entità o account di servizio il ruolo Writer log (roles/logging.logWriter).

Prezzi e fatturazione

Quando utilizzi la telemetria Google Cloud con configurazione zero (EnableGcpTraceExporter=true o EnableGcpLogExporter=true), i dati di telemetria vengono inviati a Trace e Logging. Questi servizi potrebbero comportare addebiti in base al volume di dati acquisiti. Per saperne di più, consulta Google Cloud Observability.

Metriche

Questa integrazione non supporta le metriche OpenTelemetry.

Ombreggiatura delle dipendenze

Per evitare conflitti di classpath con l'applicazione, il driver oscura le dipendenze dell'SDK OpenTelemetry e dell'esportatore. L'API OpenTelemetry rimane non ombreggiata per consentire l'interoperabilità con l'SDK fornito dall'applicazione.

Correlazione di log e tracce

Quando OpenTelemetry è abilitato, il driver mette automaticamente in correlazione i log con le tracce:

• db.connection_id: collegato come attributo span a tutti gli span JDBC.
• jdbc.connection_id: utilizzata come chiave di bagaglio e allegata come etichetta a tutte le voci di log emesse dal driver in Logging.
• ID traccia e ID intervallo: i log generati nell'ambito dell'esecuzione di una query includono automaticamente i valori trace_id e span_id attivi.

Prezzi

Puoi scaricare il driver JDBC per BigQuery senza costi. Tuttavia, quando utilizzi il driver, si applicano i prezzi standard di BigQuery.

Passaggi successivi

• Per ulteriori istruzioni di configurazione, manuali di riferimento delle proprietà dell'URL di connessione, esempi di codice e istruzioni di build locale, visita il repository open source su GitHub:
  • Guida dell'utente (docs/USER_GUIDE.md)
  • Guida per gli sviluppatori (DEVELOPMENT.md)
  • Approfondimento sulle API BigQuery Storage (docs/STORAGE_APIS.md)
• Scopri di più sul driver ODBC per BigQuery.
• Esplora altri strumenti per sviluppatori di BigQuery.