Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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

借助 BigQuery 的 Open Database Connectivity (ODBC) 驱动程序，您可以将非 Java 应用连接到 BigQuery，从而将 BigQuery 功能与首选工具和基础架构结合使用。如需将 Java 应用连接到 BigQuery，请使用 JDBC 驱动程序（适用于 BigQuery）。

适用于 BigQuery 的 ODBC 驱动程序根据 Apache 2.0 许可获得授权。

准备工作

确保您熟悉 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 进行身份验证，并记下以下信息，以便稍后在建立与 BigQuery 的 ODBC 驱动程序的连接时使用。您只需记下与您使用的身份验证方法对应的信息。

身份验证方法	身份验证信息	示例	连接属性（稍后设置）
标准服务账号	服务账号密钥（JSON 对象）	`my-sa-key.json`	`KeyFilePath`
服务账号模拟	目标服务账号电子邮件地址	`service-account@project.`	`ServiceAccountImpersonationEmail, KeyFilePath`
工作负载身份联合或员工身份联合	外部账号配置文件中的受众群体属性	`//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

安装与应用架构对应的驱动程序：
- 下载 32 位应用的 ODBCDriverforBigQuery_windows_x86.msi 文件。
- 下载 64 位应用的 ODBCDriverforBigQuery_windows_x64.msi 文件。
通过执行以下操作来创建数据源名称 (DSN)：
1. 在 Windows 开始菜单中，前往 ODBC 数据源，然后选择与客户端应用具有相同位数的版本。
2. 在 ODBC 数据源管理员页面上，点击驱动程序标签页。
3. 在已安装的 ODBC 驱动程序列表中，找到 ODBC Driver for BigQuery。
4. 选择系统 DSN 标签页可为所有用户创建 DSN，选择用户 DSN 标签页可为当前用户创建 DSN。一般建议使用系统 DSN，因为某些应用会使用不同的用户账号加载数据，可能无法检测到其他用户 DSN。
5. 点击 Add（添加）。
6. 在创建新数据源对话框中，选择 ODBC Driver for BigQuery，然后点击完成。系统会打开 ODBC Driver for BigQuery DSN Setup 对话框。
7. 在数据源名称字段中，为 DSN 输入名称。
8. 添加连接属性。如需查看属性的完整列表，请参阅连接属性。

非 Windows 设备

安装与您的操作系统对应的驱动程序：
- 下载适用于 Linux 的 ODBCDriverforBigQuery_linux_latest.zip 文件。
- 下载适用于 macOS 的 ODBCDriverforBigQuery_macos_latest.tar.gz 文件。
提取下载的 ZIP 或 TAR 文件的内容。
将 ZIP 或 TAR 文件的内容移到您要安装驱动程序的目录中。BigQuery 的 ODBC 驱动程序共享对象路径为 INSTALL_DIR/lib/libgoogle_cloud_odbc_bq_driver.so，其中 INSTALL_DIR 是您的安装目录。

更新 .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

建立连接

如需使用适用于 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：用于工作负载身份联合或员工身份联合身份验证
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 驱动程序支持以下连接属性。

连接属性	说明	默认值	数据类型	必需
`AdditionalProjects`	驱动程序可访问以用于查询和元数据操作的项目，此外还包括通过 `Catalog` 属性设置的主项目。	不适用	以逗号分隔的字符串	否
`AllowHtapiForLargeResults`	确定驱动程序是否可以使用 BigQuery Storage Read API。	`0`	布尔值	否
`AllowLargeResults`	确定当 `SQLDialect` 属性设置为 `0`（旧版 SQL）时，驱动程序是否处理大于 128 MB 的查询结果。如果 `SQLDialect` 属性设置为 `1` (GoogleSQL)，驱动程序始终会处理大型查询结果。	`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`	字符串	否
`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`：工作负载身份联合或员工身份联合身份验证	不适用	整数	是
`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`	代理服务器的主机名或 IP 地址。	不适用	字符串	否
`ProxyPort`	代理服务器正在监听的端口号。	不适用	字符串	否
`ProxyPwd`	通过代理服务器连接时用于身份验证的密码。	不适用	字符串	否
`ProxyUid`	通过代理服务器连接时用于身份验证的用户名。	不适用	字符串	否
`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 设备

创建或修改配置文件（例如 googlebigqueryodbc.ini），并在 [Driver] 部分下添加驱动程序选项。示例如下：
```
[Driver]
LogLevel=3
LogPath=/path/to/log/directory
LogFileCount=200
LogFileSize=1000
MaxThreads=8
WcharEncoding=UTF-16LE
```
将 GOOGLEBIGQUERYODBCINI 环境变量设置为此文件的路径：
```
export GOOGLEBIGQUERYODBCINI=/path/to/googlebigqueryodbc.ini
```

驱动程序日志记录级别

该驱动程序支持 0 到 3 的日志记录级别。建议先从 LogLevel=3 (INFO) 开始进行问题排查。

ODBC 日志记录级别	说明
0（关闭）	停用所有日志记录。
1（错误）	记录错误事件。
2（警告）	记录警告事件。
3（信息）	记录描述骑手进度的常规信息。

驱动程序级配置属性（非 Windows）

以下属性可在 googlebigqueryodbc.ini 的 [Driver] 部分下进行配置：

属性	说明	允许使用的值	默认值
`WcharEncoding`	在驱动程序和 ODBC 驱动程序管理器（例如 `WcharEncoding=UTF-16LE`）之间传递宽字符字符串时，显式控制 `SQLWCHAR` 字符缓冲区的有线编码。这可解决 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 开发者工具。