Menggunakan driver JDBC untuk BigQuery

Driver Java Database Connectivity (JDBC) untuk BigQuery menghubungkan aplikasi Java Anda ke BigQuery, sehingga Anda dapat menggunakan fitur BigQuery dengan alat dan infrastruktur pilihan Anda. Untuk menghubungkan aplikasi non-Java ke BigQuery, gunakan driver Simba Open Database Connectivity (ODBC) untuk BigQuery.

Batasan

Driver JDBC untuk BigQuery memiliki batasan berikut:

  • Driver ini khusus untuk BigQuery dan tidak dapat digunakan dengan produk atau layanan lainnya.
  • Jenis data INTERVAL tidak didukung dengan BigQuery Storage Read API.
  • Semua batasan bahasa pengolahan data (DML) berlaku.

Sebelum memulai

  1. Pastikan Anda sudah memahami driver JDBC, Apache Maven, dan paket java.sql.
  2. Pastikan sistem Anda dikonfigurasi dengan Java Runtime Environment (JRE) 8.0 atau yang lebih baru. Untuk mengetahui informasi tentang cara memeriksa versi JRE, lihat Memverifikasi Lingkungan JRE.
  3. Lakukan autentikasi ke BigQuery, dan catat informasi berikut, yang akan digunakan nanti saat Anda membuat koneksi dengan driver JDBC untuk BigQuery. Anda hanya perlu mencatat informasi yang sesuai dengan metode autentikasi yang Anda gunakan.

    Metode autentikasi Informasi autentikasi Contoh Properti koneksi (untuk ditetapkan nanti)
    Akun layanan standar Email akun layanan bq-jdbc-sa@mytestproject.iam.gserviceaccount.com OAuthServiceAcctEmail
    Kunci akun layanan (objek JSON) my-sa-key OAuthPvtKey
    File kunci akun layanan File kunci akun layanan (jalur lengkap) path/to/file/secret.json OAuthPvtKeyPath
    Akun pengguna Google ID Klien 123-abc.apps.googleusercontent.com OAuthClientId
    Rahasia klien _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV OAuthClientSecret
    Token akses yang dibuat sebelumnya Token akses ya29.a0AfH6SMCiH1L-x_yZ OAuthAccessToken
    Token refresh yang dibuat sebelumnya Token refresh 1/fFAGRNJru1FTz70BzhT3Zg OAuthRefreshToken
    ID Klien 123-abc.apps.googleusercontent.com OAuthClientId
    Rahasia klien _aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV OAuthClientSecret
    Kredensial Default Aplikasi Tidak ada T/A T/A
    File konfigurasi File konfigurasi (objek JSON atau jalur lengkap) path/to/file/secret.json OAuthPvtKey
    Objek konfigurasi akun eksternal Objek konfigurasi akun external_account_configuration_object OAuthPvtKey
    Lainnya Properti audiens dari file konfigurasi akun eksternal //iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider BYOID_AudienceUri
    Pengambilan token dan file informasi lingkungan {\"file\":\"/path/to/file\"} BYOID_CredentialSource
    Project pengguna (hanya jika menggunakan kumpulan tenaga kerja) my_project BYOID_PoolUserProject
    URI untuk peniruan akun layanan (hanya jika menggunakan kumpulan tenaga kerja) my-sa BYOID_SA_Impersonation_Uri
    Token Security Token Service berdasarkan spesifikasi pertukaran token urn:ietf:params:oauth:tokentype:id_token BYOID_SubjectTokenType
    Endpoint pertukaran token Security Token Service https://sts.googleapis.com/v1/token BYOID_TokenUri

Mengonfigurasi lingkungan pengembangan Anda

Untuk mengonfigurasi lingkungan pengembangan Anda dengan driver JDBC untuk BigQuery, lakukan hal berikut:

  1. Download salah satu paket JDBC berikut:

  2. Tambahkan file JAR yang didownload ke classpath Anda agar compiler dan runtime Java dapat menemukan class JDBC yang diperlukan. Untuk mengetahui informasi tentang cara menambahkan file ke classpath, lihat Menetapkan Classpath.

  3. Tambahkan dependensi berikut ke file build Anda:

    <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. Jika Anda menggunakan project Gradle, tambahkan kode berikut ke file build Anda:

    dependencies {
    // ... other dependencies
    implementation files('path/to/file/google-jdbc-jar-with-dependencies.jar')
    }

Membuat koneksi

Untuk membuat koneksi antara aplikasi Java dan BigQuery dengan driver JDBC untuk BigQuery, lakukan hal berikut:

  1. Identifikasi string koneksi Anda untuk driver JDBC untuk BigQuery. String ini mencakup semua informasi yang diperlukan untuk membuat koneksi antara aplikasi Java dan BigQuery. String koneksi memiliki format berikut:

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

    Ganti kode berikut:

    • HOST: alamat IP atau DNS server.
    • PORT: nomor port TCP.
    • PROJECT_ID: ID project BigQuery Anda.
    • AUTH_TYPE: angka yang menentukan jenis autentikasi yang Anda gunakan. Salah satu dari berikut ini:
      • 0: untuk autentikasi akun layanan (standar dan file kunci)
      • 1: untuk autentikasi akun pengguna Google
      • 2: untuk autentikasi token akses atau refresh yang telah dibuat sebelumnya
      • 3: untuk autentikasi Kredensial Default Aplikasi
      • 4: untuk metode autentikasi lainnya
    • AUTH_PROPS: informasi autentikasi yang Anda catat saat Anda mengautentikasi ke BigQuery, yang tercantum dalam format property_1=value_1; property_2=value_2;...—misalnya, OAuthPvtKeyPath=path/to/file/secret.json, jika Anda mengautentikasi dengan file kunci akun layanan.
    • OTHER_PROPS (opsional): properti koneksi tambahan untuk driver JDBC, yang tercantum dalam format property_1=value_1; property_2=value_2;.... Untuk mengetahui daftar lengkap properti koneksi, lihat Properti koneksi.
  2. Hubungkan aplikasi Java Anda ke driver JDBC untuk BigQuery dengan class DriverManager atau DataSource.

    • Hubungkan dengan class DriverManager:

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

      Ganti CONNECTION_STRING dengan string koneksi dari langkah sebelumnya.

    • Hubungkan dengan class 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;
      }

      Ganti CONNECTION_STRING dengan string koneksi dari langkah sebelumnya.

      Class DataSource juga memiliki metode setter yang dapat Anda gunakan untuk menetapkan properti koneksi, daripada menyertakannya dalam string koneksi. Berikut adalah contohnya:

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

