Menggunakan driver ODBC untuk BigQuery

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

Driver ODBC untuk BigQuery tersedia dalam lisensi Apache 2.0.

Sebelum memulai

  1. Pastikan Anda sudah memahami driver ODBC dan pengelola driver.

  2. Pastikan sistem operasi Anda memenuhi persyaratan berikut:

    Sistem operasi Arsitektur yang didukung Versi dan dependensi minimum
    Windows 32-bit (x86), 64-bit (x64) Versi: Windows 10, Windows Server 2016 atau yang lebih baru

    Dependensi: Microsoft Visual C++ Redistributable untuk Visual Studio 2019 atau 2022
    macOS 64-bit (x86_64), ARM64 (Apple Silicon) Versi: macOS 12 (Monterey) atau yang lebih baru

    Dependensi: Pengelola driver ODBC (misalnya, unixODBC). Pastikan Anda menambahkan direktori penginstalan ke DYLD_LIBRARY_PATH.
    Linux 64 bit (x86_64) Versi: Distribusi apa pun dengan glibc 2.27 atau yang lebih baru (misalnya, Ubuntu 20.04 LTS+, Debian 11+)

    Dependensi: Pengelola Driver ODBC (misalnya, unixODBC). Pastikan Anda menambahkan direktori penginstalan ke LD_LIBRARY_PATH.

  3. Lakukan autentikasi ke BigQuery, dan catat informasi berikut, yang akan digunakan nanti saat Anda membuat koneksi dengan driver ODBC 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 Kunci akun layanan (objek JSON) my-sa-key.json KeyFilePath
    Peniruan akun layanan Alamat email akun layanan target service-account@project.iam.gserviceaccount.com ServiceAccountImpersonationEmail, KeyFilePath
    Workload Identity Federation atau Workforce Identity Federation Properti audiens dari file konfigurasi akun eksternal //iam.googleapis.com/locations/global/... BYOID_AudienceUrl
    Pengambilan token dan file informasi lingkungan {"file":"/path/to/file"} BYOID_CredentialSource
    Project pengguna (hanya untuk workforce pool) my_project BYOID_PoolUserProject
    Jenis token STS id_token BYOID_SubjectTokenType
    Endpoint pertukaran token STS https://sts.googleapis.com/v1/token BYOID_TokenUrl
    Kredensial Default Aplikasi Tidak ada T/A T/A

Menginstal dan mengonfigurasi driver ODBC

Anda dapat menginstal dan mengonfigurasi driver ODBC untuk BigQuery menggunakan sistem operasi Windows atau non-Windows.

Windows

  1. Instal driver yang sesuai dengan arsitektur aplikasi Anda:

  2. Buat Nama Sumber Data (DSN) dengan melakukan hal berikut:

    1. Dari menu Start di Windows, buka ODBC Data Sources, dan pilih versi yang memiliki bit yang sama dengan aplikasi klien Anda.
    2. Di halaman ODBC Data Source Administrator, klik tab Drivers.
    3. Dalam daftar driver ODBC yang diinstal, cari ODBC Driver for BigQuery.
    4. Pilih tab System DSN untuk membuat DSN bagi semua pengguna atau tab User DSN untuk membuat DSN bagi pengguna saat ini. DSN Sistem umumnya direkomendasikan karena beberapa aplikasi memuat data menggunakan akun pengguna yang berbeda dan mungkin tidak mendeteksi DSN Pengguna lainnya.
    5. Klik Tambahkan.
    6. Di dialog Create New Data Source, pilih ODBC Driver for BigQuery, lalu klik Finish. Dialog ODBC Driver for BigQuery DSN Setup akan terbuka.
    7. Di kolom Nama Sumber Data, masukkan nama untuk DSN Anda.
    8. Tambahkan properti koneksi. Untuk mengetahui daftar lengkap properti, lihat Properti koneksi.

