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 tunduk pada batasan berikut:

• Driver ini khusus untuk BigQuery dan tidak dapat digunakan dengan produk atau layanan lain.
• 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.	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 telah dibuat sebelumnya	Token akses	ya29.a0AfH6SMCiH1L-x_yZ	OAuthAccessToken
   Token refresh yang telah 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 file konfigurasi akun eksternal	//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider	BYOID_AudienceUri
   	File pengambilan token dan informasi lingkungan	{\"file\":\"/path/to/file\"}	BYOID_CredentialSource
   	Project pengguna (hanya jika menggunakan workforce pool)	my_project	BYOID_PoolUserProject
   	URI untuk peniruan akun layanan (hanya jika menggunakan workforce pool)	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.7.0.
2. Salin file yang didownload ke lokasi yang ditentukan oleh software Anda.

Untuk mengetahui informasi tentang perubahan fitur dan update alur kerja, lihat catatan rilis dan log perubahan.

Driver JDBC sebelumnya untuk versi BigQuery

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

Konfigurasi Maven

Driver JDBC untuk BigQuery tersedia di Maven Central.

Untuk mengonfigurasi lingkungan pengembangan Anda 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.7.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.7.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.7.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 menangkap 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: DNS atau alamat IP 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 refresh atau akses yang telah dibuat sebelumnya
     • 3: untuk autentikasi Kredensial Default Aplikasi
     • 4: untuk metode autentikasi lainnya
   • AUTH_PROPS: informasi autentikasi yang Anda catat saat melakukan autentikasi ke BigQuery, yang tercantum dalam format property_1=value_1; property_2=value_2;...—misalnya, OAuthPvtKeyPath=path/to/file/secret.json, jika Anda melakukan autentikasi 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 penyetel 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 teruskan melalui metode setter saat Anda membuat koneksi ke database. Properti koneksi berikut didukung oleh driver JDBC untuk BigQuery.

Catatan: Semua nama properti koneksi tidak peka huruf besar/kecil. Properti koneksi Boolean menerima TRUE/FALSE dan 1/0.

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 ditetapkan ke BIG_QUERY. Jika properti QueryDialect ditetapkan ke SQL, driver akan selalu memproses hasil kueri yang besar.	TRUE	Boolean	Tidak
BYOID_AudienceUri	Properti audiens dalam file konfigurasi akun eksternal. Properti audience dapat berisi nama resource untuk workload identity pool atau workforce pool, serta ID penyedia di pool tersebut.	T/A	String	Hanya saat OAuthType=4
BYOID_CredentialSource	Pengambilan token dan informasi lingkungan.	T/A	String	Hanya saat OAuthType=4
BYOID_PoolUserProject	Project pengguna saat workforce pool digunakan untuk autentikasi.	T/A	String	Hanya saat OAuthType=4 dan menggunakan workforce pool
BYOID_SA_Impersonation_Uri	URI untuk peniruan akun layanan saat workforce pool digunakan untuk autentikasi.	T/A	String	Hanya saat OAuthType=4 dan menggunakan workforce pool
BYOID_SubjectTokenType	Token Security Token Service 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 saat 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 tidak ditentukan dalam kueri.	T/A	String	Tidak
EnableDiagnosticTelemetry	Mengaktifkan atau menonaktifkan telemetri. Telemetri diaktifkan secara default. Untuk perilaku siklus proses JVM, lihat Konfigurasi telemetri penggunaan sisi klien.	TRUE	Boolean	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 trace 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 Google Cloud yang dapat diakses. Jika ditetapkan 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
EnableTimestampPicos	Menentukan apakah driver mengambil nilai TIMESTAMP(12) dengan presisi pikodetik. Jika ditetapkan ke TRUE, nilai TIMESTAMP(12) akan ditampilkan sebagai objek String berformat UTC oleh metode getString() dan getObject(). Jika ditetapkan ke FALSE, nilai TIMESTAMP(12) akan dipotong menjadi presisi mikrodetik 6 digit. Properti ini tidak kompatibel dengan legacy SQL (QueryDialect=BIG_QUERY).	FALSE	Boolean	Tidak
EnableWriteAPI	Menentukan apakah Storage Write API (gRPC) dapat digunakan. Nilai ini harus ditetapkan ke TRUE untuk mengaktifkan penyisipan massal.	FALSE	Boolean	Tidak
EndpointOverrides	Endpoint kustom untuk menimpa hal berikut: 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 ditetapkan ke FALSE, pemfilteran tidak akan terjadi. Properti DefaultDataset juga harus ditetapkan untuk mengaktifkan pemfilteran.	FALSE	Boolean	Tidak
GcpTelemetryCredentials	Kredensial yang digunakan untuk mengautentikasi pengekspor telemetri. Menerima jalur ke kunci JSON akun layanan atau string JSON mentah. Setelan default ditetapkan ke kredensial koneksi jika tidak ditetapkan. Untuk mengetahui informasi selengkapnya, lihat OpenTelemetry.	T/A	String	Tidak
GcpTelemetryProjectId	Project ID Google Cloud tujuan 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 serta HighThroughputMinTableSize terpenuhi, driver akan mulai menggunakan Storage Read API.	2	Bilangan bulat	Tidak
HighThroughputMinTableSize	Batas 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 menetapkan properti ini, penulisan data akan mengabaikan cache hasil dan memicu penagihan untuk setiap kueri, meskipun hasilnya kecil.	_google_jdbc	String	Tidak
LargeResultsDatasetExpirationTime	Masa aktif semua tabel dalam set data hasil yang 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 mengabaikan cache hasil dan memicu penagihan untuk setiap kueri, meskipun hasilnya kecil.	temp_table...	String	Tidak
ListenerPoolSize	Ukuran kumpulan pemroses, 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 driver. 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 dikenai biaya.	0	Long	Tidak
MaxResults	Jumlah hasil maksimum 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 telah dibuat sebelumnya.	T/A	String	Hanya saat OAUTH_TYPE=2
OAuthClientId	Client ID untuk autentikasi token refresh yang telah dibuat sebelumnya dan autentikasi akun pengguna.	T/A	String	Hanya jika OAUTH_TYPE=1 atau OAUTH_TYPE=2
OAuthClientSecret	Rahasia klien untuk autentikasi token refresh yang telah 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 serta nilai OAuthPvtKey dan OAuthServiceAcctEmail tidak ditetapkan
OAuthRefreshToken	Token refresh untuk autentikasi token refresh yang telah dibuat sebelumnya.	T/A	String	Hanya saat 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 telah 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 akan menyimpulkan project ID.	T/A	String	Tidak, tetapi sangat direkomendasikan
ProxyHost	Nama host atau alamat IP server proxy yang menjadi tujuan perutean koneksi JDBC.	T/A	String	Tidak
ProxyPort	Nomor port yang diproses server proxy untuk 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 jika ditetapkan 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 OAuth 2.0 yang dipisahkan koma untuk digunakan dengan akun yang ditiru identitasnya.	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
SSLTrustStoreProvider	Penyedia Java Cryptography Extension (JCE) yang digunakan untuk properti SSLTrustStore.	T/A	String	Tidak
SSLTrustStorePwd	Sandi ke Java TrustStore yang ditentukan di properti SSLTrustStore.	T/A	String	Hanya jika TrustStore Java dilindungi sandi
SSLTrustStoreType	Format file truststore yang ditentukan dalam properti SSLTrustStore (seperti JKS, PKCS12, atau ROTKS).	T/A	String	Tidak
SWA_ActivationRowCount	Batas baris executeBatch insert yang, jika terlampaui, akan menyebabkan konektor beralih ke Storage Write API (gRPC).	3	Bilangan bulat	Tidak
SWA_AppendRowCount	Ukuran aliran data tulis.	1000	Bilangan bulat	Tidak
Timeout	Durasi waktu, dalam detik, saat konektor mencoba ulang panggilan API yang gagal sebelum waktu tunggu habis.	0	Long	Tidak
UniverseDomain	Domain level teratas yang terkait dengan resource Google Cloud organisasi Anda.	googleapis.com	String	Tidak
UnsupportedHTAPIFallback	Menentukan apakah konektor akan beralih ke REST API (jika ditetapkan ke TRUE) atau menampilkan error (jika ditetapkan 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

Dengan aplikasi Java yang 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);

Data bertingkat dan berulang

Contoh berikut mengkueri data dasar dari 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 data 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 terkait driver JDBC untuk BigQuery, Anda dapat mengaktifkan logging dengan menetapkan properti koneksi atau variabel lingkungan. Logging dapat memengaruhi performa dan menggunakan kapasitas disk, jadi aktifkan hanya untuk sementara 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 dalam 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 developer Anda tidak mengizinkan pengeditan string koneksi, Anda juga dapat menetapkan 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 pelacakan dan logging terdistribusi, yang memungkinkan Anda memantau performa interaksi database dan memecahkan masalah secara efektif.

Operasi yang dilacak

Jika OpenTelemetry diaktifkan, driver akan menghasilkan span untuk operasi berikut:

• Eksekusi kueri: Span dibuat untuk BigQueryStatement (execute(), executeQuery(), executeLargeUpdate(), executeBatch()) dan BigQueryPreparedStatement (execute(), executeQuery(), executeLargeUpdate()).
• Operasi metadata: Span dibuat untuk metode DatabaseMetaData tertentu (getCatalogs(), getSchemas(), getTables(), getColumns()).
• Penomoran halaman: Pengambilan asinkron untuk halaman hasil tambahan (saat menggunakan jalur REST API) dilacak dan ditautkan secara kausal ke span eksekusi kueri asli menggunakan Link Span OpenTelemetry. Span bernama BigQueryStatement.pagination dibuat untuk operasi ini.
• Penerapan konteks: Driver JDBC menerapkan konteks aktif ke google-cloud-bigquery SDK yang mendasarinya. Akibatnya, span yang dihasilkan oleh SDK (seperti panggilan RPC HTTP) otomatis muncul sebagai turunan dari span JDBC, sehingga memberikan hierarki trace 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 memasukkan instance OpenTelemetry ke dalam driver JDBC untuk memastikan bahwa telemetri driver berkorelasi dengan telemetri aplikasi Anda.

Untuk melakukannya, gunakan BigQueryDataSource API:

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

Dukungan OpenTelemetry global

Jika Anda telah menginisialisasi OpenTelemetry secara global di aplikasi (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 trace 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, konfigurasi proxy, dan harga.

Interaksi dengan LogLevel

Properti koneksi LogLevel yang ada bertindak sebagai gatekeeper utama untuk logging.

• Jika LogLevel=0 (OFF) ditetapkan, tidak ada data 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 (tracing dan logging) dengan penggantian otomatis Google Cloud mendukung Kredensial Default Aplikasi (ADC) dan kredensial Akun Layanan eksplisit yang disediakan menggunakan GcpTelemetryCredentials.

Jika GcpTelemetryProjectId atau GcpTelemetryCredentials disediakan, log dan trace akan dikirim ke project tujuan yang sama menggunakan kredensial yang sama yang dikonfigurasi.

Konfigurasi proxy dengan OpenTelemetry dan logging

Jika aplikasi Anda terhubung ke BigQuery melalui server proxy, driver akan menangani perutean proxy sebagai berikut:

• Ekspor trace (HTTP). Saat Anda menggunakan protokol HTTP default untuk ekspor trace OpenTelemetry (otel.exporter.otlp.protocol=http/protobuf), driver akan otomatis merutekan traffic ekspor trace melalui proxy yang dikonfigurasi di properti koneksi menggunakan ProxyHost dan ProxyPort.

• Ekspor log dan telemetri gRPC. Pengekspor log Google Cloud otomatis (EnableGcpLogExporter=true) dan pengekspor OpenTelemetry berbasis gRPC (otel.exporter.otlp.protocol=grpc) menggunakan gRPC, yang tidak mendukung konfigurasi proxy per koneksi. Untuk merutekan traffic ekspor log dan telemetri gRPC melalui server proxy, konfigurasikan setelan proxy di level JVM menggunakan properti sistem berikut:

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

Izin IAM dan API yang diperlukan

Agar berhasil menulis data telemetri ke observabilitas 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. Berikan peran IAM:
   • Untuk mengekspor trace: Berikan peran Trace Agent (roles/cloudtrace.agent) kepada akun utama atau akun layanan.
   • Untuk mengekspor log: Berikan peran Logs Writer (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 mungkin dikenai biaya berdasarkan volume data yang diserap. Untuk mengetahui informasi selengkapnya, lihat Google Cloud Observability.

Metrik

Integrasi ini tidak mendukung metrik OpenTelemetry.

Shading dependensi

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

Korelasi logging dan trace

Jika OpenTelemetry diaktifkan, driver akan otomatis menghubungkan log dengan trace:

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

Telemetri penggunaan sisi klien

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Driver JDBC untuk BigQuery menyertakan telemetri sisi klien yang secara otomatis mengumpulkan metrik penggunaan dan diagnostik anonim untuk membantu Google meningkatkan stabilitas dan fitur driver. Fitur ini berada dalam Pratinjau. Pengumpulan telemetri penggunaan sisi klien dirancang untuk berjalan di latar belakang tanpa memengaruhi performa driver atau fungsi JDBC. Setiap kegagalan transmisi telemetri akan gagal secara otomatis dan tidak menampilkan error ke aplikasi atau menimbulkan biaya apa pun.

Telemetri penggunaan sisi klien tidak pernah mengumpulkan teks kueri SQL, nilai parameter, informasi skema database, atau konten data. Pengumpulan telemetri tidak berfungsi di lingkungan yang menggunakan URL endpoint kustom atau akses jaringan terbatas yang memblokir koneksi keluar ke layanan logging publik Google.

Diagnostik yang dikumpulkan

Driver mengumpulkan informasi berikut:

• Informasi lingkungan: Versi Driver, versi utama JVM, platform dan versi sistem operasi, serta ID korelasi perangkat anonim yang disimpan secara lokal di folder ~/.bigquery-jdbc/telemetry-tag.
• Metrik koneksi: Status hasil koneksi (berhasil, gagal, atau pembatalan) dan metode autentikasi yang digunakan (seperti akun layanan, ADC, atau token).
• Metrik eksekusi: Jenis operasi kueri tingkat tinggi (seperti SELECT, INSERT, dan CREATE TABLE) , substrat mesin eksekusi yang digunakan (REST API standar atau API throughput tinggi), dan distribusi latensi durasi.
• Metrik error dan fitur: Kode pengecualian internal, metode asal, dan penghitung penggunaan fitur (seperti pernyataan yang disiapkan, pengelompokan, dan penggabungan koneksi).

Konfigurasi telemetri penggunaan sisi klien

Telemetri penggunaan sisi klien berperilaku sebagai layanan latar belakang global untuk JVM aplikasi. Setelan dapat dikonfigurasi menggunakan properti koneksi JDBC, variabel lingkungan, atau properti sistem Java. Driver menyelesaikan setelan dalam prioritas berikut: properti sistem > variabel lingkungan > properti koneksi JDBC.

Karena sifatnya yang global, properti koneksi telemetri penggunaan sisi klien menunjukkan perilaku siklus proses berikut:

• Kontrol Penonaktifan: Jika telemetri penggunaan sisi klien dinonaktifkan kapan saja menggunakan properti koneksi (EnableDiagnosticTelemetry=0), variabel lingkungan, atau properti sistem, layanan akan segera dinonaktifkan dan tetap nonaktif secara permanen selama sisa siklus proses JVM. Penghitung ini hanya akan dimulai ulang saat JVM dimulai ulang.

Kunci Konfigurasi

Untuk mengonfigurasi properti, Anda dapat menggunakan kunci berikut:

• Kontrol Penonaktifan:
  • Properti Koneksi: EnableDiagnosticTelemetry=0;
  • Variabel Lingkungan: BIGQUERY_JDBC_TELEMETRY_ENABLED=false
  • Properti Sistem: -DBIGQUERY_JDBC_TELEMETRY_ENABLED=false

Harga

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

Langkah berikutnya

• Untuk petunjuk penyiapan tambahan, panduan referensi properti URL koneksi, contoh kode, dan petunjuk build lokal, kunjungi repositori open source di GitHub:
  • Catatan Rilis (RELEASE_NOTES.md)
  • Panduan Pengguna (docs/USER_GUIDE.md)
  • Panduan Pengembangan (DEVELOPMENT.md)
  • Pembahasan Mendalam BigQuery Storage API (docs/STORAGE_APIS.md)
• Pelajari lebih lanjut driver ODBC untuk BigQuery.
• Pelajari alat developer BigQuery lainnya.