Properti koneksi

Properti koneksi driver JDBC adalah parameter konfigurasi yang Anda sertakan dalam string koneksi atau diteruskan melalui metode setter saat Anda membuat koneksi ke database. Properti koneksi berikut didukung oleh driver JDBC untuk BigQuery.

Properti koneksi Deskripsi Nilai default Data type Wajib
AdditionalProjects Project yang dapat diakses driver untuk kueri dan operasi metadata, selain project utama yang ditetapkan oleh properti ProjectId. T/A String yang dipisahkan koma Tidak
AllowLargeResults Menentukan apakah driver memproses hasil kueri yang lebih besar dari 128 MB saat properti QueryDialect disetel ke BIG_QUERY. Jika properti QueryDialect disetel ke SQL, driver akan selalu memproses hasil kueri besar. TRUE Boolean Tidak
BYOID_AudienceUri Properti audiens dalam file konfigurasi akun eksternal. Properti audiens dapat berisi nama resource untuk workload identity pool atau workforce pool, serta ID penyedia di pool tersebut. T/A String Hanya jika OAuthType=4
BYOID_CredentialSource Pengambilan token dan informasi lingkungan. T/A String Hanya jika OAuthType=4
BYOID_PoolUserProject Project pengguna saat kumpulan tenaga kerja digunakan untuk autentikasi. T/A String Hanya jika OAuthType=4 dan menggunakan gabungan tenaga kerja
BYOID_SA_Impersonation_Uri URI untuk peniruan identitas akun layanan saat kumpulan tenaga kerja digunakan untuk autentikasi. T/A String Hanya jika OAuthType=4 dan menggunakan gabungan tenaga kerja
BYOID_SubjectTokenType Token Layanan Token Keamanan berdasarkan spesifikasi pertukaran token. Salah satu dari berikut ini:
  • urn:ietf:params:oauth:token-type:jwt
  • urn:ietf:params:oauth:token-type:id_token
  • urn:ietf:params:oauth:token-type:saml2
  • urn:ietf:params:aws:token-type:aws4_request
