Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用适用于 BigQuery 的 ODBC 驱动程序

适用于 BigQuery 的开放数据库连接 (ODBC) 驱动程序可将您的应用连接到 BigQuery。这样，您就可以将 BigQuery 功能与首选工具和基础架构结合使用。

准备工作

确保您熟悉 Open Database Connectivity (ODBC) 驱动程序和驱动程序管理器。

请注意以下系统要求：

操作系统	支持的架构	最低版本和依赖项
Windows	32 位 (x86)、64 位 (x64)	版本：Windows 10、Windows Server 2016 或更高版本依赖项：Microsoft Visual C++ Redistributable for Visual Studio 2019 或 2022
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`。

确定适用于 BigQuery 的 ODBC 驱动程序的连接类型。该驱动程序支持以下身份验证方法：

身份验证方法	身份验证信息	示例	连接媒体资源（稍后设置）
标准服务账号	服务账号密钥（JSON 对象）	`my-sa-key`	`KeyFilePath`
Workload Identity 联合或员工身份联合	外部账号配置文件中的受众群体属性	`//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 中创建数据源名称，请执行以下操作：

在开始菜单中，前往 ODBC 数据源，然后选择与客户端应用具有相同位数的版本，以确保正确连接到 BigQuery。
在“ODBC 数据源管理员”中，点击驱动程序标签页。
在已安装的 ODBC 驱动程序的字母顺序列表中，找到 ODBC Driver for BigQuery。
根据需要，执行以下操作之一：
- 如需为当前用户创建 DSN，请点击用户 DSN 标签页。
- 如需为所有用户创建 DSN，请点击系统 DSN 标签页。建议使用系统 DSN，因为某些应用会使用不同的用户账号加载数据，可能无法检测到在其他用户账号下创建的用户 DSN。
点击 Add（添加）。
在创建新数据源对话框中，选择 ODBC Driver for BigQuery，然后点击完成。
系统会打开 ODBC Driver for BigQuery DSN 设置对话框。
在数据源名称字段中，输入 DSN 的名称。
如需了解要填充哪些值，请参阅连接属性部分。

非 Windows

64 位 Linux 发行版同时支持 32 位和 64 位应用。确保 ODBC 驱动程序的架构与您打算使用的应用相匹配。例如，针对 64 位应用使用 64 位驱动程序，针对 32 位应用使用 32 位驱动程序。您可以在单个系统上同时安装这两种驱动程序架构。

下载适用于 Linux 的 ODBCDriverforBigQuery_linux_latest.zip
下载适用于 macOS 的 ODBCDriverforBigQuery_macos_latest.tar.gz

如需使用 tar 或 zip 文件包安装连接器，请执行以下操作：

创建要安装连接器的目录（如果该目录尚不存在）。
将主 ZIP 文件解压到方便访问的临时位置。
前往提取的 tar 或 zip 文件的文件夹，然后（可选）将所有文件和文件夹复制到安装目录。
提取后，适用于 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 驱动程序是否应处理大于 128MB 的查询结果。	`0`	布尔值	否
`BYOID_AudienceUrl`	受众群体包含工作负载身份池或员工池的资源名称，以及相应池中的提供方标识符。	不适用	字符串	仅当 `OAuthMechanism=4` 时
`BYOID_CredentialSource`	设置检索令牌本身所需的信息，以及一些环境信息。	不适用	字符串	仅当 `OAuthMechanism=4` 时
`BYOID_PoolUserProject`	如果这是员工池而不是 Workload Identity 池，请设置此属性。	不适用	字符串	仅当 `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`	长	否
`Location`	用于指定驱动程序创建或查询数据集的位置。	不适用	字符串	否
`LogLevel`	限制驱动程序在互动期间记录的详细信息。选择以下任一选项： `0`：`OFF` `1`：`ERROR` `2`：`WARNING` `3`：`INFO`	`0`	整数	否
`LogPath`	用于指定驱动程序写入日志文件的目录。	不适用	字符串	否
`LogFileCount`	可让您设置要保留的日志文件数量上限。	`0`	整数	否
`LogFileSize`	可让您设置每个日志文件的大小上限（以字节为单位）。	`0`	长	否
`MaxResults`	用于指定 BigQuery API 结果中每页的结果数。	`10000`	长	否
`MaxThreads`	定义连接器可在线程池中用于并发处理的线程数量上限。如需将此属性配置为非 Windows（Linux/macOS）连接器的连接器级设置，请在 `googlebigqueryodbc.ini` 文件中指定此属性。	`8`	整数	否
`OAuthMechanism`	身份验证类型。选择以下任一选项： `0`：服务账号身份验证 `3`：应用默认凭据身份验证 `4`：工作负载或员工身份联合身份验证	不适用	整数	是
`ProjectId`	驱动程序的默认项目 ID。驱动程序使用此项目执行查询，并根据资源使用情况向此项目收取费用。	不适用	字符串	是
`ProxyHost`	代理服务器的主机名或 IP 地址。	不适用	字符串	否
`ProxyPort`	代理服务器正在监听的端口号。	不适用	字符串	否
`ProxyPwd`	通过代理服务器连接时用于身份验证的密码。	不适用	字符串	否
`ProxyUid`	通过代理服务器连接时用于身份验证的用户名。	不适用	字符串	否
`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`	指定组织的全球网域。	`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 分析价格付费。