使用 BigQuery 的 ODBC 驅動程式

BigQuery 的開放式資料庫連線 (ODBC) 驅動程式可將非 Java 應用程式連線至 BigQuery，讓您使用偏好的工具和基礎架構，運用 BigQuery 功能。如要將 Java 應用程式連線至 BigQuery，請使用 BigQuery 專用的 JDBC 驅動程式。

BigQuery 的 ODBC 驅動程式是依據 Apache 2.0 授權提供。

事前準備

1. 請務必熟悉 ODBC 驅動程式和驅動程式管理員。

2. 確認作業系統符合下列規定：

   作業系統	支援的架構	最低版本和依附元件
   Windows	32 位元 (x86)、64 位元 (x64)	版本：Windows 10、Windows Server 2016 以上版本 相依性：適用於 Visual Studio 2019 或 2022 的 Microsoft Visual C++ 可轉散發套件
   macOS	64 位元 (x86_64)、ARM64 (Apple Silicon)	版本：macOS 12 (Monterey) 以上版本 相依性：ODBC 驅動程式管理員 (例如 unixODBC)。請務必將安裝目錄新增至 DYLD_LIBRARY_PATH。
   Linux	64 位元 (x86_64)	版本：任何具有 glibc 2.27 以上版本的發行版本 (例如 Ubuntu 20.04 LTS+、Debian 11+) 依附元件：ODBC 驅動程式管理員 (例如 unixODBC)。請務必將安裝目錄新增至 LD_LIBRARY_PATH。

3. 向 BigQuery 進行驗證，並記下下列資訊，稍後使用 BigQuery 的 ODBC 驅動程式建立連線時會用到。您只需要注意與所用驗證方法對應的資訊。

   驗證方式	驗證資訊	範例	連結資源 (稍後設定)
   標準服務帳戶	服務帳戶金鑰 (JSON 物件)	my-sa-key.json	KeyFilePath
   服務帳戶模擬	目標服務帳戶電子郵件地址	[e-mail]	ServiceAccountImpersonationEmail, KeyFilePath
   Workload Identity Federation 或 Workforce Identity Federation	外部帳戶設定檔的目標對象屬性	//iam.googleapis.com/locations/global/...	BYOID_AudienceUrl
   	權杖擷取和環境資訊檔案	{"file":"/path/to/file"}	BYOID_CredentialSource
   	使用者專案 (僅限工作團隊集區)	my_project	BYOID_PoolUserProject
   	STS 權杖類型	id_token	BYOID_SubjectTokenType
   	STS 權杖交換端點	https://sts.googleapis.com/v1/token	BYOID_TokenUrl
   應用程式預設憑證	無	不適用	不適用

安裝及設定 ODBC 驅動程式

您可以使用 Windows 或非 Windows 作業系統，安裝及設定 BigQuery 的 ODBC 驅動程式。

Windows

1. 安裝與應用程式架構對應的驅動程式：

   • 下載 32 位元應用程式的 ODBCDriverforBigQuery_windows_x86.msi 檔案。
   • 下載 64 位元應用程式的 ODBCDriverforBigQuery_windows_x64.msi 檔案。

2. 請按照下列步驟建立資料來源名稱 (DSN)：

   1. 在 Windows「開始」功能表中，前往「ODBC Data Sources」，然後選取與用戶端應用程式位元數相同的版本。
   2. 在「ODBC Data Source Administrator」(ODBC 資料來源管理員) 頁面中，按一下「Drivers」(驅動程式) 分頁標籤。
   3. 在已安裝的 ODBC 驅動程式清單中，找出「ODBC Driver for BigQuery」。
   4. 選取「系統 DSN」分頁標籤，為所有使用者建立 DSN；或選取「使用者 DSN」分頁標籤，為目前使用者建立 DSN。一般來說，建議使用系統 DSN，因為部分應用程式會使用不同的使用者帳戶載入資料，可能無法偵測到其他使用者 DSN。
   5. 按一下「新增」。
   6. 在「建立新的資料來源」對話方塊中，選取「BigQuery 的 ODBC 驅動程式」，然後點選「完成」。「ODBC Driver for BigQuery DSN Setup」(適用於 BigQuery 的 ODBC 驅動程式 DSN 設定) 對話方塊隨即開啟。
   7. 在「資料來源名稱」欄位中，輸入 DSN 的名稱。
   8. 新增連線屬性。如需完整的屬性清單，請參閱「連線屬性」。