Non-Windows

  1. Instal driver yang sesuai dengan sistem operasi Anda:

  2. Ekstrak konten file ZIP atau TAR yang didownload.

  3. Pindahkan konten file ZIP atau TAR ke direktori tempat Anda ingin menginstal driver. Jalur objek bersama driver ODBC untuk BigQuery adalah INSTALL_DIR/lib/libgoogle_cloud_odbc_bq_driver.so, dengan INSTALL_DIR adalah direktori penginstalan Anda.

  4. Perbarui file .ini Anda untuk mencerminkan jalur baru driver.

    Contoh berikut memperbarui file .ini dalam sistem Linux:

    unzip linux_odbc-driver.VERSION.zip -d linux_odbc-driver.VERSION/
cd ./linux_odbc-driver.VERSION
export INSTALL_DIR=$(pwd)
export ODBCINI=$INSTALL_DIR/odbc.ini
export ODBCINSTINI=$INSTALL_DIR/odbcinst.ini
export GOOGLEBIGQUERYODBCINI=$INSTALL_DIR/googlebigqueryodbc.ini

    Ganti VERSION dengan versi driver.

Membuat koneksi

Untuk membuat koneksi antara aplikasi dan BigQuery dengan driver ODBC untuk BigQuery, identifikasi string koneksi Anda. Anda dapat melewati langkah ini jika sudah mengonfigurasi properti koneksi melalui DSN Anda.

String koneksi memiliki format berikut:

Driver=ODBC Driver for BigQuery;Catalog=PROJECT_ID;OAuthMechanism=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

Ganti kode berikut:

  • PROJECT_ID: ID project BigQuery Anda.
  • AUTH_TYPE: angka yang menentukan jenis autentikasi yang Anda gunakan. Pilih salah satu opsi berikut:
    • 0: untuk autentikasi akun layanan
    • 3: untuk autentikasi Kredensial Default Aplikasi
    • 4: untuk autentikasi Workload Identity Federation atau Workforce Identity Federation
  • 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, KeyFilePath=my-sa-key.json, jika Anda mengautentikasi dengan akun layanan.
  • OTHER_PROPS (opsional): properti koneksi tambahan untuk driver ODBC, yang tercantum dalam format property_1=value_1; property_2=value_2;.... Untuk mengetahui daftar lengkap properti koneksi, lihat Properti koneksi.

Properti koneksi

Properti koneksi driver ODBC adalah parameter konfigurasi yang Anda sertakan dalam string koneksi saat Anda membuat koneksi ke database. Driver ODBC untuk BigQuery mendukung properti koneksi berikut.

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 Catalog. T/A String yang dipisahkan koma Tidak
AllowHtapiForLargeResults Menentukan apakah driver dapat menggunakan BigQuery Storage Read API. 0 Boolean Tidak
AllowLargeResults Menentukan apakah driver memproses hasil kueri yang lebih besar dari 128 MB saat properti SQLDialect disetel ke 0 (SQL lama). Jika properti SQLDialect disetel ke 1 (GoogleSQL), driver akan selalu memproses hasil kueri besar. 0 Boolean Tidak
BYOID_AudienceUrl Berisi nama resource untuk Workload Identity Pool atau Workforce Pool dan ID penyedia di pool tersebut. T/A String Hanya jika OAuthMechanism=4
BYOID_CredentialSource Menetapkan informasi yang diperlukan untuk mengambil token itu sendiri, serta beberapa informasi lingkungan. T/A String Hanya jika OAuthMechanism=4
BYOID_PoolUserProject Tetapkan project jika project tersebut adalah Workforce Pool, bukan Workload Identity Pool. T/A String Hanya saat OAuthMechanism=4 dan menggunakan Gabungan Tenaga Kerja
BYOID_SubjectTokenType Menetapkan jenis token STS berdasarkan spesifikasi pertukaran token OAuth 2.0. Nilai yang diharapkan mencakup:
  • 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
 T/A String Hanya jika OAuthMechanism=4