urn:ietf:params:oauth:tokentype:id_token String Hanya jika OAuthType=4
BYOID_TokenUri Endpoint pertukaran token Security Token Service. https://sts.googleapis.com/v1/token String Tidak
ConnectionPoolSize Ukuran kumpulan koneksi, jika penggabungan koneksi diaktifkan. 10 Long Tidak
DefaultDataset Set data yang digunakan jika set data tidak ditentukan dalam kueri. T/A String Tidak
EnableHighThroughputAPI Menentukan apakah Storage Read API dapat digunakan. Properti HighThroughputActivationRatio dan HighThroughputMinTableSize juga harus ditetapkan ke TRUE untuk menggunakan Storage Read API. FALSE Boolean Tidak
EnableSession Menentukan apakah koneksi memulai sesi. Jika ditetapkan ke TRUE, ID sesi akan diteruskan ke semua kueri berikutnya. FALSE Boolean Tidak
EnableWriteAPI Menentukan apakah Storage Write API dapat digunakan. Harus disetel ke TRUE untuk mengaktifkan penyisipan massal. FALSE Boolean Tidak
EndpointOverrides Endpoint kustom untuk mengganti berikut ini:
  • BIGQUERY=https://bigquery.googleapis.com
  • READ_API=https://bigquerystorage.googleapis.com
  • OAUTH2=https://oauth2.googleapis.com
  • STS=https://sts.googleapis.com
T/A String yang dipisahkan koma Tidak
FilterTablesOnDefaultDataset Menentukan cakupan metadata yang ditampilkan oleh metode DatabaseMetaData.getTables() dan DatabaseMetaData.getColumns(). Jika disetel ke FALSE, pemfilteran tidak akan terjadi. Properti DefaultDataset juga harus disetel untuk mengaktifkan pemfilteran. FALSE Boolean Tidak
HighThroughputActivationRatio Nilai minimum untuk jumlah halaman dalam respons kueri. Jika jumlah ini terlampaui, dan kondisi EnableHighThroughputAPI dan HighThroughputMinTableSize terpenuhi, driver akan mulai menggunakan Storage Read API. 2 Bilangan bulat Tidak
HighThroughputMinTableSize Nilai minimum untuk jumlah baris dalam respons kueri. Jika jumlah ini terlampaui, dan kondisi EnableHighThroughputAPI serta HighThroughputActivationRatio terpenuhi, driver akan mulai menggunakan Storage Read API. 100 Bilangan bulat Tidak
JobCreationMode Menentukan apakah kueri dijalankan dengan atau tanpa tugas. Nilai 1 berarti tugas dibuat untuk setiap kueri, dan nilai 2 berarti kueri dapat dijalankan tanpa tugas. 2 Bilangan bulat Tidak
JobTimeout Waktu tunggu tugas (dalam detik) setelah tugas dibatalkan di server. 0 Long Tidak
KMSKeyName Nama kunci KMS untuk mengenkripsi data. T/A String Tidak
Labels Label yang terkait dengan kueri untuk mengatur dan mengelompokkan tugas kueri. T/A Map<String, String> Tidak
LargeResultDataset Dataset tujuan untuk hasil kueri yang besar, hanya jika properti LargeResultTable ditetapkan. Saat Anda menyetel properti ini, penulisan data akan melewati cache hasil dan memicu penagihan untuk setiap kueri, meskipun hasilnya kecil. _google_jdbc String Tidak
LargeResultsDatasetExpirationTime Masa aktif semua tabel dalam set data hasil besar, dalam milidetik. Properti ini diabaikan jika set data sudah memiliki waktu habis masa berlaku default yang ditetapkan. 3600000 Long Tidak
LargeResultTable Tabel tujuan untuk hasil kueri yang besar, hanya jika properti LargeResultDataset ditetapkan. Saat Anda menetapkan properti ini, penulisan data akan melewati cache hasil dan memicu penagihan untuk setiap kueri, meskipun hasilnya kecil. temp_table... String Tidak
ListenerPoolSize Ukuran kumpulan pendengar, jika penggabungan koneksi diaktifkan. 10 Long Tidak
Location Lokasi tempat set data dibuat atau dikueri. BigQuery secara otomatis menentukan lokasi jika properti ini tidak ditetapkan. T/A String Tidak
LogLevel Tingkat detail yang dicatat oleh paket java.util.logging selama interaksi database. Logging dapat memengaruhi performa, jadi aktifkan sementara hanya untuk merekam masalah. Salah satu dari berikut ini:
  • 0: tingkat OFF
  • 1: tingkat SEVERE
  • 2: tingkat WARNING
  • 3: tingkat INFO
  • 4: tingkat CONFIG
  • 5: tingkat FINE
  • 6: tingkat FINER
  • 7: tingkat FINEST
  • 8: tingkat ALL
