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 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 manipulasi 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. 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 Client ID 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
    Client ID 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

Menginstal dan mengonfigurasi driver JDBC

Anda dapat menginstal dan mengonfigurasi driver JDBC untuk BigQuery dengan mendownload file uber-JAR secara langsung atau menggunakan Maven.

Konfigurasi download langsung

Untuk mengonfigurasi driver JDBC melalui download langsung, lakukan hal berikut:

  1. Download driver versi 1.1.0.
  2. Salin file yang didownload ke lokasi yang ditentukan oleh software Anda.

Untuk mengetahui informasi tentang perubahan fitur dan pembaruan alur kerja, lihat log perubahan.

Konfigurasi Maven

Driver JDBC untuk BigQuery tersedia di Maven Central.

Untuk mengonfigurasi lingkungan pengembangan dengan driver JDBC, tambahkan driver sebagai dependensi ke project Anda:

Maven

Tambahkan dependensi berikut ke file pom.xml Anda:

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

Maven menggunakan uber-JAR

Tambahkan dependensi berikut ke file pom.xml Anda:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.1.0</version>
    <classifier>all</classifier>
    <exclusions>
      <exclusion>
        <groupId>*</groupId>
        <artifactId>*</artifactId>
      </exclusion>
    </exclusions>
</dependency>

Gradle

Tambahkan kode berikut ke file build.gradle Anda:

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

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 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 yang besar. TRUE Boolean Tidak
BYOID_AudienceUri Properti audiens dalam file konfigurasi akun eksternal. Properti audiens dapat berisi nama resource untuk workload identity pool atau kumpulan tenaga kerja, serta ID penyedia dalam kumpulan 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 pool 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
EnableGcpLogExporter Menentukan apakah driver otomatis mengekspor log ke Cloud Logging (jika tidak ada instance OpenTelemetry kustom atau global yang digunakan). Untuk mengetahui informasi selengkapnya, lihat OpenTelemetry. FALSE Boolean Tidak
EnableGcpTraceExporter Menentukan apakah driver otomatis mengekspor rekaman aktivitas ke Cloud Trace (jika tidak ada instance OpenTelemetry kustom atau global yang digunakan). Untuk mengetahui informasi selengkapnya, lihat OpenTelemetry. FALSE Boolean 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
EnableProjectDiscovery Menentukan apakah metode metadata database menemukan set data di semua project yang dapat diakses Google Cloud . Jika disetel ke FALSE, penemuan dibatasi ke ProjectId default. 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 (gRPC) 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, tidak ada pemfilteran. Properti DefaultDataset juga harus disetel untuk mengaktifkan pemfilteran. FALSE Boolean Tidak
GcpTelemetryCredentials Kredensial yang digunakan untuk mengautentikasi eksportir telemetri. Menerima jalur ke kunci JSON akun layanan atau string JSON mentah. Defaultnya adalah kredensial koneksi jika tidak ditetapkan. Untuk mengetahui informasi selengkapnya, lihat OpenTelemetry. T/A String Tidak
GcpTelemetryProjectId Project ID tujuan Google Cloud untuk telemetri. Default-nya adalah ProjectId utama. Untuk mengetahui informasi selengkapnya, lihat OpenTelemetry. T/A String 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. 10000 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 Set data 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 menyetel 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 akan otomatis menentukan lokasi jika properti ini tidak ditetapkan. T/A String Tidak
LogLevel Tingkat detail yang dicatat oleh pengemudi. Untuk mengetahui informasi selengkapnya, lihat Logging. 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 SSL/TLS handshake. T/A String Tidak
SSLTrustStoreProvider Penyedia Java Cryptography Extension (JCE) yang digunakan untuk properti SSLTrustStore. T/A String Tidak
SSLTrustStorePwd Sandi ke Java TrustStore yang ditentukan dalam properti SSLTrustStore. T/A String Hanya jika Java TrustStore dilindungi sandi
SSLTrustStoreType Format file truststore yang ditentukan dalam properti SSLTrustStore (seperti JKS, PKCS12, atau ROTKS). T/A String Tidak
SWA_ActivationRowCount Nilai minimum baris executeBatch insert yang, jika terlampaui, akan menyebabkan konektor beralih ke Storage Write API (gRPC). 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
UseGlobalOpenTelemetry Menentukan apakah driver menggunakan GlobalOpenTelemetry.get() untuk instrumentasi. Untuk mengetahui informasi selengkapnya, lihat OpenTelemetry. FALSE 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();