非 Windows

1. 安裝與作業系統對應的驅動程式：

   • 下載 Linux 專用的 ODBCDriverforBigQuery_linux_latest.zip 檔案。
   • 下載 macOS 適用的 ODBCDriverforBigQuery_macos_latest.tar.gz 檔案。

2. 擷取下載的 ZIP 或 TAR 檔案內容。

3. 將 ZIP 或 TAR 檔案的內容移至要安裝驅動程式的目錄。BigQuery 的 ODBC 驅動程式共用物件路徑為 INSTALL_DIR/lib/libgoogle_cloud_odbc_bq_driver.so，其中 INSTALL_DIR 是安裝目錄。

4. 更新 .ini 檔案，反映驅動程式的新路徑。

   以下範例會更新 Linux 系統中的 .ini 檔案：

   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

   將 VERSION 替換為驅動程式版本。

先前版本的 BigQuery ODBC 驅動程式

1.3.1

• Windows 32 位元 (x86)
• Windows 64 位元 (x64)
• Linux
• macOS

建立連線

如要使用 BigQuery 的 ODBC 驅動程式，在應用程式與 BigQuery 之間建立連線，請找出連線字串。如果您已透過 DSN 設定連線屬性，可以略過這個步驟。

連線字串的格式如下：

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

更改下列內容：

• PROJECT_ID：BigQuery 專案的 ID。
• AUTH_TYPE：指定您使用的驗證類型。選取下列其中一個選項：
  • 0：用於服務帳戶驗證
  • 3：用於應用程式預設憑證驗證
  • 4：適用於 Workload Identity Federation 或 Workforce Identity Federation 驗證
• AUTH_PROPS：您向 BigQuery 驗證身分時記下的驗證資訊，格式為 property_1=value_1; property_2=value_2;...，例如 KeyFilePath=my-sa-key.json (如果您使用服務帳戶驗證身分)。
• OTHER_PROPS (選用)：ODBC 驅動程式的其他連線屬性，以 property_1=value_1; property_2=value_2;... 格式列出。如需連線屬性的完整清單，請參閱「連線屬性」。

連線屬性

ODBC 驅動程式連線屬性是設定參數，您可以在建立資料庫連線時，將這些參數納入連線字串。BigQuery 的 ODBC 驅動程式支援下列連線屬性。

注意： 所有連線屬性名稱都不區分大小寫。布林值連線屬性接受 TRUE/FALSE 和 1/0。

