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: Driver ODBC untuk BigQuery tersedia dengan lisensi Apache 2.0. Untuk meminta masukan atau dukungan terkait fitur ini, kirim email ke [e-mail].

Driver Open Database Connectivity (ODBC) untuk BigQuery menghubungkan aplikasi Anda ke BigQuery. Hal ini memungkinkan Anda menggunakan fitur BigQuery dengan alat dan infrastruktur pilihan Anda.

Sebelum memulai

1. Pastikan Anda memahami driver Open Database Connectivity (ODBC) dan pengelola driver.

2. Perhatikan persyaratan sistem berikut:

   Sistem Operasi	Arsitektur yang Didukung	Versi Minimum dan Dependensi
   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. Identifikasi jenis koneksi Anda untuk driver ODBC untuk BigQuery. Driver mendukung metode autentikasi berikut:

   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 atau jenis STS lainnya	BYOID_SubjectTokenType
   	Endpoint pertukaran token STS	URL endpoint STS kustom	BYOID_TokenUrl
   Kredensial Default Aplikasi	T/A	T/A	T/A

Menginstal dan mengonfigurasi driver ODBC

Bagian ini menjelaskan cara menginstal dan mengonfigurasi driver ODBC untuk sistem operasi Windows dan non-Windows.

Windows

Di Windows, pastikan Anda menginstal arsitektur driver yang sesuai dengan arsitektur aplikasi Anda. Misalnya, gunakan driver 64-bit untuk aplikasi 64-bit dan driver 32-bit untuk aplikasi 32-bit. Sistem Windows 64-bit mendukung aplikasi 32-bit dan 64-bit.

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

Membuat Nama Sumber Data

Untuk membuat Nama Sumber Data di Windows:

1. Dari menu Start, buka ODBC Data Sources, lalu pilih versi yang memiliki bit yang sama dengan aplikasi klien Anda untuk memastikan koneksi yang tepat ke BigQuery.
2. Di ODBC Data Source Administrator, klik tab Drivers.
3. Temukan ODBC Driver for BigQuery sebagaimana muncul dalam daftar alfabetis driver ODBC yang diinstal.
4. Pilih salah satu opsi berikut:
   • Untuk membuat DSN bagi pengguna saat ini, klik tab DSN Pengguna.
   • Untuk membuat DSN bagi semua pengguna, klik tab System DSN. DSN sistem direkomendasikan karena beberapa aplikasi memuat data menggunakan akun pengguna yang berbeda dan mungkin tidak mendeteksi DSN Pengguna yang dibuat di akun pengguna lain.
5. Klik Tambahkan.
6. Di dialog Create New Data Source, pilih ODBC Driver for BigQuery lalu klik Finish.
7. Dialog ODBC Driver for BigQuery DSN Setup akan terbuka.
8. Di kolom Nama Sumber Data, ketik nama untuk DSN Anda.
9. Lihat bagian Properti Koneksi untuk memahami nilai yang harus diisi.

Non-Windows

Distribusi Linux 64-bit mendukung aplikasi 32-bit dan 64-bit. Pastikan arsitektur driver ODBC cocok dengan aplikasi yang ingin Anda gunakan. Misalnya, gunakan driver 64-bit untuk aplikasi 64-bit dan driver 32-bit untuk aplikasi 32-bit. Anda dapat menginstal kedua arsitektur driver secara bersamaan di satu sistem.

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

Untuk menginstal konektor menggunakan paket file tar atau zip:

1. Buat direktori tempat Anda ingin menginstal konektor, jika belum ada.
2. Ekstrak file zip utama ke lokasi sementara yang mudah diakses.
3. Buka folder file tar atau zip yang diekstrak, lalu (opsional) salin semua file dan folder ke direktori penginstalan.
4. Setelah ekstraksi, jalur objek bersama ODBC Driver for BigQuery adalah [INSTALLDIR]/lib/libgoogle_cloud_odbc_bq_driver.so. Perbarui file .ini Anda untuk mencerminkan jalur konektor yang benar.

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

Membuat koneksi

Untuk membuat koneksi menggunakan driver ODBC untuk BigQuery, Anda dapat menggunakan string koneksi atau DSN.

Format string koneksi

Driver=ODBC Driver for BigQuery;ProjectId=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 atau Workforce Identity Federation
• AUTH_PROPS: informasi autentikasi yang Anda catat saat Anda melakukan autentikasi ke BigQuery.
• OTHER_PROPS (opsional): properti koneksi tambahan untuk driver ODBC.

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	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 pengemudi dapat menggunakan Read API.	0	Boolean	Tidak
AllowLargeResults	Menentukan apakah Driver ODBC harus memproses hasil kueri yang lebih besar dari 128 MB saat menggunakan SQL lama (QueryDialect=BIG_QUERY).	0	Boolean	Tidak
BYOID_AudienceUrl	Audiens 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 ini jika berupa 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/kolom. Jika FALSE, pemfilteran tidak akan terjadi. 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	Memungkinkan Anda menentukan nama kunci KMS yang akan digunakan saat mengenkripsi dan mendekripsi data.	T/A	String	Tidak
LargeResultsDataSetId	Memungkinkan Anda menentukan set data tujuan untuk menyimpan hasil kueri yang besar.	T/A	String	Tidak
LargeResultsDatasetExpirationTime	Memungkinkan Anda menentukan masa aktif semua tabel dalam set data hasil besar, dalam milidetik.	3600000	Long	Tidak
Location	Memungkinkan Anda menentukan lokasi tempat driver membuat atau mengkueri set data.	T/A	String	Tidak
LogLevel	Membatasi detail yang dicatat driver selama interaksi. Pilih salah satu opsi berikut: 0: OFF 1: ERROR 2: WARNING 3: INFO	0	Bilangan bulat	Tidak
LogPath	Memungkinkan Anda menentukan direktori tempat driver menulis file log.	T/A	String	Tidak
LogFileCount	Memungkinkan Anda menetapkan jumlah maksimum file log yang akan disimpan.	0	Bilangan bulat	Tidak
LogFileSize	Memungkinkan Anda menetapkan ukuran maksimum setiap file log dalam byte.	0	Long	Tidak
MaxResults	Memungkinkan Anda menentukan jumlah hasil per halaman di 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 seluruh konektor untuk konektor non-Windows (Linux/macOS), Anda menentukannya dalam 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 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	Memungkinkan Anda mengaktifkan fitur caching kueri di BigQuery.	true	Boolean	Tidak

Menjalankan kueri dengan driver

Bagian ini memberikan informasi tentang pemetaan jenis data dan contoh untuk menjalankan kueri dengan driver ODBC.

Pemetaan jenis data

Saat Anda menjalankan kueri melalui driver ODBC untuk BigQuery, pemetaan jenis data berikut akan terjadi (berdasarkan jenis SQL ODBC standar):

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

Membuat kueri melalui driver ODBC untuk BigQuery tunduk pada harga analisis BigQuery standar.