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 Simba 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
INTERVALnon è supportato dall'API BigQuery Storage Read. - Si applicano tutte le limitazioni del Data Manipulation Language (DML).
Prima di iniziare
- Assicurati di avere familiarità con i driver JDBC, Apache Maven e
il
pacchetto
java.sql. - 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.
Autenticati in BigQuery e prendi nota delle seguenti informazioni, che verranno utilizzate in un secondo momento quando stabilirai una connessione con il driver JDBC per BigQuery. Devi annotare solo le informazioni corrispondenti al metodo di autenticazione che utilizzi.
Metodo di autenticazione Informazioni di autenticazione Esempio Proprietà della connessione (da impostare in un secondo momento) Account di servizio standard Email dell'account di servizio bq-jdbc-sa@mytestproject.iam.gserviceaccount.comOAuthServiceAcctEmailChiave del service account (oggetto JSON) my-sa-keyOAuthPvtKeyFile della chiave del service account File della chiave del service account (percorso completo) path/to/file/secret.jsonOAuthPvtKeyPathAccount utente Google ID client 123-abc.apps.googleusercontent.comOAuthClientIdClient secret _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uVOAuthClientSecretToken di accesso pregenerato Token di accesso ya29.a0AfH6SMCiH1L-x_yZOAuthAccessTokenToken di aggiornamento pregenerato Token di aggiornamento 1/fFAGRNJru1FTz70BzhT3ZgOAuthRefreshTokenID client 123-abc.apps.googleusercontent.comOAuthClientIdClient secret _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uVOAuthClientSecretCredenziali predefinite dell'applicazione Nessuno N/D N/D File di configurazione File di configurazione (oggetto JSON o percorso completo) path/to/file/secret.jsonOAuthPvtKeyOggetto di configurazione dell'account esterno Oggetto di configurazione dell'account external_account_configuration_objectOAuthPvtKeyAltro Proprietà Segmento di pubblico del file di configurazione dell'account esterno //iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-providerBYOID_AudienceUriFile di recupero dei token e informazioni sull'ambiente {\"file\":\"/path/to/file\"}BYOID_CredentialSourceProgetto utente (solo se utilizzi un pool di forza lavoro) my_projectBYOID_PoolUserProjectURI per la simulazione dell'identità del account di servizio (solo se utilizzi un pool di workforce) my-saBYOID_SA_Impersonation_UriToken del servizio token di sicurezza basato sulla specifica di scambio di token urn:ietf:params:oauth:tokentype:id_tokenBYOID_SubjectTokenTypeEndpoint di scambio token del servizio token di sicurezza https://sts.googleapis.com/v1/tokenBYOID_TokenUri
Configura l'ambiente di sviluppo
Per configurare l'ambiente di sviluppo con il driver JDBC per BigQuery, segui questa procedura:
Scarica uno dei seguenti pacchetti JDBC:
- Uber JAR. Un file JAR con tutte le dipendenze incluse.
- Uber JAR ombreggiato. Un file JAR ombreggiato con tutte le dipendenze incluse.
- Thin JAR con dipendenze. Un file zip che include un file JAR thin e tutte le dipendenze.
Aggiungi il file JAR scaricato al classpath in modo che il compilatore Java e il runtime possano individuare le classi JDBC necessarie. Per informazioni sull'aggiunta di un file al classpath, vedi Impostazione del classpath.
Aggiungi la seguente dipendenza al tuo file di build:
<dependency> <groupId>com.google.cloud</groupId> <artifactId>google-cloud-bigquery-jdbc</artifactId> <version>0.0.1</version> <scope>system</scope> <systemPath>path/to/file/google-jdbc-jar-with-dependencies.jar</systemPath> </dependency>
Se utilizzi un progetto Gradle, aggiungi quanto segue al file di build:
dependencies { // ... other dependencies implementation files('path/to/file/google-jdbc-jar-with-dependencies.jar') }
Stabilire una connessione
Per stabilire una connessione tra l'applicazione Java e BigQuery con il driver JDBC per BigQuery, procedi nel seguente modo:
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 chiave)1: per l'autenticazione dell'account utente Google2: per l'autenticazione con token di accesso o di aggiornamento pregenerati3: per l'autenticazione delle credenziali predefinite dell'applicazione4: per altri metodi di autenticazione
AUTH_PROPS: le informazioni di autenticazione che hai annotato quando ti sei autenticato in BigQuery, elencate nel formatoproperty_1=value_1; property_2=value_2;..., ad esempioOAuthPvtKeyPath=path/to/file/secret.json, se l'autenticazione è stata eseguita con un file di chiave dell'account di servizio.OTHER_PROPS(facoltativo): proprietà di connessione aggiuntive per il driver JDBC, elencate nel formatoproperty_1=value_1; property_2=value_2;.... Per un elenco completo delle proprietà di connessione, consulta Proprietà di connessione.
Connetti la tua applicazione Java al driver JDBC per BigQuery con la classe
DriverManageroDataSource.Connettiti al corso
DriverManager:import java.sql.Connection; import java.sql.DriverManager; private static Connection getJdbcConnectionDM(){ Connection connection = DriverManager.getConnection(CONNECTION_STRING); return connection; }
Sostituisci
CONNECTION_STRINGcon la stringa di connessione del passaggio precedente.Connettiti al corso
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_STRINGcon la stringa di connessione del passaggio precedente.La classe
DataSourcedispone anche di metodi setter che puoi utilizzare per impostare le proprietà di connessione, anziché includerle nella stringa di connessione. Di seguito è riportato 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 che trasmetti tramite i metodi setter quando stabilisci una connessione a un database. Le seguenti proprietà di connessione sono supportate dal driver JDBC per BigQuery.
| 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 della 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 i risultati di query di grandi dimensioni.
|
TRUE |
Booleano | No |
BYOID_AudienceUri |
La proprietà del segmento di pubblico in un file di configurazione dell'account esterno. La proprietà del pubblico 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 si utilizza il pool di forza lavoro |
BYOID_SA_Impersonation_Uri |
L'URI per l'impersonificazione del account di servizio quando viene utilizzato un pool di forza lavoro per l'autenticazione. | N/D | Stringa | Solo quando OAuthType=4 e si utilizza il pool di forza lavoro |
BYOID_SubjectTokenType |
Il token del servizio token di sicurezza basato sulla specifica di scambio di token.
Uno dei seguenti valori:
|
urn:ietf:params:oauth:tokentype:id_token |
Stringa | Solo quando OAuthType=4 |
BYOID_TokenUri |
L'endpoint di scambio dei token del servizio token di sicurezza. | https://sts.googleapis.com/v1/token |
Stringa | No |
ConnectionPoolSize |
Le dimensioni del pool di connessioni, se il pooling di connessioni è abilitato. | 10 |
Lungo | No |
DefaultDataset |
Il set di dati utilizzato quando non ne viene specificato uno in una query. | N/D | Stringa | No |
EnableHighThroughputAPI |
Determina se è possibile utilizzare l'API Storage Read. Per utilizzare l'API Storage Read, devono essere impostate anche le proprietà
HighThroughputActivationRatio e
HighThroughputMinTableSize su
TRUE.
|
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 |
EnableWriteAPI |
Determina se è possibile utilizzare l'API Storage Write. Deve essere
impostato su TRUE per abilitare gli inserimenti collettivi.
|
FALSE |
Booleano | No |
EndpointOverrides |
Endpoint personalizzati per sovrascrivere quanto segue:
|
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 abilitare il filtro, deve essere impostata anche la proprietà DefaultDataset.
|
FALSE |
Booleano | 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 vengono 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 vengono soddisfatte, il driver
inizia a utilizzare l'API Storage Read.
|
100 |
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 criptare i 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 di dati ignorano la cache dei risultati e attivano la fatturazione per ogni query,
anche se i risultati sono piccoli.
|
_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à impostato un tempo di scadenza predefinito. | 3600000 |
Lungo | No |
LargeResultTable |
La tabella di destinazione per i risultati di query di grandi dimensioni, solo quando è impostata la proprietà LargeResultDataset. Quando imposti questa proprietà, le scritture di dati ignorano la cache dei risultati e attivano la fatturazione per ogni query, anche se i risultati sono piccoli.
|
temp_table... |
Stringa | No |
ListenerPoolSize |
Le dimensioni del pool di listener, se il pool di connessioni è abilitato. | 10 |
Lungo | No |
Location |
La località in cui vengono creati o interrogati i set di dati. BigQuery determina automaticamente la posizione se questa proprietà non è impostata. | N/D | Stringa | No |
LogLevel |
Il livello di dettaglio registrato dal pacchetto
java.util.logging
durante le interazioni con il database. Il logging può influire sulle prestazioni, quindi
attivalo solo temporaneamente per acquisire un problema. Uno dei seguenti valori:
|
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 del token di accesso pregenerato. | N/D | Stringa | Solo quando OAUTH_TYPE=2 |
OAuthClientId |
L'ID client per l'autenticazione con 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 con 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 JSON keyfile non elaborato o un percorso del JSON keyfile. | 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 si utilizza l'autenticazione delaccount di serviziot. | 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'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 valori:
|
-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 l'autista. Questo progetto viene utilizzato per eseguire le query e viene fatturato per l'utilizzo delle risorse. Se non è 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 delle connessioni. | N/D | Stringa | No |
ProxyPwd |
La password per l'autenticazione quando la connessione avviene 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 (opzione altamente consigliata) e BIG_QUERY per
SQL precedente.
|
SQL |
Stringa | No |
QueryProperties |
Proprietà di connessione REST che personalizzano il comportamento della query. | N/D | Map<String, String> | No |
RequestGoogleDriveScope |
Aggiunge l'ambito di sola lettura di Drive alla connessione quando è impostato su
1.
|
0 |
Numero intero | No |
RetryInitialDelay |
Imposta il ritardo (in secondi) prima del primo 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 con identità simulata. | https://www.googleapis.com/auth/bigquery |
Stringa | No |
ServiceAccountImpersonationTokenLifetime |
Durata del token dell'account rappresentato (in secondi). | 3600 |
Numero intero | No |
SSLTrustStore |
Il percorso completo dell'archivio attendibilità Java contenente i certificati dell'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 |
SSLTrustStorePwd |
La password del TrustStore Java specificata nella proprietà
SSLTrustStore.
|
N/D | Stringa | Solo se l'archivio attendibile Java è protetto da password |
SWA_ActivationRowCount |
La soglia di executeBatch insert righe che, se superata, fa sì che il connettore passi all'API Storage Write.
|
3 |
Numero intero | No |
SWA_AppendRowCount |
La dimensione del flusso di scrittura. | 1000 |
Numero intero | No |
Timeout |
La durata, in secondi, durante la quale il connettore ritenta 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 failover all'API REST (se impostato su
TRUE) o restituisce un errore (se impostato su FALSE).
|
TRUE |
Booleano | No |
UseQueryCache |
Consente la memorizzazione nella cache delle query. | TRUE |
Booleano | No |
Eseguire query con il driver
Ora che la tua applicazione Java è connessa a BigQuery tramite il driver JDBC, puoi eseguire query nel tuo ambiente di sviluppo tramite la procedura 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, viene eseguito il seguente mapping dei tipi di dati:
| Tipo GoogleSQL | Tipo di 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
Il seguente esempio 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 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();
Prezzi
Puoi scaricare il driver JDBC per BigQuery senza costi e non hai bisogno di licenze aggiuntive per utilizzarlo. Tuttavia, quando utilizzi il driver, vengono applicati i prezzi standard di BigQuery.
Passaggi successivi
- Scopri di più sul driver Simba ODBC per BigQuery.
- Esplora altri strumenti per sviluppatori BigQuery.