連結資源	說明	預設值	資料類型	必要
AdditionalProjects	除了 Catalog 屬性設定的主要專案外，驅動程式還可存取哪些專案，以進行查詢和中繼資料作業。	不適用	以半形逗號分隔的字串	否
AllowHtapiForLargeResults	決定驅動程式是否可以使用 BigQuery Storage Read API。	0	布林值	否
AllowLargeResults	判斷驅動程式是否會在 SQLDialect 屬性設為 0 (舊版 SQL) 時，處理大於 128 MB 的查詢結果。如果 SQLDialect 屬性設為 1 (GoogleSQL)，驅動程式一律會處理大型查詢結果。	0	布林值	否
BYOID_AudienceUrl	包含 Workload Identity Pool 或 Workforce Pool 的資源名稱，以及該集區中的提供者 ID。	不適用	字串	僅限 OAuthMechanism=4
BYOID_CredentialSource	設定擷取權杖本身所需的資訊，以及部分環境資訊。	不適用	字串	僅限 OAuthMechanism=4
BYOID_PoolUserProject	如果專案是工作團隊集區，而非工作負載身分集區，請設定專案。	不適用	字串	僅限 OAuthMechanism=4 和使用工作團隊集區時
BYOID_SubjectTokenType	根據 OAuth 2.0 權杖交換規格設定 STS 權杖類型。預期值包括： 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	不適用	字串	僅限 OAuthMechanism=4
BYOID_TokenUrl	設定 STS 權杖交換端點。	https://sts.googleapis.com/v1/token	字串	否
Catalog	驅動程式的預設 BigQuery 專案 ID。驅動程式會使用這個專案執行查詢，並根據資源用量計費。	不適用	字串	是
DefaultDataset	做為專案中指定的資料集，當您執行查詢時，如果沒有明確指定資料集，系統會自動參照這個資料集。	不適用	字串	否
EnableSession	決定連線是否會啟動工作階段。啟用後，該連線執行的第一個查詢會啟動工作階段，且驅動程式會將工作階段 ID 傳遞至所有後續查詢。	0	布林值	否
FilterTablesOnDefaultDataset	決定資料表或資料欄中繼資料方法傳回的中繼資料範圍。如果為 false (0)，則不會進行篩選。您還必須設定 DefaultDataset 屬性，才能啟用篩選功能。	0	布林值	否
IgnoreTransactions	啟用時 (1 或 TRUE)，如果 SQL_ATTR_AUTOCOMMIT 設為 SQL_AUTOCOMMIT_OFF，驅動程式會略過手動交易處理 (BEGIN TRANSACTION、COMMIT、ROLLBACK)。如果第三方 BI 和 SQL 用戶端工具 (例如 Tableau、Power BI 和 DBeaver) 預設會停用自動提交，建議您使用這項功能。	0	布林值	否
JobCreationMode	可啟用低延遲查詢路徑。選擇下列其中一個選項： 1：驅動程式會為每個查詢建立工作 (JOB_CREATION_REQUIRED) 2：驅動程式執行查詢時沒有工作 (JOB_CREATION_OPTIONAL)	2	整數	否
KeyFilePath	使用服務帳戶驗證時，服務帳戶金鑰 JSON 檔案的路徑。	不適用	字串	僅限 OAuthMechanism=0
KMSKeyName	指定加密及解密資料時使用的 Cloud KMS 金鑰資源名稱。	不適用	字串	否
LargeResultsDataSetId	指定用於儲存大型查詢結果的目的地資料集。	不適用	字串	否
LargeResultsTempTableExpirationTime	指定 LargeResultsDataSetId 中暫時資料表的生命週期 (以毫秒為單位)。	3600000	Long	否
LogLevel	限制駕駛人在互動期間記錄的詳細資料。詳情請參閱「記錄和驅動程式設定」。選擇下列其中一個選項： 0：OFF 1：ERROR 2：WARNING 3：INFO	0	整數	否
LogPath	指定驅動程式寫入記錄檔的目錄。詳情請參閱「記錄和驅動程式設定」。	不適用	字串	否
LogFileCount	指定要保留的記錄檔數量上限。	0	整數	否
LogFileSize	以 KB 為單位指定每個記錄檔的大小上限。	0	Long	否
MaxRetries	設定驅動程式在遇到暫時性 BigQuery REST 和 gRPC API 錯誤 (例如速率限制或 HTTP 5xx) 時，執行指數輪詢重試的最大次數，超過此次數就會傳回錯誤。	6	整數	否
MaxThreads	定義驅動程式可在執行緒集區中用於並行處理的執行緒數量上限。如要將這個屬性設為非 Windows 環境的驅動程式全域設定，請在 googlebigqueryodbc.ini 檔案中指定這個屬性。	8	整數	否
OAuthMechanism	驗證類型。選擇下列其中一個選項： 0：服務帳戶驗證 3：應用程式預設憑證驗證 4：Workload Identity Federation 或 Workforce Identity Federation 驗證	不適用	整數	是
PrivateServiceConnectUris	用來覆寫預設端點的自訂端點。示例： BIGQUERY=https://bigquery.us-east4.rep.googleapis.com/ READ_API=bigquerystorage.us-east4.rep.googleapis.com OAUTH2=oauth2.us-east4.rep.googleapis.com	不適用	以半形逗號分隔的字串	否
ProxyHost	Proxy 伺服器的主機名稱或 IP 位址。	不適用	字串	否
ProxyPort	Proxy 伺服器監聽的通訊埠號碼。	不適用	字串	否
ProxyPwd	透過 Proxy 伺服器連線時，用於驗證的密碼。	不適用	字串	否
ProxyUid	透過 Proxy 伺服器連線時，用於驗證的使用者名稱。	不適用	字串	否
QueryProperties	設定可修改查詢行為的屬性。	不適用	Map<String, String>	否
RefreshToken	為使用者驗證流程儲存的 OAuth 更新權杖。	不適用	字串	否
RowsFetchedPerBlock	指定從 BigQuery 擷取每個區塊或結果頁面的資料列數上限。	100000	Long	否
ServiceAccountImpersonationEmail	使用呼叫端基本憑證指定要模擬的目標服務帳戶電子郵件地址。啟用多租戶和最小權限委派工作流程，不必發布額外的服務帳戶私密金鑰。	不適用	字串	否
SessionLocation	指定驅動程式建立或查詢資料集，以及執行查詢工作階段的地理位置 (區域或多區域)，例如 US、EU 或 us-central1。	不適用	字串	否
SQLDialect	指定要使用的查詢方言。使用 1 代表 GoogleSQL (標準 SQL，強烈建議使用)，0 代表舊版 SQL。	1	整數	否
TrustedCerts	指定自訂 PEM 格式 SSL/TLS 根 CA 憑證檔案的完整路徑 (例如 roots.pem 或 cacerts.pem)。覆寫預設的套裝組合憑證檔案。	不適用	字串	否
UniverseDomain	指定貴機構的 Universe 網域。	googleapis.com	字串	否
UseDefaultLargeResultsDataset	AllowLargeResults=1：決定驅動程式是否自動將大型查詢結果路徑導向預設暫時資料集 (_bqodbc_temp_tables)。設為 0 時，必須明確指定 LargeResultsDataSetId。	1	布林值	否
UseQueryCache	在 BigQuery 中啟用查詢快取功能。	true	布林值	否
UseSystemTrustStore	僅適用於 Windows。指示驅動程式載入及驗證 Windows 憑證信任存放區中的 TLS 憑證，而非尋找本機 PEM 檔案。	0	布林值	否