BYOID_TokenUrl Menetapkan endpoint pertukaran token STS. https://sts.googleapis.com/v1/token String Tidak
Catalog ID project BigQuery default untuk driver. Driver menggunakan project ini untuk menjalankan kueri dan menagihnya untuk penggunaan resource. T/A String Ya
DefaultDataset Berfungsi sebagai set data yang ditetapkan dalam project yang dirujuk secara otomatis oleh driver saat Anda menjalankan kueri tanpa menentukan set data secara eksplisit. T/A String Tidak
EnableSession Menentukan apakah koneksi memulai sesi. Jika diaktifkan, kueri pertama yang dijalankan oleh koneksi tertentu akan memulai sesi dan driver meneruskan ID sesi ke semua kueri berikutnya. 0 Boolean Tidak
FilterTablesOnDefaultDataset Menentukan cakupan metadata yang ditampilkan oleh metode metadata tabel atau kolom. Jika salah (0), tidak ada pemfilteran yang terjadi. Anda juga harus menetapkan properti DefaultDataset untuk mengaktifkan pemfilteran. 0 Boolean Tidak
IgnoreTransactions Jika diaktifkan (1 atau TRUE), driver akan melewati penanganan transaksi manual (BEGIN TRANSACTION, COMMIT, ROLLBACK) saat SQL_ATTR_AUTOCOMMIT disetel ke SQL_AUTOCOMMIT_OFF. Opsi ini direkomendasikan untuk alat BI dan klien SQL pihak ketiga (seperti Tableau, Power BI, dan DBeaver) yang menonaktifkan commit otomatis secara default. 0 Boolean Tidak
JobCreationMode Memungkinkan Anda mengaktifkan jalur kueri latensi rendah. Pilih salah satu opsi berikut:
  • 1: Driver membuat tugas untuk setiap kueri (JOB_CREATION_REQUIRED)
  • 2: Driver menjalankan kueri tanpa tugas (JOB_CREATION_OPTIONAL)
 2 Bilangan bulat Tidak
KeyFilePath Jalur ke file JSON kunci akun layanan saat menggunakan autentikasi akun layanan. T/A String Hanya jika OAuthMechanism=0
KMSKeyName Menentukan nama resource kunci Cloud KMS yang akan digunakan saat mengenkripsi dan mendekripsi data. T/A String Tidak
LargeResultsDataSetId Menentukan set data tujuan untuk menyimpan hasil kueri yang besar. T/A String Tidak
LargeResultsTempTableExpirationTime Menentukan masa aktif tabel sementara di LargeResultsDataSetId, dalam milidetik. 3600000 Long Tidak
LogLevel Membatasi detail yang dicatat pengemudi selama interaksi. Untuk informasi selengkapnya, lihat Konfigurasi logging dan driver. Pilih salah satu opsi berikut:
  • 0: OFF
  • 1: ERROR
  • 2: WARNING
  • 3: INFO
 0 Bilangan bulat Tidak
LogPath Menentukan direktori tempat driver menulis file log. Untuk informasi selengkapnya, lihat Konfigurasi logging dan driver. T/A String Tidak
LogFileCount Menentukan jumlah maksimum file log yang akan disimpan. 0 Bilangan bulat Tidak
LogFileSize Menentukan ukuran maksimum setiap file log dalam KB. 0 Long Tidak
MaxRetries Mengonfigurasi jumlah maksimum upaya percobaan ulang yang dilakukan oleh driver dengan backoff eksponensial saat terjadi error BigQuery REST dan gRPC API sementara (seperti batas kapasitas atau HTTP 5xx) sebelum menampilkan error. 6 Bilangan bulat Tidak
MaxThreads Menentukan jumlah maksimum thread yang dapat digunakan driver untuk pemrosesan serentak di kumpulan thread. Untuk mengonfigurasi properti ini sebagai setelan seluruh driver untuk lingkungan non-Windows, tentukan di file googlebigqueryodbc.ini. 8 Bilangan bulat Tidak
OAuthMechanism Jenis autentikasi. Pilih salah satu opsi berikut:
  • 0: Autentikasi akun layanan
  • 3: Autentikasi Kredensial Default Aplikasi
  • 4: Autentikasi Workload Identity Federation atau Workforce Identity Federation
 T/A Bilangan bulat Ya
