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

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

限制

适用于 BigQuery 的 JDBC 驱动程序存在以下限制：

• 该驱动程序专为 BigQuery 而设计，无法与其他产品或服务搭配使用。
• BigQuery Storage Read API 不支持 INTERVAL 数据类型。
• 需遵守所有数据操纵语言 (DML) 限制。

准备工作

1. 确保您熟悉 JDBC 驱动程序、Apache Maven 和 java.sql 软件包。
2. 验证您的系统是否已配置 Java 运行时环境 (JRE) 8.0 或更高版本。如需了解如何查看 JRE 版本，请参阅验证 JRE 环境。

3. 向 BigQuery 进行身份验证，并记下以下信息，以便稍后在建立与 BigQuery 的 JDBC 驱动程序的连接时使用。您只需记下与您使用的身份验证方法对应的信息。

   身份验证方法	身份验证信息	示例	连接媒体资源（稍后设置）
   标准服务账号	服务账号电子邮件地址	bq-jdbc-sa@mytestproject.	OAuthServiceAcctEmail
   	服务账号密钥（JSON 对象）	my-sa-key	OAuthPvtKey
   服务账号密钥文件	服务账号密钥文件（完整路径）	path/to/file/secret.json	OAuthPvtKeyPath
   Google 用户账号	客户端 ID	123-abc.apps.googleusercontent.com	OAuthClientId
   	客户端密钥	_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV	OAuthClientSecret
   预生成的访问令牌	访问令牌	ya29.a0AfH6SMCiH1L-x_yZ	OAuthAccessToken
   预生成的刷新令牌	刷新令牌	1/fFAGRNJru1FTz70BzhT3Zg	OAuthRefreshToken
   	客户端 ID	123-abc.apps.googleusercontent.com	OAuthClientId
   	客户端密钥	_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV	OAuthClientSecret
   应用默认凭证	无	不适用	不适用
   配置文件	配置文件（JSON 对象或完整路径）	path/to/file/secret.json	OAuthPvtKey
   外部账号配置对象	账号配置对象	external_account_configuration_object	OAuthPvtKey
   其他	外部账号配置文件中的受众群体属性	//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider	BYOID_AudienceUri
   	令牌检索和环境信息文件	{\"file\":\"/path/to/file\"}	BYOID_CredentialSource
   	用户项目（仅在使用员工池时）	my_project	BYOID_PoolUserProject
   	服务账号模拟的 URI（仅当使用工作团队池时）	my-sa	BYOID_SA_Impersonation_Uri
   	基于令牌交换规范的 Security Token Service 令牌	urn:ietf:params:oauth:tokentype:id_token	BYOID_SubjectTokenType
   	Security Token Service 令牌交换端点	https://sts.googleapis.com/v1/token	BYOID_TokenUri

安装和配置 JDBC 驱动程序

您可以直接下载 uber-JAR 文件或使用 Maven 来安装和配置适用于 BigQuery 的 JDBC 驱动程序。

直接下载配置

如需通过直接下载来配置 JDBC 驱动程序，请执行以下操作：

1. 下载版本 1.4.0 的驱动程序。
2. 将下载的文件复制到软件指定的位置。

如需了解功能变更和工作流更新，请参阅变更记录。

适用于 BigQuery 的先前 JDBC 驱动程序版本

• 1.3.0
• 1.2.0
• 1.1.0
• 1.0.0

Maven 配置

适用于 BigQuery 的 JDBC 驱动程序可在 Maven Central 上获取。

如需使用 JDBC 驱动程序配置开发环境，请将该驱动程序作为依赖项添加到您的项目：

Maven

将以下依赖项添加到您的 pom.xml 文件中：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.4.0</version>
</dependency>

使用超级 JAR 的 Maven

将以下依赖项添加到您的 pom.xml 文件中：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>1.4.0</version>
    <classifier>all</classifier>
    <exclusions>
      <exclusion>
        <groupId>*</groupId>
        <artifactId>*</artifactId>
      </exclusion>
    </exclusions>
</dependency>

Gradle

请将以下内容添加到 build.gradle 文件：

dependencies {
// ... other dependencies
implementation("com.google.cloud:google-cloud-bigquery-jdbc:1.4.0")
}

建立连接

如需使用适用于 BigQuery 的 JDBC 驱动程序在 Java 应用与 BigQuery 之间建立连接，请执行以下操作：

1. 确定适用于 BigQuery 的 JDBC 驱动程序的连接字符串。此字符串包含在 Java 应用与 BigQuery 之间建立连接所需的所有信息。连接字符串采用以下格式：

   jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;AUTH_PROPS;OTHER_PROPS

   替换以下内容：

   • HOST：服务器的 DNS 或 IP 地址。
   • PORT：TCP 端口号。
   • PROJECT_ID：BigQuery 项目的 ID。
   • AUTH_TYPE：一个数字，用于指定您使用的身份验证类型。以下项之一：
     • 0：用于服务账号身份验证（标准和密钥文件）
     • 1：用于 Google 用户账号身份验证
     • 2：用于预生成的刷新令牌或访问令牌身份验证
     • 3：用于应用默认凭据身份验证
     • 4：适用于其他身份验证方法
   • AUTH_PROPS：您在向 BigQuery 进行身份验证时记下的身份验证信息，以 property_1=value_1; property_2=value_2;... 格式列出，例如 OAuthPvtKeyPath=path/to/file/secret.json（如果您使用服务账号密钥文件进行身份验证）。
   • OTHER_PROPS（可选）：JDBC 驱动程序的其他连接属性，以 property_1=value_1; property_2=value_2;... 格式列出。如需查看连接属性的完整列表，请参阅连接属性。

2. 使用 DriverManager 或 DataSource 类将 Java 应用连接到 BigQuery 的 JDBC 驱动程序。

   • 使用 DriverManager 类进行连接：

     import java.sql.Connection;
     import java.sql.DriverManager;
     
     private static Connection getJdbcConnectionDM(){
       Connection connection = DriverManager.getConnection(CONNECTION_STRING);
       return connection;
     }

     将 CONNECTION_STRING 替换为上一步中的连接字符串。

   • 使用 DataSource 类进行连接：

     import com.google.cloud.bigquery.jdbc.DataSource;
     import java.sql.Connection;
     import java.sql.SQLException;
     
     private static public Connection getJdbcConnectionDS() throws SQLException {
       Connection connection = null;
       DataSource dataSource = new com.google.cloud.bigquery.jdbc.DataSource();
       dataSource.setURL(CONNECTION_STRING);
       connection = dataSource.getConnection();
       return connection;
     }

     将 CONNECTION_STRING 替换为上一步中的连接字符串。

     DataSource 类还具有 setter 方法，您可以使用这些方法来设置连接属性，而不是将它们包含在连接字符串中。下面给出了一个示例：

     private static Connection getConnection() throws SQLException {
       DataSource ds = new DataSource();
       ds.setURL(jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;);
       ds.setAuthType(3);  // Application Default Credentials
       ds.setProjectId("MyTestProject");
       ds.setEnableHighThroughputAPI(true);
       ds.setLogLevel("6");
       ds.setUseQueryCache(false);
       return ds.getConnection();
     }

连接属性

JDBC 驱动程序连接属性是指在建立与数据库的连接时包含在连接字符串中或通过 setter 方法传递的配置参数。BigQuery 的 JDBC 驱动程序支持以下连接属性。

注意： 所有连接属性名称都不区分大小写。布尔值连接属性接受 TRUE/FALSE 和 1/0。

连接媒体资源	说明	默认值	数据类型	必需
AdditionalProjects	驱动程序可访问以用于查询和元数据操作的项目，此外还包括由 ProjectId 属性设置的主项目。	不适用	以逗号分隔的字符串	否
AllowLargeResults	确定当 QueryDialect 属性设置为 BIG_QUERY 时，驱动程序是否处理大于 128 MB 的查询结果。如果 QueryDialect 属性设置为 SQL，驱动程序始终会处理大型查询结果。	TRUE	布尔值	否
BYOID_AudienceUri	外部账号配置文件中的 audience 属性。受众群体属性可以包含工作负载身份池或员工池的资源名称，以及相应池中的提供方标识符。	不适用	字符串	仅当 OAuthType=4 时
BYOID_CredentialSource	令牌检索和环境信息。	不适用	字符串	仅当 OAuthType=4 时
BYOID_PoolUserProject	使用员工池进行身份验证时的用户项目。	不适用	字符串	仅当 OAuthType=4 且使用员工池时
BYOID_SA_Impersonation_Uri	使用工作区池进行身份验证时，服务账号模拟的 URI。	不适用	字符串	仅当 OAuthType=4 且使用员工池时
BYOID_SubjectTokenType	基于令牌交换规范的 Security Token Service 令牌。 以下值之一： 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	urn:ietf:params:oauth:tokentype:id_token	字符串	仅当 OAuthType=4 时
BYOID_TokenUri	Security Token Service 令牌交换端点。	https://sts.googleapis.com/v1/token	字符串	否
ConnectionPoolSize	连接池大小（如果已启用连接池）。	10	Long	否
DefaultDataset	未在查询中指定数据集时所使用的数据集。	不适用	字符串	否
EnableGcpLogExporter	确定驱动程序是否自动将日志导出到 Cloud Logging（如果未使用自定义或全局 OpenTelemetry 实例）。如需了解详情，请参阅 OpenTelemetry。	FALSE	布尔值	否
EnableGcpTraceExporter	确定驱动程序是否自动将轨迹导出到 Cloud Trace（如果未使用任何自定义或全局 OpenTelemetry 实例）。如需了解详情，请参阅 OpenTelemetry。	FALSE	布尔值	否
EnableHighThroughputAPI	确定是否可以使用 Storage Read API。HighThroughputActivationRatio 和 HighThroughputMinTableSize 属性也必须设置为 TRUE，才能使用 Storage Read API。	FALSE	布尔值	否
EnableProjectDiscovery	确定数据库元数据方法是否在所有可访问的 Google Cloud 项目中发现数据集。如果设置为 FALSE，则发现范围仅限于默认的 ProjectId。	FALSE	布尔值	否
EnableSession	确定连接是否启动会话。如果设置为 TRUE，则会将会话 ID 传递给所有后续查询。	FALSE	布尔值	否
EnableTimestampPicos	确定驱动程序是否以皮秒精度检索 TIMESTAMP(12) 值。如果设置为 TRUE，TIMESTAMP(12) 值会通过 getString() 和 getObject() 方法以 UTC 格式的 String 对象返回。如果设置为 FALSE，则 TIMESTAMP(12) 值会截断为 6 位微秒精度。此属性与旧版 SQL (QueryDialect=BIG_QUERY) 不兼容。	FALSE	布尔值	否
EnableWriteAPI	确定是否可以使用 Storage Write API (gRPC)。必须设置为 TRUE 才能启用批量插入。	FALSE	布尔值	否
EndpointOverrides	用于覆盖以下内容的自定义端点： BIGQUERY=https://bigquery.googleapis.com READ_API=https://bigquerystorage.googleapis.com OAUTH2=https://oauth2.googleapis.com STS=https://sts.googleapis.com	不适用	以逗号分隔的字符串	否
FilterTablesOnDefaultDataset	确定 DatabaseMetaData.getTables() 和 DatabaseMetaData.getColumns() 方法返回的元数据的范围。如果设置为 FALSE，则不会进行过滤。还必须设置 DefaultDataset 属性才能启用过滤功能。	FALSE	布尔值	否
GcpTelemetryCredentials	用于对遥测导出器进行身份验证的凭据。接受服务账号 JSON 密钥的路径或原始 JSON 字符串。如果未设置，则默认为连接凭据。如需了解详情，请参阅 OpenTelemetry。	不适用	字符串	否
GcpTelemetryProjectId	遥测数据的目标 Google Cloud 项目 ID。默认值为主要 ProjectId。如需了解详情，请参阅 OpenTelemetry。	不适用	字符串	否
HighThroughputActivationRatio	查询响应中的页数阈值。如果超过此数量，并且满足 EnableHighThroughputAPI 和 HighThroughputMinTableSize 条件，驱动程序将开始使用 Storage Read API。	2	整数	否
HighThroughputMinTableSize	查询响应中的行数阈值。如果超过此数量，并且满足 EnableHighThroughputAPI 和 HighThroughputActivationRatio 条件，驱动程序将开始使用 Storage Read API。	10000	整数	否
JobCreationMode	确定查询是否通过作业运行。值为 1 表示系统会为每个查询创建作业，值为 2 表示可以在没有作业的情况下执行查询。	2	整数	否
JobTimeout	作业超时时间（以秒为单位），超过此时间后，服务器会取消作业。	0	Long	否
KMSKeyName	用于加密数据的 KMS 密钥名称。	不适用	字符串	否
Labels	与查询相关联的标签，用于整理和分组查询作业。	不适用	Map<String, String>	否
LargeResultDataset	大型查询结果的目标数据集，仅当设置了 LargeResultTable 属性时才有效。设置此属性后，数据写入会绕过结果缓存，并针对每个查询触发结算，即使结果很小也是如此。	_google_jdbc	字符串	否
LargeResultsDatasetExpirationTime	大型结果数据集中的所有表的生命周期（以毫秒为单位）。 如果数据集已设置默认到期时间，则系统会忽略此属性。	3600000	Long	否
LargeResultTable	大型查询结果的目标表，仅当设置了 LargeResultDataset 属性时才有效。设置此属性后，数据写入会绕过结果缓存，并针对每个查询触发结算，即使结果很小也是如此。	temp_table...	字符串	否
ListenerPoolSize	监听器池大小（如果已启用连接池）。	10	Long	否
Location	创建或查询数据集的位置。如果未设置此属性，BigQuery 会自动确定位置。	不适用	字符串	否
LogLevel	驱动程序记录的详细程度。如需了解详情，请参阅 Logging。	0	整数	否
LogPath	写入日志文件的目录。	不适用	字符串	否
MaximumBytesBilled	结算的字节数上限。如果查询的收费字节数超出此值，则查询会失败，但不会产生费用。	0	Long	否
MaxResults	每页的结果数上限。	10000	Long	否
MetaDataFetchThreadCount	用于数据库元数据方法的线程数。	32	整数	否
OAuthAccessToken	用于预生成的访问令牌身份验证的访问令牌。	不适用	字符串	仅当 OAUTH_TYPE=2 时
OAuthClientId	用于预生成的刷新令牌身份验证和用户账号身份验证的客户端 ID。	不适用	字符串	仅当 OAUTH_TYPE=1 或 OAUTH_TYPE=2 时
OAuthClientSecret	用于预生成的刷新令牌身份验证和用户账号身份验证的客户端密钥。	不适用	字符串	仅当 OAUTH_TYPE=1 或 OAUTH_TYPE=2 时
OAuthP12Password	PKCS12 密钥文件的密码。	notasecret	字符串	否
OAuthPvtKey	使用服务账号身份验证时的服务账号密钥。此值可以是原始 JSON 密钥文件对象，也可以是 JSON 密钥文件的路径。	不适用	字符串	仅当 OAUTH_TYPE=0 和 OAuthPvtKeyPath 值未设置时
OAuthPvtKeyPath	使用服务账号身份验证时，服务账号密钥的路径。	不适用	字符串	仅当未设置 OAUTH_TYPE=0 以及 OAuthPvtKey 和 OAuthServiceAcctEmail 值时
OAuthRefreshToken	预生成的刷新令牌身份验证的刷新令牌。	不适用	字符串	仅当 OAUTH_TYPE=2
OAuthServiceAcctEmail	使用服务账号身份验证时的服务账号电子邮件地址。	不适用	字符串	仅当 OAUTH_TYPE=0 和 OAuthPvtKeyPath 值未设置时
OAuthType	身份验证类型。以下值之一： 0：服务账号身份验证 1：用户账号身份验证 2：预生成的刷新令牌或访问令牌身份验证 3：应用默认凭据身份验证 4：其他身份验证方法	-1	整数	是
PartnerToken	供 Google Cloud 合作伙伴用于跟踪驱动程序使用情况的令牌。	不适用	字符串	否
ProjectId	驱动程序的默认项目 ID。此项目用于执行查询，并按资源使用情况付费。如果未设置，驱动程序会推断项目 ID。	不适用	字符串	否，但强烈建议使用
ProxyHost	用于路由 JDBC 连接的代理服务器的主机名或 IP 地址。	不适用	字符串	否
ProxyPort	代理服务器监听连接的端口号。	不适用	字符串	否
ProxyPwd	通过需要进行身份验证的代理服务器连接时，用于身份验证的密码。	不适用	字符串	否
ProxyUid	通过需要进行身份验证的代理服务器连接时，用于身份验证的用户名。	不适用	字符串	否
QueryDialect	用于执行查询的 SQL 方言。使用 SQL 表示 GoogleSQL（强烈推荐），使用 BIG_QUERY 表示旧版 SQL。	SQL	字符串	否
QueryProperties	用于自定义查询行为的 REST 连接属性。	不适用	Map<String, String>	否
RequestGoogleDriveScope	如果设置为 1，则向连接添加只读云端硬盘范围。	0	整数	否
RetryInitialDelay	设置首次重试前的延迟时间（以秒为单位）。	0	Long	否
RetryMaxDelay	设置重试延迟时间的最大限值（以秒为单位）。	0	Long	否
ServiceAccountImpersonationChain	模拟链中的服务账号电子邮件地址的英文逗号分隔列表。	不适用	字符串	否
ServiceAccountImpersonationEmail	要模拟的服务账号电子邮件地址。	不适用	字符串	否
ServiceAccountImpersonationScopes	要与模拟账号搭配使用的 OAuth2 范围的英文逗号分隔列表。	https://www.googleapis.com/auth/bigquery	字符串	否
ServiceAccountImpersonationTokenLifetime	模拟账号令牌的生命周期（以秒为单位）。	3600	整数	否
SSLTrustStore	包含受信任证书授权机构 (CA) 证书的 Java TrustStore 的完整路径。驱动程序会利用此信任库在 SSL/TLS 握手期间验证服务器的身份。	不适用	字符串	否
SSLTrustStoreProvider	用于 SSLTrustStore 属性的 Java 加密扩展 (JCE) 提供程序。	不适用	字符串	否
SSLTrustStorePwd	SSLTrustStore 属性中指定的 Java TrustStore 的密码。	不适用	字符串	仅当 Java TrustStore 受密码保护时
SSLTrustStoreType	SSLTrustStore 属性中指定的信任库文件的格式（例如 JKS、PKCS12 或 ROTKS）。	不适用	字符串	否
SWA_ActivationRowCount	阈值为 executeBatch insert 行，当超过此阈值时，连接器会切换到 Storage Write API (gRPC)。	3	整数	否
SWA_AppendRowCount	写入数据流的大小。	1000	整数	否
Timeout	连接器在超时之前重试失败的 API 调用的时长（以秒为单位）。	0	Long	否
UniverseDomain	与贵组织的 Google Cloud 资源关联的顶级网域。	googleapis.com	字符串	否
UnsupportedHTAPIFallback	确定连接器是回退到 REST API（设置为 TRUE 时）还是返回错误（设置为 FALSE 时）。	TRUE	布尔值	否
UseGlobalOpenTelemetry	确定驱动程序是否使用 GlobalOpenTelemetry.get() 进行插桩。如需了解详情，请参阅 OpenTelemetry。	FALSE	布尔值	否
UseQueryCache	启用查询缓存。	TRUE	布尔值	否

使用驱动程序运行查询

通过 JDBC 驱动程序将 Java 应用连接到 BigQuery 后，您现在可以通过标准 JDBC 流程在开发环境中运行查询。您必须遵循所有 BigQuery 配额和限制。

数据类型映射

通过适用于 BigQuery 的 JDBC 驱动程序运行查询时，会发生以下数据类型映射：

GoogleSQL 类型	Java 类型
ARRAY	Array
BIGNUMERIC	BigDecimal
BOOL	Boolean
BYTES	byte[]
DATE	Date
DATETIME	String
FLOAT64	Double
GEOGRAPHY	String
INT64	Long
INTERVAL	String
JSON	String
NUMERIC	BigDecimal
STRING	String
STRUCT	Struct
TIME	Time
TIMESTAMP	Timestamp

示例

以下部分提供了通过适用于 BigQuery 的 JDBC 驱动程序使用 BigQuery 功能的示例。

定位参数

以下示例运行了一个包含位置参数的查询：

PreparedStatement preparedStatement = connection.prepareStatement(
    "SELECT * FROM MyTestTable where testColumn = ?");
preparedStatement.setString(1, "string2");
ResultSet resultSet = statement.executeQuery(selectQuery);

嵌套和重复记录

以下示例查询了 Struct 数据的基本记录：

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct obj = (Struct) resultSet.getObject(1);
    System.out.println(obj.toString());

驱动程序会将基本记录作为结构对象或 JSON 对象的字符串表示形式返回。结果类似于以下内容：

{
  "v": {
    "f": [
      {
        "v": "Adam"
      },
      {
        "v": "5"
      }
    ]
  }
}

以下示例查询 Struct 对象的子组件：

ResultSet resultSet = statement.executeQuery("SELECT STRUCT(\"Adam\" as name, 5 as age)");
    resultSet.next();
    Struct structObject = (Struct) resultSet.getObject(1);
    Object[] structComponents = structObject.getAttributes();
    for (Object component : structComponents){
      System.out.println(component.toString());
    }

以下示例查询了重复数据的标准数组，然后验证了结果：

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT [1,2,3]");
resultSet.next();
Object[] arrayObject = (Object[]) resultSet.getArray(1).getArray();

// Verify Result
int count =0;
for (; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

以下示例查询了重复数据的 Struct 数组，然后验证了结果：

// Execute Query
ResultSet resultSet = statement.executeQuery("SELECT "
    + "[STRUCT(\"Adam\" as name, 12 as age), "
    + "STRUCT(\"Lily\" as name, 17 as age)]");

Struct[] arrayObject = (Struct[]) resultSet.getArray(1).getArray();

// Verify Result
for (int count =0; count < arrayObject.length; count++) {
  System.out.println(arrayObject[count]);
}

批量插入

以下示例使用 executeBatch 方法执行批量插入操作。

Connection conn = DriverManager.getConnection(connectionUrl);
PreparedStatement statement = null;
Statement st = conn.createStatement();
final String insertQuery = String.format(
        "INSERT INTO `%s.%s.%s` "
      + " (StringField, IntegerField, BooleanField) VALUES(?, ?, ?);",
        DEFAULT_CATALOG, DATASET, TABLE_NAME);

statement = conn.prepareStatement(insertQuery1);

for (int i=0; i<2000; ++i) {
      statement.setString(1, i+"StringField");
      statement.setInt(2, i);
      statement.setBoolean(3, true);
      statement.addBatch();
}

statement.executeBatch();

日志记录

如需排查 BigQuery JDBC 驱动程序的问题，您可以通过设置连接属性或环境变量来启用日志记录。日志记录可能会影响性能并占用磁盘空间，因此请仅在需要捕获问题时临时启用。

日志级别

LogLevel 属性用于确定 java.util.logging 软件包记录的详细程度：

• 0：OFF（默认）
• 1：SEVERE
• 2：WARNING
• 3：INFO
• 4：CONFIG
• 5：FINE
• 6：FINER
• 7：FINEST
• 8：ALL

我们建议将日志记录级别设为 6，以便进行常规问题排查。级别 7 和 8 仅限 ResultSet 操作，并会生成大量日志。

在连接字符串中启用日志记录

如需在连接字符串中启用日志记录，请添加 LogLevel 和 LogPath 连接属性，例如：

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=MyTestProject;OAuthType=3;LogLevel=6;LogPath=/tmp/jdbc-logs;

使用环境变量启用日志记录

如果您的开发工具不允许修改连接字符串，您还可以在运行应用之前使用以下环境变量设置日志级别和日志路径：

• BIGQUERY_JDBC_LOG_LEVEL：日志级别 (0-8)。
• BIGQUERY_JDBC_LOG_PATH：日志文件的目录。

例如，在 Linux 或 macOS 环境中，运行以下命令：

export BIGQUERY_JDBC_LOG_LEVEL=6
export BIGQUERY_JDBC_LOG_PATH=/tmp/jdbc-logs

OpenTelemetry

BigQuery 的 JDBC 驱动程序支持 OpenTelemetry (OTel)，可提供分布式跟踪和日志记录，让您能够监控数据库互动的性能并有效排查问题。

已跟踪的操作

启用 OpenTelemetry 后，驱动程序会为以下操作生成 span：

• 查询执行：为 BigQueryStatement（execute()、executeQuery()、executeLargeUpdate()、executeBatch()）和 BigQueryPreparedStatement（execute()、executeQuery()、executeLargeUpdate()）生成 span。
• 元数据操作：为特定 DatabaseMetaData 方法（getCatalogs()、getSchemas()、getTables()、getColumns()）生成 span。
• 分页：使用 OpenTelemetry Span Links 跟踪并以因果关系将异步提取的其他结果页与原始查询执行 span 相关联（使用 REST API 路径时）。系统会为这些操作创建一个名为 BigQueryStatement.pagination 的 span。
• 上下文传播：JDBC 驱动程序将有效上下文传播到基础 google-cloud-bigquery SDK。因此，由 SDK 生成的 span（例如 HTTP RPC 调用）会自动显示为 JDBC span 的子 span，从而提供完整的端到端跟踪层次结构。

配置模式

您可以根据应用的架构和要求，使用以下任一模式在 JDBC 驱动程序中配置 OpenTelemetry。

应用管理的遥测

如果您的应用已使用 OpenTelemetry，您可以将 OpenTelemetry 实例注入到 JDBC 驱动程序中，以确保驱动程序的遥测数据与应用的遥测数据相关联。

为此，请使用 BigQueryDataSource API：

BigQueryDataSource dataSource = new BigQueryDataSource();
// ... set other properties ...
dataSource.setCustomOpenTelemetry(yourOpenTelemetryInstance);

全球 OpenTelemetry 支持

如果您已在应用中全局初始化 OpenTelemetry（例如，使用 OpenTelemetry Java 代理或通过调用 GlobalOpenTelemetry.set() 函数），则可以配置驱动程序以使用此全局实例。

如需启用全局实例，请将 UseGlobalOpenTelemetry 连接属性设置为 TRUE。

零配置 Google Cloud 遥测

如果您在 Google Cloud 上运行，并且希望快速完成设置，则可以启用将轨迹和日志自动导出到 Google Cloud 可观测性（Trace 和 Logging）的功能。

如需启用此导出功能，请在 JDBC 网址中设置以下连接属性：

• EnableGcpTraceExporter=true
• EnableGcpLogExporter=true

以下是连接网址示例：

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=your-project-id;EnableGcpTraceExporter=true;EnableGcpLogExporter=true;

OpenTelemetry 连接属性

OpenTelemetry 支持以下连接属性。如需详细了解这些属性的说明和默认值，请参阅连接属性。

• EnableGcpLogExporter
• EnableGcpTraceExporter
• GcpTelemetryCredentials
• GcpTelemetryProjectId
• UseGlobalOpenTelemetry

重要注意事项

部署 OpenTelemetry 集成时，请注意以下有关日志记录行为、身份验证、代理配置和价格的注意事项。

与 LogLevel 的互动

现有的 LogLevel 连接属性充当日志记录的主要门槛。

• 如果设置为 LogLevel=0（关闭），则不会生成任何日志记录。因此，即使设置了 EnableGcpLogExporter=true，也不会使用 OpenTelemetry 或将日志导出到 Cloud Logging。
• 如需启用 OTel 日志记录，请确保 LogLevel 设置为大于 0 的值（例如，5 表示详细日志）。

遥测的身份验证

通过自动Google Cloud 回退进行的遥测数据导出（包括跟踪和日志记录）支持使用 GcpTelemetryCredentials 提供的应用默认凭据 (ADC) 和显式服务账号凭据。

如果提供了 GcpTelemetryProjectId 或 GcpTelemetryCredentials，则日志和轨迹都会使用相同的配置凭据发送到同一指定的目标项目。

使用 OpenTelemetry 和日志记录的代理配置

如果您的应用通过代理服务器连接到 BigQuery，驱动程序会按如下方式处理代理路由：

• 轨迹导出 (HTTP)。当您使用默认 HTTP 协议进行 OpenTelemetry 轨迹导出 (otel.exporter.otlp.protocol=http/protobuf) 时，驱动程序会自动通过使用 ProxyHost 和 ProxyPort 在连接属性中配置的代理来路由轨迹导出流量。

• 日志导出和 gRPC 遥测。自动 Google Cloud 日志导出器 (EnableGcpLogExporter=true) 和基于 gRPC 的 OpenTelemetry 导出器 (otel.exporter.otlp.protocol=grpc) 使用 gRPC，而 gRPC 不支持按连接代理配置。如需通过代理服务器路由日志导出和 gRPC 遥测流量，请使用以下系统属性在 JVM 级别配置代理设置：

  -Dhttps.proxyHost=PROXY_HOST -Dhttps.proxyPort=PROXY_PORT

所需的 API 和 IAM 权限

如需成功将遥测数据写入 Google Cloud 可观测性，请在目标 Google Cloud 项目中执行以下设置：

1. 启用 API：
   • 启用 Cloud Trace API (cloudtrace.googleapis.com)。
   • 启用 Cloud Logging API (logging.googleapis.com)。
2. 授予 IAM 角色：
   • 对于导出轨迹：向主账号或服务账号授予 Trace Agent (roles/cloudtrace.agent) 角色。
   • 对于导出日志：向主账号或服务账号授予 Logs Writer (roles/logging.logWriter) 角色。

价格和结算

使用零配置 Google Cloud 遥测 (EnableGcpTraceExporter=true 或 EnableGcpLogExporter=true) 时，遥测数据会发送到 Trace 和 Logging。这些服务可能会根据注入的数据量收取费用。如需了解详情，请参阅 Google Cloud Observability。

指标

此集成不支持 OpenTelemetry 指标。

依赖项阴影

为防止与应用发生类路径冲突，驱动程序会对 OpenTelemetry SDK 和导出器依赖项进行阴影处理。OpenTelemetry API 保持未遮盖状态，以便与应用提供的 SDK 实现互操作性。

日志记录和轨迹关联

启用 OpenTelemetry 后，驱动程序会自动将日志与轨迹相关联：

• db.connection_id：作为 span 属性附加到所有 JDBC span。
• jdbc.connection_id：用作行李键，并作为标签附加到驱动程序向日志记录服务发送的所有日志条目。
• 跟踪 ID 和 span ID：在查询执行范围内生成的日志会自动包含有效的 trace_id 和 span_id。

价格

您可以免费下载适用于 BigQuery 的 JDBC 驱动程序。不过，在使用驱动程序时，您需要按标准 BigQuery 价格付费。

后续步骤

• 如需查看其他设置说明、连接网址属性参考手册、代码示例和本地 build 说明，请访问 GitHub 上的开源代码库：
  • 用户指南 (docs/USER_GUIDE.md)
  • 开发指南 (DEVELOPMENT.md)
  • BigQuery Storage API 深入分析 (docs/STORAGE_APIS.md)
• 详细了解 BigQuery 的 ODBC 驱动程序。
• 探索其他 BigQuery 开发者工具。