資料類型對應

透過 BigQuery 的 ODBC 驅動程式執行查詢時，系統會進行下列資料類型對應：

GoogleSQL 類型	ODBC SQL 類型
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

記錄和驅動程式設定

如要設定全驅動程式選項 (例如記錄和字元編碼)，請按照下列步驟操作：

Windows

使用 ODBC 資料來源管理員中的 DSN 設定對話方塊，設定記錄和 DSN 選項。

非 Windows

1. 建立或編輯設定檔 (例如 googlebigqueryodbc.ini)，並在 [Driver] 區段下方新增驅動程式選項。以下是範例：

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

2. 將 GOOGLEBIGQUERYODBCINI 環境變數設為這個檔案的路徑：

   export GOOGLEBIGQUERYODBCINI=/path/to/googlebigqueryodbc.ini
   

注意： 您可能需要重新啟動應用程式，變更才會生效。

驅動程式記錄層級

驅動程式支援記錄層級 0 到 3。建議先從 LogLevel=3 (INFO) 開始排解問題。

ODBC 記錄層級	說明
0 (關閉)	停用所有記錄功能。
1 (ERROR)	記錄錯誤事件。
2 (警告)	記錄警告事件。
3 (INFO)	記錄說明駕駛人進度的一般資訊。

驅動程式層級的設定屬性 (非 Windows)

您可以在 googlebigqueryodbc.ini 的 [Driver] 區段中設定下列屬性：

屬性	說明	允許的值	預設值
WcharEncoding	在驅動程式和 ODBC 驅動程式管理器之間傳遞寬字元字串時，明確控管 SQLWCHAR 字元緩衝區的線路編碼 (例如 WcharEncoding=UTF-16LE)。這可解決 unixODBC (通常為 2 位元組 UTF-16LE) 和 iODBC (通常為 4 位元組 UTF-32LE) 的字元損毀和截斷問題。	UTF-8、UTF-16LE、UTF-32LE	空白 (系統會根據 sizeof(SQLWCHAR) 自動偵測)
MaxThreads	定義驅動程式可在執行緒集區中用於並行處理的執行緒數量上限。	正整數	8

範例

下列範例說明如何搭配 ODBC 驅動程式使用參數化查詢和多重陳述式指令碼。

參數化查詢

// 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);

多重陳述式指令碼

// 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);

定價

您可以免費下載 BigQuery 的 ODBC 驅動程式。 不過，使用驅動程式時，須支付標準 BigQuery 分析價格。

後續步驟

• 進一步瞭解 BigQuery 的 JDBC 驅動程式。
• 探索其他 BigQuery 開發人員工具。