PrivateServiceConnectUris Endpoint kustom untuk mengganti endpoint default. Contoh:
  • BIGQUERY=https://bigquery.us-east4.rep.googleapis.com/
  • READ_API=bigquerystorage.us-east4.rep.googleapis.com
  • OAUTH2=oauth2.us-east4.rep.googleapis.com
 T/A String yang dipisahkan koma Tidak
ProxyHost Nama host atau alamat IP server proxy. T/A String Tidak
ProxyPort Nomor port tempat server proxy memproses. T/A String Tidak
ProxyPwd Sandi untuk autentikasi saat terhubung melalui server proxy. T/A String Tidak
ProxyUid Nama pengguna untuk autentikasi saat terhubung melalui server proxy. T/A String Tidak
QueryProperties Mengonfigurasi properti yang dapat mengubah perilaku kueri. T/A Map<String, String> Tidak
RefreshToken Token refresh OAuth yang disimpan untuk alur autentikasi pengguna. T/A String Tidak
RowsFetchedPerBlock Menentukan jumlah maksimum baris yang diambil per blok atau halaman hasil dari BigQuery. 100000 Long Tidak
ServiceAccountImpersonationEmail Menentukan alamat email akun layanan target yang akan ditiru identitasnya menggunakan kredensial berbasis pemanggil. Memungkinkan alur kerja delegasi multi-tenant dan hak istimewa terendah tanpa mendistribusikan kunci pribadi akun layanan tambahan. T/A String Tidak
SessionLocation Menentukan lokasi geografis (region atau multi-region) tempat driver membuat atau membuat kueri set data dan menjalankan sesi kueri (misalnya, US, EU, atau us-central1). T/A String Tidak
SQLDialect Menentukan dialek kueri yang akan digunakan. Gunakan 1 untuk GoogleSQL (SQL standar, sangat direkomendasikan) dan 0 untuk legacy SQL. 1 Bilangan bulat Tidak
TrustedCerts Menentukan jalur lengkap ke file sertifikat CA root SSL/TLS berformat PEM kustom (misalnya, roots.pem atau cacerts.pem). Menggantikan file sertifikat bawaan default. T/A String Tidak
UniverseDomain Menentukan domain semesta untuk organisasi Anda. googleapis.com String Tidak
UseDefaultLargeResultsDataset Jika AllowLargeResults=1, menentukan apakah driver secara otomatis merutekan hasil kueri besar ke set data sementara default (_bqodbc_temp_tables). Jika ditetapkan ke 0, LargeResultsDataSetId harus ditentukan secara eksplisit. 1 Boolean Tidak
UseQueryCache Mengaktifkan fitur caching kueri di BigQuery. true Boolean Tidak
UseSystemTrustStore Khusus Windows. Menginstruksikan driver untuk memuat dan memvalidasi sertifikat TLS terhadap Windows Certificate Trust Store, bukan mencari file PEM lokal. 0 Boolean Tidak

Pemetaan jenis data

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

Jenis GoogleSQL Jenis SQL ODBC
INT64SQL_BIGINT
BOOLSQL_BIT
DATESQL_TYPE_DATE
FLOAT64SQL_DOUBLE
TIMESQL_TYPE_TIME
TIMESTAMPSQL_TYPE_TIMESTAMP
DATETIMESQL_TYPE_TIMESTAMP
BYTESSQL_VARBINARY
STRINGSQL_VARCHAR
ARRAYSQL_VARCHAR
STRUCTSQL_VARCHAR
INTERVALSQL_VARCHAR
JSONSQL_VARCHAR
GEOGRAPHYSQL_VARCHAR
RANGESQL_VARCHAR
NUMERICSQL_NUMERIC
BIGNUMERICSQL_NUMERIC

Konfigurasi logging dan driver

Untuk mengonfigurasi opsi di seluruh driver (seperti logging dan encoding karakter), lakukan hal berikut:

Windows

Konfigurasi opsi logging dan DSN menggunakan dialog konfigurasi DSN di ODBC Data Source Administrator.

Non-Windows

  1. Buat atau edit file konfigurasi, seperti googlebigqueryodbc.ini, dan tambahkan opsi driver di bagian [Driver]. Berikut adalah contohnya:

    [Driver]