Logging

Untuk memecahkan masalah pada driver JDBC untuk BigQuery, Anda dapat mengaktifkan logging dengan menetapkan properti koneksi atau variabel lingkungan. Logging dapat memengaruhi performa dan menggunakan ruang disk, jadi aktifkan hanya untuk sementara waktu guna merekam masalah.

Level log

Properti LogLevel menentukan tingkat detail yang dicatat oleh paket java.util.logging:

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

Sebaiknya gunakan level 6 untuk pemecahan masalah umum. Level 7 dan 8 dibatasi untuk operasi ResultSet dan menghasilkan volume log yang besar.

Mengaktifkan logging di string koneksi

Untuk mengaktifkan logging di string koneksi, tambahkan properti koneksi LogLevel dan LogPath, misalnya:

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

Mengaktifkan logging dengan variabel lingkungan

Jika alat pengembangan Anda tidak mengizinkan pengeditan string koneksi, Anda juga dapat menyetel tingkat log dan jalur log dengan variabel lingkungan berikut sebelum menjalankan aplikasi:

  • BIGQUERY_JDBC_LOG_LEVEL: level log (0-8).
  • BIGQUERY_JDBC_LOG_PATH: direktori untuk file log.

Misalnya, di lingkungan Linux atau macOS, jalankan perintah berikut:

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

OpenTelemetry

Driver JDBC untuk BigQuery mendukung OpenTelemetry (OTel) untuk menyediakan tracing dan logging terdistribusi, yang memungkinkan Anda memantau performa interaksi database dan memecahkan masalah secara efektif.

Operasi yang dilacak

Jika OpenTelemetry diaktifkan, driver akan membuat rentang untuk operasi berikut:

  • Eksekusi kueri: Rentang dibuat untuk BigQueryStatement (execute(), executeQuery(), executeLargeUpdate(), executeBatch()) dan BigQueryPreparedStatement (execute(), executeQuery(), executeLargeUpdate()).
  • Operasi metadata: Rentang dibuat untuk metode DatabaseMetaData tertentu (getCatalogs(), getSchemas(), getTables(), getColumns()).
  • Penomoran halaman: Pengambilan asinkron untuk halaman hasil tambahan (saat menggunakan jalur REST API) dilacak dan dihubungkan secara kausal ke rentang eksekusi kueri asli menggunakan Link Rentang OpenTelemetry. Rentang bernama BigQueryStatement.pagination dibuat untuk operasi ini.
  • Penerapan konteks: Driver JDBC menerapkan konteks aktif ke SDK google-cloud-bigquery yang mendasarinya. Akibatnya, rentang yang dibuat oleh SDK (seperti panggilan RPC HTTP) akan otomatis muncul sebagai turunan rentang JDBC, sehingga memberikan hierarki rekaman aktivitas end-to-end yang lengkap.

Mode konfigurasi

Anda dapat mengonfigurasi OpenTelemetry di driver JDBC menggunakan salah satu mode berikut, bergantung pada arsitektur dan persyaratan aplikasi Anda.

Telemetri yang dikelola aplikasi

Jika aplikasi Anda sudah menggunakan OpenTelemetry, Anda dapat menyuntikkan instance OpenTelemetry ke driver JDBC untuk memastikan telemetri driver dikorelasikan dengan telemetri aplikasi Anda.

Untuk melakukannya, gunakan BigQueryDataSource API:

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

Dukungan OpenTelemetry global

Jika telah menginisialisasi OpenTelemetry secara global di aplikasi Anda (misalnya, menggunakan Agen Java OpenTelemetry atau dengan memanggil fungsi GlobalOpenTelemetry.set()), Anda dapat mengonfigurasi driver untuk menggunakan instance global ini.

Untuk mengaktifkan instance global, tetapkan properti koneksi UseGlobalOpenTelemetry ke TRUE.

Telemetri Google Cloud tanpa konfigurasi

Jika Anda menjalankan Google Cloud dan menginginkan penyiapan cepat, Anda dapat mengaktifkan ekspor otomatis rekaman aktivitas dan log ke kemampuan observasi Google Cloud (Trace dan Logging).

