Menggunakan driver ODBC untuk BigQuery

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.

Catatan: Untuk meminta masukan atau dukungan terkait fitur ini, kirim email ke [e-mail].

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

   • Download file ODBCDriverforBigQuery_windows_x86.msi untuk aplikasi 32-bit.
   • Download file ODBCDriverforBigQuery_windows_x64.msi untuk aplikasi 64-bit.

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:

   • Download file ODBCDriverforBigQuery_linux_latest.zip untuk Linux.
   • Download file ODBCDriverforBigQuery_macos_latest.tar.gz untuk macOS.

2. Ekstrak konten file ZIP atau TAR yang didownload.

3. Pindahkan konten file ZIP atau TAR ke direktori tempat Anda ingin menginstal konektor. 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 konektor yang baru.

   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;ProjectId=PROJECT_ID;OAuthType=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, 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.

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
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 QueryDialect disetel ke BIG_QUERY. Jika properti QueryDialect disetel ke SQL, driver akan selalu memproses hasil kueri yang 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 Oauth2.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
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
FilterTablesOnDefaultDataset	Menentukan cakupan metadata yang ditampilkan oleh metode metadata tabel atau kolom. Jika salah (false), pemfilteran tidak akan berfungsi. Anda juga harus menetapkan properti DefaultDataset untuk mengaktifkan pemfilteran.	FALSE	Boolean	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
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 kunci akun layanan saat menggunakan autentikasi akun layanan.	T/A	String	Hanya jika OAuthMechanism=0
KMSKeyName	Menentukan nama kunci 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
LargeResultsDatasetExpirationTime	Menentukan masa aktif semua tabel dalam set data hasil besar, dalam milidetik.	3600000	Long	Tidak
Location	Menentukan lokasi tempat pengemudi membuat atau mengkueri set data.	T/A	String	Tidak
LogLevel	Membatasi detail yang dicatat pengemudi selama interaksi. 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.	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 byte.	0	Long	Tidak
MaxResults	Menentukan jumlah hasil per halaman dalam hasil BigQuery API.	10000	Long	Tidak
MaxThreads	Menentukan jumlah maksimum thread yang dapat digunakan konektor untuk pemrosesan serentak dalam kumpulan thread. Untuk mengonfigurasi properti ini sebagai setelan di seluruh konektor untuk konektor 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
ProjectId	Project ID default untuk driver. Driver menggunakan project ini untuk menjalankan kueri dan menagihnya untuk penggunaan resource.	T/A	String	Ya
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
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
QueryDialect	Menentukan dialek kueri yang akan digunakan. Gunakan SQL untuk GoogleSQL (sangat direkomendasikan) dan BIG_QUERY untuk legacy SQL.	SQL	String	Tidak
QueryProperties	Mengonfigurasi properti yang dapat mengubah perilaku kueri.	T/A	Map<String, String>	Tidak
UniverseDomain	Menentukan domain semesta untuk organisasi Anda.	googleapis.com	String	Tidak
UseQueryCache	Mengaktifkan fitur caching kueri di BigQuery.	true	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
INT64	SQL_BIGINT
BOOL	SQL_BIT
DATE	SQL_TYPE_DATE
FLOAT64	SQL_DOUBLE
TIME	SQL_TYPE_TIME
TIMESTAMP	SQL_TYPE_TIMESTAMP
DATETIME	SQL_TYPE_TIMESTAMP
BYTES	SQL_VARBINARY
STRING	SQL_VARCHAR
ARRAY	SQL_VARCHAR
STRUCT	SQL_VARCHAR
INTERVAL	SQL_VARCHAR
JSON	SQL_VARCHAR
GEOGRAPHY	SQL_VARCHAR
RANGE	SQL_VARCHAR
NUMERIC	SQL_NUMERIC
BIGNUMERIC	SQL_NUMERIC

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

• Pelajari lebih lanjut driver JDBC untuk BigQuery.
• Pelajari alat developer BigQuery lainnya.