LogLevel=3
LogPath=/path/to/log/directory
LogFileCount=200
LogFileSize=1000
MaxThreads=8
WcharEncoding=UTF-16LE

  2. Tetapkan variabel lingkungan GOOGLEBIGQUERYODBCINI ke jalur file ini:

    export GOOGLEBIGQUERYODBCINI=/path/to/googlebigqueryodbc.ini

Tingkat logging driver

Driver mendukung tingkat logging 0 hingga 3. Sebaiknya mulai dengan LogLevel=3 (INFO) untuk memecahkan masalah.

Tingkat logging ODBC Deskripsi
0 (NONAKTIF) Menonaktifkan semua logging.
1 (ERROR) Mencatat peristiwa error ke dalam log.
2 (PERINGATAN) Mencatat peristiwa peringatan.
3 (INFO) Mencatat informasi umum yang menjelaskan progres pengemudi.

Properti konfigurasi seluruh driver (Non-Windows)

Properti berikut dapat dikonfigurasi di bagian [Driver] dalam googlebigqueryodbc.ini:

Properti Deskripsi Nilai yang diizinkan Nilai default
WcharEncoding Mengontrol encoding melalui kabel dari buffer karakter SQLWCHAR secara eksplisit saat meneruskan string karakter lebar antara driver dan pengelola driver ODBC (misalnya, WcharEncoding=UTF-16LE). Hal ini menyelesaikan masalah kerusakan dan pemotongan karakter di seluruh unixODBC (biasanya UTF-16LE 2 byte) dan iODBC (biasanya UTF-32LE 4 byte). UTF-8, UTF-16LE, UTF-32LE Kosong (mendeteksi otomatis berdasarkan sizeof(SQLWCHAR))
MaxThreads Menentukan jumlah maksimum thread yang dapat digunakan driver untuk pemrosesan serentak di kumpulan thread. Bilangan bulat positif 8

Contoh

Contoh berikut menunjukkan cara menggunakan kueri berparameter dan skrip multi-pernyataan dengan driver ODBC.

Kueri berparameter

// 1. Prepare statement
std::string insert_stmt = "INSERT INTO MyTable VALUES (?, ?, ?)";
status = SQLPrepare(hstmt, (SQLCHAR*)insert_stmt.c_str(), SQL_NTS);

// 2. Bind parameters
std::string str_val = "example_string";
long long int_val = 12345;
double float_val = 1.2345;

// Bind string field
status = SQLBindParameter(
    hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR, 50, 0,
    (SQLPOINTER)str_val.c_str(), str_val.size(), NULL);

// Bind integer field
status = SQLBindParameter(
    hstmt, 2, SQL_PARAM_INPUT, SQL_C_UBIGINT, SQL_BIGINT, 0, 0,
    &int_val, 0, NULL);

// Bind float field
status = SQLBindParameter(
    hstmt, 3, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_DOUBLE, 0, 0,
    &float_val, 0, NULL);

// 3. Execute statement
status = SQLExecute(hstmt);

Skrip multi-pernyataan

// 1. Prepare and execute the multi-statement script
std::string query =
    "CREATE OR REPLACE TABLE MyTable (StringField STRING, IntegerField INTEGER); "
    "INSERT INTO MyTable VALUES ('example', 123); "
    "SELECT * FROM MyTable;";

status = SQLExecDirect(hstmt, (SQLCHAR*)query.c_str(), SQL_NTS);

// 2. Process results for each statement using SQLMoreResults
do {
    SQLSMALLINT num_cols;
    status = SQLNumResultCols(hstmt, &num_cols);

    if (num_cols > 0) {
        // This is a result-returning statement (e.g., SELECT)
        while (SQLFetch(hstmt) == SQL_SUCCESS) {
            // Process rows...
        }
    } else {
        // This is a non-result statement (e.g., CREATE, INSERT)
        SQLLEN row_count;
        SQLRowCount(hstmt, &row_count);
        // Process affected rows...
    }
} while (SQLMoreResults(hstmt) == SQL_SUCCESS);

Harga

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

Langkah berikutnya