使用 BigQuery 的 ODBC 驅動程式

預覽

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

注意：BigQuery 的 ODBC 驅動程式適用於 Apache 2.0 授權。如要尋求支援或針對這項功能提供意見回饋，請傳送電子郵件至 [e-mail]。

BigQuery 的開放式資料庫連線 (ODBC) 驅動程式可將應用程式連線至 BigQuery。這樣一來，您就能透過偏好的工具和基礎架構使用 BigQuery 功能。

事前準備

1. 請務必熟悉 Open Database Connectivity (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 晶片)	版本：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 ODBC 驅動程式的連線類型。驅動程式支援下列驗證方法：

   驗證方式	驗證資訊	範例	連結資源 (稍後設定)
   標準服務帳戶	服務帳戶金鑰 (JSON 物件)	my-sa-key	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 或其他 STS 類型	BYOID_SubjectTokenType
   	STS 權杖交換端點	自訂 STS 端點網址	BYOID_TokenUrl
   應用程式預設憑證	不適用	不適用	不適用

安裝及設定 ODBC 驅動程式

本節說明如何為 Windows 和非 Windows 作業系統安裝及設定 ODBC 驅動程式。

Windows

在 Windows 上，請務必安裝與應用程式架構相符的驅動程式架構。舉例來說，64 位元應用程式應使用 64 位元驅動程式，32 位元應用程式則應使用 32 位元驅動程式。64 位元 Windows 系統同時支援 32 位元和 64 位元應用程式。

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

建立資料來源名稱

如要在 Windows 中建立資料來源名稱，請按照下列步驟操作：

1. 從「開始」選單前往「ODBC 資料來源」，然後選取與用戶端應用程式位元數相同的版本，確保能正確連線至 BigQuery。
2. 在 ODBC 資料來源管理工具中，按一下「驅動程式」分頁標籤。
3. 在已安裝的 ODBC 驅動程式字母清單中，找出 BigQuery 專用的 ODBC 驅動程式。
4. 選擇下列其中一個選項：
   • 如要為目前使用者建立 DSN，請按一下「使用者 DSN」分頁標籤。
   • 如要為所有使用者建立 DSN，請按一下「系統 DSN」分頁標籤。建議使用系統 DSN，因為部分應用程式會使用不同的使用者帳戶載入資料，可能無法偵測到在其他使用者帳戶下建立的使用者 DSN。
5. 按一下「新增」。
6. 在「建立新資料來源」對話方塊中，選取「BigQuery 的 ODBC 驅動程式」，然後按一下「完成」。
7. 「ODBC Driver for BigQuery DSN Setup」(適用於 BigQuery 的 ODBC 驅動程式 DSN 設定) 對話方塊隨即開啟。
8. 在「資料來源名稱」欄位中，輸入 DSN 的名稱。
9. 如要瞭解要填入哪些值，請參閱「連線屬性」一節。

非 Windows

64 位元 Linux 發行版本支援 32 位元和 64 位元應用程式。請確認 ODBC 驅動程式的架構與您要使用的應用程式相符。舉例來說，64 位元應用程式應使用 64 位元驅動程式，32 位元應用程式則應使用 32 位元驅動程式。您可以在單一系統上同時安裝這兩種驅動程式架構。

• 下載 Linux 版 ODBCDriverforBigQuery_linux_latest.zip
• 下載 macOS 版 ODBCDriverforBigQuery_macos_latest.tar.gz

如要使用 tar 或 zip 檔案包安裝連接器，請按照下列步驟操作：

1. 如果尚未建立要安裝連接器的目錄，請加以建立。
2. 將主要 ZIP 檔案解壓縮至方便存取的暫時位置。
3. 前往解壓縮的 tar 或 zip 檔案所在的資料夾，然後 (選擇性) 將所有檔案和資料夾複製到安裝目錄。
4. 解壓縮後，BigQuery 共用物件的 ODBC 驅動程式路徑為 [INSTALLDIR]/lib/libgoogle_cloud_odbc_bq_driver.so。更新 .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

建立連線

如要使用 BigQuery 的 ODBC 驅動程式建立連線，您可以使用連線字串或 DSN。

連線字串格式

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

更改下列內容：

• PROJECT_ID：BigQuery 專案的 ID。
• AUTH_TYPE：指定所用驗證類型的數字。選擇下列其中一個選項：
  • 0：用於服務帳戶驗證
  • 3：用於應用程式預設憑證驗證
  • 4：用於工作負載或員工身分聯盟驗證
• AUTH_PROPS：您向 BigQuery 驗證時記下的驗證資訊。
• OTHER_PROPS (選用)：ODBC 驅動程式的其他連線屬性。

連線屬性

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

注意： 所有連線屬性名稱都不區分大小寫。