0 Bilangan bulat Tidak
LogPath Direktori tempat file log ditulis. T/A String Tidak
MaximumBytesBilled Batas byte yang ditagih. Kueri dengan byte yang ditagih lebih besar dari jumlah ini akan gagal tanpa menimbulkan biaya. 0 Long Tidak
MaxResults Jumlah maksimum hasil per halaman. 10000 Long Tidak
MetaDataFetchThreadCount Jumlah thread yang digunakan untuk metode metadata database. 32 Bilangan bulat Tidak
OAuthAccessToken Token akses yang digunakan untuk autentikasi token akses yang dibuat sebelumnya. T/A String Hanya jika OAUTH_TYPE=2
OAuthClientId ID klien untuk autentikasi token refresh yang dibuat sebelumnya dan autentikasi akun pengguna. T/A String Hanya jika OAUTH_TYPE=1 atau OAUTH_TYPE=2
OAuthClientSecret Secret klien untuk autentikasi token refresh yang dibuat sebelumnya dan autentikasi akun pengguna. T/A String Hanya jika OAUTH_TYPE=1 atau OAUTH_TYPE=2
OAuthP12Password Sandi untuk file kunci PKCS12. notasecret String Tidak
OAuthPvtKey Kunci akun layanan saat menggunakan autentikasi akun layanan. Nilai ini dapat berupa objek file kunci JSON mentah atau jalur ke file kunci JSON. T/A String Hanya jika OAUTH_TYPE=0 dan nilai OAuthPvtKeyPath tidak ditetapkan
OAuthPvtKeyPath Jalur ke kunci akun layanan saat menggunakan autentikasi akun layanan. T/A String Hanya jika OAUTH_TYPE=0 dan nilai OAuthPvtKey serta OAuthServiceAcctEmail tidak ditetapkan
OAuthRefreshToken Token refresh untuk autentikasi token refresh yang dibuat sebelumnya. T/A String Hanya jika OAUTH_TYPE=2
OAuthServiceAcctEmail Email akun layanan saat menggunakan autentikasi akun layanan. T/A String Hanya jika OAUTH_TYPE=0 dan nilai OAuthPvtKeyPath tidak ditetapkan
OAuthType Jenis autentikasi. Salah satu dari berikut ini:
  • 0: autentikasi akun layanan
  • 1: autentikasi akun pengguna
  • 2: autentikasi token akses atau refresh yang dibuat sebelumnya
  • 3: Autentikasi Kredensial Default Aplikasi
  • 4: metode autentikasi lainnya
