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 INTERVAL non è supportato dall'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 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.com	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à Segmento di pubblico 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à del account di servizio (solo se utilizzi un pool di workforce)	my-sa	BYOID_SA_Impersonation_Uri
   	Token del servizio token di sicurezza basato sulla specifica di scambio di token	urn:ietf:params:oauth:tokentype:id_token	BYOID_SubjectTokenType
   	Endpoint di scambio token del servizio token di sicurezza	https://sts.googleapis.com/v1/token	BYOID_TokenUri

Configura l'ambiente di sviluppo

Per configurare l'ambiente di sviluppo con il driver JDBC per BigQuery, segui questa procedura:

1. 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.

2. 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.

3. 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>

4. 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:

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 chiave)
     • 1: per l'autenticazione dell'account utente Google
     • 2: per l'autenticazione con token di accesso o di aggiornamento pregenerati
     • 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 ti sei autenticato in BigQuery, elencate nel formato property_1=value_1; property_2=value_2;..., ad esempio OAuthPvtKeyPath=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 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 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_STRING con 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_STRING con la stringa di connessione del passaggio precedente.

     La classe DataSource dispone 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.

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:

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.