連結資源	說明	預設值	資料類型	必要
AdditionalProjects	除了 ProjectId 屬性設定的主要專案外，驅動程式還可存取哪些專案以進行查詢和中繼資料作業。	不適用	以半形逗號分隔的字串	否
AllowHtapiForLargeResults	決定驅動程式是否能使用 Read API。	0	布林值	否
AllowLargeResults	指定使用舊版 SQL (QueryDialect=BIG_QUERY) 時，ODBC 驅動程式是否應處理大於 128 MB 的查詢結果。	0	布林值	否
BYOID_AudienceUrl	對象包含 Workload Identity Pool 或 Workforce Pool 的資源名稱，以及該集區中的提供者 ID。	不適用	字串	只有在 OAuthMechanism=4 時
BYOID_CredentialSource	設定擷取權杖本身所需的資訊，以及部分環境資訊。	不適用	字串	只有在 OAuthMechanism=4 時
BYOID_PoolUserProject	如果是 Workforce Pool，而非 Workload Identity Pool，請設定此項目。	不適用	字串	僅限 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	字串	否
DefaultDataset	做為專案中指定的資料集，當您執行查詢時，如果沒有明確指定資料集，系統會自動參照這個資料集。	不適用	字串	否
FilterTablesOnDefaultDataset	決定資料表/資料欄中繼資料方法傳回的中繼資料範圍。如果設為 FALSE，系統就不會執行篩選作業。您還必須設定 DefaultDataset 屬性，才能啟用篩選功能。	FALSE	布林值	否
EnableSession	決定連線是否會啟動工作階段。啟用後，該連線執行的第一個查詢會啟動工作階段，且驅動程式會將工作階段 ID 傳遞至所有後續查詢。	0	布林值	否
JobCreationMode	可啟用低延遲查詢路徑。選擇下列其中一個選項： 1：驅動程式會為每個查詢建立工作 (JOB_CREATION_REQUIRED) 2：驅動程式會執行查詢，但不會建立工作 (JOB_CREATION_OPTIONAL)	2	整數	否
KeyFilePath	使用服務帳戶驗證時，服務帳戶金鑰的路徑。	不適用	字串	僅限 OAuthMechanism=0
KMSKeyName	可讓您指定加密及解密資料時要使用的 KMS 金鑰名稱。	不適用	字串	否
LargeResultsDataSetId	可指定目的地資料集，用來儲存大型查詢結果。	不適用	字串	否
LargeResultsDatasetExpirationTime	可讓您以毫秒為單位，指定大型結果資料集中所有資料表的生命週期。	3600000	Long	否
Location	可讓您指定驅動程式建立或查詢資料集的位置。	不適用	字串	否
LogLevel	限制驅動程式在互動期間記錄的詳細資料。選擇下列其中一個選項： 0：OFF 1：ERROR 2：WARNING 3：INFO	0	整數	否
LogPath	可指定驅動程式寫入記錄檔的目錄。	不適用	字串	否
LogFileCount	可設定要保留的記錄檔數量上限。	0	整數	否
LogFileSize	可設定每個記錄檔的大小上限 (以位元組為單位)。	0	Long	否
MaxResults	可讓您在 BigQuery API 結果中指定每頁的結果數。	10000	Long	否
MaxThreads	定義連接器可在執行緒集區中用於並行處理的執行緒數量上限。如要將這項屬性設為非 Windows (Linux/macOS) 連接器的連接器層級設定，請在 googlebigqueryodbc.ini 檔案中指定這項屬性。	8	整數	否
OAuthMechanism	驗證類型。選擇下列其中一個選項： 0：服務帳戶驗證 3：應用程式預設憑證驗證 4：工作負載或員工身分聯盟驗證	不適用	整數	是
ProjectId	驅動程式的預設專案 ID。驅動程式會使用這個專案執行查詢，並根據資源用量計費。	不適用	字串	是
ProxyHost	Proxy 伺服器的主機名稱或 IP 位址。	不適用	字串	否
ProxyPort	Proxy 伺服器監聽的通訊埠號碼。	不適用	字串	否
ProxyPwd	透過 Proxy 伺服器連線時，用於驗證的密碼。	不適用	字串	否
ProxyUid	透過 Proxy 伺服器連線時，用於驗證的使用者名稱。	不適用	字串	否
PrivateServiceConnectUris	自訂端點，可覆寫預設端點。示例： BIGQUERY=https://bigquery.us-east4.rep.googleapis.com/ READ_API=bigquerystorage.us-east4.rep.googleapis.com OAUTH2=oauth2.us-east4.rep.googleapis.com	不適用	以半形逗號分隔的字串	否
QueryDialect	指定要使用的查詢方言。使用 SQL 代表 GoogleSQL (強烈建議)，使用 BIG_QUERY 代表舊版 SQL。	SQL	字串	否
QueryProperties	設定可修改查詢行為的屬性。	不適用	Map<String, String>	否
UniverseDomain	指定貴機構的 Universe 網域。	googleapis.com	字串	否
UseQueryCache	可讓您在 BigQuery 中啟用查詢快取功能。	true	布林值	否

使用驅動程式執行查詢

本節提供資料類型對應資訊，以及使用 ODBC 驅動程式執行查詢的範例。

資料類型對應

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

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

範例

下列範例說明如何搭配使用 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 分析費用。