-1 Bilangan bulat Ya
PartnerToken Token yang digunakan oleh partner Google Cloud untuk melacak penggunaan driver. T/A String Tidak
ProjectId Project ID default untuk driver. Project ini digunakan untuk menjalankan kueri dan ditagih untuk penggunaan resource. Jika tidak ditetapkan, driver menyimpulkan project ID. T/A String Tidak, tetapi sangat direkomendasikan
ProxyHost Nama host atau alamat IP server proxy yang digunakan untuk merutekan koneksi JDBC. T/A String Tidak
ProxyPort Nomor port tempat server proxy memproses koneksi. T/A String Tidak
ProxyPwd Sandi untuk autentikasi saat terhubung melalui server proxy yang memerlukannya. T/A String Tidak
ProxyUid Nama pengguna untuk autentikasi saat terhubung melalui server proxy yang memerlukannya. T/A String Tidak
QueryDialect Dialek SQL untuk eksekusi kueri. Gunakan SQL untuk GoogleSQL (sangat direkomendasikan) dan BIG_QUERY untuk legacy SQL. SQL String Tidak
QueryProperties Properti koneksi REST yang menyesuaikan perilaku kueri. T/A Map<String, String> Tidak
RequestGoogleDriveScope Menambahkan cakupan Drive hanya baca ke koneksi saat disetel ke 1. 0 Bilangan bulat Tidak
RetryInitialDelay Menetapkan penundaan (dalam detik) sebelum percobaan ulang pertama. 0 Long Tidak
RetryMaxDelay Menetapkan batas maksimum (dalam detik) untuk penundaan percobaan ulang. 0 Long Tidak
ServiceAccountImpersonationChain Daftar email akun layanan yang dipisahkan koma dalam rantai peniruan identitas. T/A String Tidak
ServiceAccountImpersonationEmail Email akun layanan yang akan ditiru identitasnya. T/A String Tidak
ServiceAccountImpersonationScopes Daftar cakupan OAuth2 yang dipisahkan koma untuk digunakan dengan akun yang di-impersonate. https://www.googleapis.com/auth/bigquery String Tidak
ServiceAccountImpersonationTokenLifetime Masa aktif token akun yang ditiru (dalam detik). 3600 Bilangan bulat Tidak
SSLTrustStore Jalur lengkap ke Java TrustStore yang berisi sertifikat Certificate Authority (CA) tepercaya. Driver menggunakan truststore ini untuk memvalidasi identitas server selama handshake SSL/TLS. T/A String Tidak
SSLTrustStorePwd Sandi ke Java TrustStore yang ditentukan dalam properti SSLTrustStore. T/A String Hanya jika Java TrustStore dilindungi sandi
SWA_ActivationRowCount Nilai minimum executeBatch insert baris yang, jika terlampaui, akan menyebabkan konektor beralih ke Storage Write API. 3 Bilangan bulat Tidak
SWA_AppendRowCount Ukuran aliran tulis. 1000 Bilangan bulat Tidak
Timeout Durasi waktu, dalam detik, saat konektor mencoba lagi panggilan API yang gagal sebelum waktu tunggu habis. 0 Long Tidak
UniverseDomain Domain tingkat teratas yang terkait dengan Google Cloud resource organisasi Anda. googleapis.com String Tidak
UnsupportedHTAPIFallback Menentukan apakah konektor melakukan penggantian ke REST API (jika disetel ke TRUE) atau menampilkan error (jika disetel ke FALSE). TRUE Boolean Tidak
UseQueryCache Mengaktifkan caching kueri. TRUE Boolean Tidak

Menjalankan kueri dengan driver

Setelah aplikasi Java Anda terhubung ke BigQuery melalui driver JDBC, Anda kini dapat menjalankan kueri di lingkungan pengembangan melalui proses JDBC standar. Semua kuota dan batas BigQuery berlaku.

Pemetaan jenis data

Saat Anda menjalankan kueri melalui driver JDBC untuk BigQuery, pemetaan jenis data berikut akan terjadi:

Jenis GoogleSQL Jenis 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

Contoh

Bagian berikut memberikan contoh yang menggunakan fitur BigQuery melalui driver JDBC untuk BigQuery.

Parameter posisi

Contoh berikut menjalankan kueri dengan parameter posisi:

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

Kumpulan data bertingkat dan berulang

Contoh berikut mengkueri rekaman dasar data 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());

Driver menampilkan rekaman dasar sebagai objek struct atau representasi string dari objek JSON. Hasilnya mirip dengan berikut ini:

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

Contoh berikut mengkueri subkomponen objek 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());
    }

Contoh berikut mengkueri array standar data berulang, lalu memverifikasi hasilnya:

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

Contoh berikut mengkueri array Struct dari data berulang, lalu memverifikasi hasilnya:

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

Penyisipan massal

Contoh berikut melakukan operasi penyisipan massal dengan metode 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();

Harga

Anda dapat mendownload driver JDBC untuk BigQuery tanpa biaya, dan Anda tidak memerlukan lisensi tambahan untuk menggunakan driver tersebut. Namun, saat Anda menggunakan driver, harga BigQuery standar berlaku.

Langkah berikutnya