Untuk mengaktifkan ekspor ini, tetapkan properti koneksi berikut di URL JDBC Anda:

  • EnableGcpTraceExporter=true
  • EnableGcpLogExporter=true

Berikut adalah contoh URL koneksi:

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

Properti koneksi OpenTelemetry

Properti koneksi berikut didukung untuk OpenTelemetry. Untuk deskripsi mendetail dan nilai default, lihat Properti koneksi.

  • EnableGcpLogExporter
  • EnableGcpTraceExporter
  • GcpTelemetryCredentials
  • GcpTelemetryProjectId
  • UseGlobalOpenTelemetry

Pertimbangan penting

Saat men-deploy integrasi OpenTelemetry, perhatikan pertimbangan berikut terkait perilaku logging, autentikasi, dan harga.

Interaksi dengan LogLevel

Properti koneksi LogLevel yang ada berfungsi sebagai penjaga utama untuk pencatatan.

  • Jika LogLevel=0 (NONAKTIF) ditetapkan, tidak ada catatan log yang dibuat. Akibatnya, tidak ada log yang diekspor menggunakan OpenTelemetry atau ke Logging, meskipun EnableGcpLogExporter=true.
  • Untuk mengaktifkan logging OTel, pastikan LogLevel ditetapkan ke nilai yang lebih besar dari 0 (misalnya, 5 untuk log mendetail).

Autentikasi untuk telemetri

Ekspor telemetri (pelacakan dan logging) dengan penggantian otomatis Google Cloud mendukung Kredensial Default Aplikasi (ADC) dan kredensial Akun Layanan eksplisit yang diberikan menggunakan GcpTelemetryCredentials.

Jika GcpTelemetryProjectId atau GcpTelemetryCredentials diberikan, log dan rekaman aktivitas akan dikirim ke project tujuan yang sama yang ditentukan menggunakan kredensial yang dikonfigurasi sama.

API dan izin IAM yang diperlukan

Agar berhasil menulis data telemetri ke kemampuan pengamatan Google Cloud , lakukan penyiapan berikut di project Google Cloud target Anda:

  1. Aktifkan API:
    • Aktifkan Cloud Trace API (cloudtrace.googleapis.com).
    • Aktifkan Cloud Logging API (logging.googleapis.com).
  2. Memberikan peran IAM:
    • Untuk mengekspor rekaman aktivitas: Berikan peran Trace Agent (roles/cloudtrace.agent) kepada akun utama atau akun layanan.
    • Untuk mengekspor log: Berikan peran Penulis Log (roles/logging.logWriter) kepada akun utama atau akun layanan.

Penetapan harga dan penagihan

Saat menggunakan telemetri Google Cloud tanpa konfigurasi (EnableGcpTraceExporter=true atau EnableGcpLogExporter=true), data telemetri dikirim ke Trace dan Logging. Layanan ini dapat dikenai biaya berdasarkan volume data yang di-ingest. Untuk mengetahui informasi selengkapnya, lihat Google Cloud Observability.

Metrik

Integrasi ini tidak mendukung metrik OpenTelemetry.

Bayangan dependensi

Untuk mencegah konflik classpath dengan aplikasi Anda, driver menyertakan dependensi SDK dan eksportir OpenTelemetry. OpenTelemetry API tetap tidak di-shade untuk memungkinkan interoperabilitas dengan SDK yang disediakan aplikasi Anda.

Korelasi logging dan pelacakan

Jika OpenTelemetry diaktifkan, driver akan otomatis mengorelasikan log dengan rekaman aktivitas:

  • db.connection_id: Dilampirkan sebagai atribut rentang ke semua rentang JDBC.
  • jdbc.connection_id: Digunakan sebagai kunci bagasi dan dilampirkan sebagai label ke semua entri log yang dikeluarkan oleh driver ke Logging.
  • ID Aktivitas dan ID Rentang: Log yang dihasilkan dalam cakupan eksekusi kueri secara otomatis menyertakan trace_id dan span_id yang aktif.

Harga

Anda dapat mendownload driver JDBC untuk BigQuery tanpa biaya. Namun, saat Anda menggunakan driver, harga BigQuery standar berlaku.

Langkah berikutnya