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

适用于 BigQuery 的 Java Database Connectivity (JDBC) 驱动程序可将您的 Java 应用连接到 BigQuery，让您能够将 BigQuery 功能与首选工具和基础架构结合使用。此驱动程序专为 BigQuery 而设计，无法与其他产品或服务搭配使用。您无需任何其他许可即可使用此驱动程序。

准备工作

确保您熟悉 JDBC 驱动程序和 java.sql 软件包。
验证您的系统是否已配置 Java 运行时环境 (JRE) 8.0 或更高版本。

配置驱动程序

如需为 BigQuery 配置 JDBC 驱动程序，您必须安装该驱动程序、向 BigQuery 进行身份验证，并建立连接。

安装驱动程序

下载以下 JDBC 软件包之一：
- Uber JAR。包含所有依赖项的单个 JAR 文件。
- 包含依赖项的精简 JAR。包含精简 JAR 文件和所有依赖项的 ZIP 文件。
- 阴影 Uber JAR。包含所有依赖项且经过阴影处理的单个 JAR 文件。
将下载的 JAR 文件添加到类路径中，以便 Java 编译器和运行时可以找到必要的 JDBC 类。

向 BigQuery 进行身份验证

适用于 BigQuery 的 JDBC 驱动程序提供多种身份验证选项：

使用服务账号
使用 Google 用户账号
使用预生成的访问令牌和刷新令牌
使用应用默认凭据
使用外部方法

使用服务账号进行身份验证

当您使用 BigQuery 的 JDBC 驱动程序建立连接时，请执行以下操作：

将 OAuthType 连接属性设置为 0。
将 ProjectId 连接属性设置为您的 BigQuery 项目的名称。
执行以下某项操作：
- 如果您使用的是服务账号电子邮件地址和密钥，请将 OAuthServiceAcctEmail 连接属性设置为您的 Google 服务账号电子邮件地址，并将 OAuthPvtKey 连接属性设置为服务账号密钥 JSON 对象。对于 OAuthPvtKey，您可以使用密钥的 JSON 对象或密钥文件的完整路径。
- 如果您使用的是服务账号密钥文件，请将 OAuthPvtKeyPath 连接属性设置为服务账号密钥文件的完整路径。

以下两个示例使用服务账号身份验证：

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=0;
OAuthServiceAcctEmail=bq-jdbc-sa@mytestproject.iam.gserviceaccount.com;
OAuthPvtKey=my-sa-key

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=0;
OAuthPvtKeyPath=path/to/file/secret.json;

使用 Google 用户账号进行身份验证

当您使用 BigQuery 的 JDBC 驱动程序建立连接时，请执行以下操作：

将 OAuthType 连接属性设置为 1。
将 ProjectId 连接属性设置为您的 BigQuery 项目的名称。
将 OAuthClientId 连接属性设置为您的客户端 ID，并将 OAuthClientSecret 连接属性设置为您的客户端密钥。

如需了解详情，请参阅使用 OAuth 2.0 访问 Google API 和管理 OAuth 客户端。

以下示例使用 Google 用户账号身份验证：

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=1;
OAuthClientId=123456789012-abcdefghijklmnopqrstuvwxyz12345.apps.googleusercontent.com;
OAuthClientSecret=_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV;

使用预生成的访问令牌或刷新令牌进行身份验证

当您使用 BigQuery 的 JDBC 驱动程序建立连接时，请执行以下操作：

将 OAuthType 连接属性设置为 2。
将 ProjectId 连接属性设置为您的 BigQuery 项目的名称。
执行以下某项操作：
- 如果您使用的是预生成的访问令牌，请将 OAuthAccessToken 连接属性设置为您的访问令牌。
- 如果您使用的是预生成的刷新令牌，请将 OAuthRefreshToken 连接属性设置为您的刷新令牌，将 OAuthClientId 连接属性设置为您的客户端 ID，并将 OAuthClientSecret 连接属性设置为您的客户端密钥。

如需了解详情，请参阅使用 OAuth 2.0 访问 Google API。

以下示例使用预生成的访问令牌进行身份验证：

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=2;
OAuthAccessToken=ya29.a0AfH6SMCiH1L-x_yZABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_;

以下示例使用预生成的刷新令牌进行身份验证：

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=2;
OAuthClientId=123456789012-abcdefghijklmnopqrstuvwxyz12345.apps.googleusercontent.com;
OAuthClientSecret=_aB-C1D_E2fGh3Ij4kL5m6No7p8QR9sT0uV;
OAuthRefreshToken=1/fFAGRNJru1FTz70BzhT3Zg;

使用应用默认凭据进行身份验证

应用默认凭据 (ADC) 是身份验证库使用的一种策略，可根据应用环境自动查找凭据。

当您使用 BigQuery 的 JDBC 驱动程序建立连接时，请执行以下操作：

将 OAuthType 连接属性设置为 3。
将 ProjectId 连接属性设置为您的 BigQuery 项目的名称。

如需了解详情，请参阅设置应用默认凭证。

以下示例使用 ADC 身份验证：

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=3;

使用外部方法进行身份验证

您可以使用员工身份联合或工作负载身份联合等外部方法进行身份验证。

当您使用 BigQuery 的 JDBC 驱动程序建立连接时，请执行以下操作：

将 OAuthType 连接属性设置为 4。
将 ProjectId 连接属性设置为您的 BigQuery 项目的名称。
执行以下某项操作：
- 将 OAuthPvtKey 连接属性或 OAuthPvtKeyPath 连接属性设置为配置文件的完整路径。对于 OAuthPvtKey，您可以使用密钥的 JSON 对象或密钥文件的完整路径。
- 将 OAuthPvtKey 连接属性设置为原始外部账号配置对象。
- 设置以下 BYOID 连接属性（如连接属性部分中所述）：
  - BYOID_AudienceUri
  - BYOID_CredentialSource
  - BYOID_PoolUserProject
  - BYOID_SA_Impersonation_Uri
  - BYOID_SubjectTokenType
  - BYOID_TokenUri

以下示例使用外部身份验证方法：

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=4;
OAuthPvtKeyPath=path/to/file/secret.json;

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=4;
OAuthPvtKey=External_account_configuration_object;

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
ProjectId=MyTestProject;OAuthType=4;
BYOID_AudienceUri=//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider;
BYOID_SubjectTokenType=urn:ietf:params:oauth:tokentype:id_token;
BYOID_CredentialSource={\"file\":\"/path/to/file\"};
BYOID_SA_Impersonation_Uri=my-sa;
BYOID_TokenUri=https://sts.googleapis.com/v1/token;"

以下是一个配置文件示例：

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/my_pool_name/providers/my_provider_name",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "/path/to/workforce/tokrn.txt"
  },
  "workforce_pool_user_project": "my_project",
  "token_info_url": "https://sts.googleapis.com/v1/introspect"
}

建立连接

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

将 google-cloud-bigquery-jdbc 依赖项添加到 Maven POM/Gradle build 文件中：

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-bigquery-jdbc</artifactId>
    <version>0.0.1</version>
    <scope>system</scope>
    <systemPath>path/to/file/google-jdbc-jar-with-dependencies.jar</systemPath>
</dependency>

如果您使用的是 Gradle 项目，请将以下内容添加到 build 文件中：

dependencies {
// ... other dependencies
implementation files('path/to/file/google-jdbc-jar-with-dependencies.jar')
}

确定 JDBC 驱动程序的连接字符串。此字符串包含在 Java 应用与特定数据库之间建立连接所需的所有基本信息。BigQuery 连接字符串的 JDBC 驱动程序采用以下格式：
```
jdbc:bigquery://HOST:PORT;ProjectId=PROJECT_ID;OAuthType=AUTH_TYPE;PROPERTIES
```
替换以下内容：
- HOST：服务器的 DNS 或 IP 地址。
- PORT：TCP 端口号。
- PROJECT_ID：BigQuery 项目的 ID。
- AUTH_TYPE：一个数字，用于指定您使用的身份验证类型。以下项之一：
  - 0：Google 服务账号身份验证
  - 1：Google 用户账号身份验证
  - 2：预生成的刷新令牌或访问令牌身份验证
  - 3：应用默认凭据身份验证
  - 4：外部身份验证方法，例如员工身份联合或工作负载身份联合
- PROPERTIES：JDBC 驱动程序的其他连接属性。属性必须以 property_1=value_1; property_2=value_2;... 格式列出。属性名称不区分大小写。如需查看连接属性的完整列表，请参阅连接属性。

使用 DriverManager 或 DataSource 类连接到驱动程序。

连接到 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(CONNECTION_STRING);
  ds.setAuthType(3);  // Application Default Credentials
  ds.setProjectId("MyTestProject");
  ds.setEnableHighThroughputAPI(true);
  ds.setLogLevel("6");
  ds.setUseQueryCache(false);
  return ds.getConnection();
}

探索驾驶员功能

现在，您已连接到 BigQuery 的 JDBC 驱动程序，可以探索其功能了。

SQL 连接器

借助 SQL 连接器，您可以使用 BigQuery 运行 SQL 查询。使用 QueryDialect 连接属性指定要使用的 SQL 方言。

数据类型映射

适用于 BigQuery 的 JDBC 驱动程序支持以下数据类型映射：

BigQuery 类型	SQL 类型	Java 类型
`ARRAY`	`ARRAY`	`Array`
`BIGNUMERIC`	`NUMERIC`	`BigDecimal`
`BOOL`	`BOOLEAN`	`Boolean`
`BYTES`	`VARBINARY`	`byte[]`
`DATE`	`DATE`	`Date`
`DATETIME`	`OTHER`	`String`
`FLOAT64`	`DOUBLE`	`Double`
`GEOGRAPHY`	`OTHER`	`String`
`INT64`	`BIGINT`	`Long`
`INTERVAL`	`OTHER`	`String`
`JSON`	`OTHER`	`String`
`NUMERIC`	`NUMERIC`	`BigDecimal`
`STRING`	`NVARCHAR`	`String`
`STRUCT`	`STRUCT`	`Struct`
`TIME`	`TIME`	`Time`
`TIMESTAMP`	`TIMESTAMP`	`Timestamp`

嵌套和重复记录

BigQuery 的 JDBC 驱动程序支持嵌套和重复记录，其中驱动程序将基本类型作为结构对象或 JSON 对象的字符串表示形式返回。

以下是查询结构体数据基本记录的示例：

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

结果如下：

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

以下示例展示了如何查询结构对象中的子组件：

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]);
}

以下是查询重复数据结构体数组的示例：

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

大型结果集

使用适用于 BigQuery 的 JDBC 驱动程序检索大型结果集时，请执行以下操作：

如果您的 QueryDialect 连接属性设置为 SQL，请使用 LargeResultDataset 和 LargeResultTable 连接属性指定用于存储结果的数据集和表。
如果您的 QueryDialect 连接属性设置为 BIG_QUERY，请将 AllowLargeResults 连接属性设置为 TRUE，并使用 LargeResultDataset 和 LargeResultTable 连接属性指定用于存储结果的数据集和表。

在这两种情况下，您都可以使用 LargeResultsDatasetExpirationTime 连接属性来指定目标数据集的生命周期时长。

如果您未为 LargeResultDataset 和 LargeResultTable 连接属性指定值，则适用于 BigQuery 的 JDBC 驱动程序会创建一个名为 _google_jdbc 的隐藏数据集，并在其中创建一个临时表。这些资源会在 24 小时后自动删除。

您仍需遵循 BigQuery 的所有配额和限制。

定位参数

位置参数是 SQL 语句中的占位符，表示在查询执行期间要提供的值。适用于 BigQuery 的 JDBC 驱动程序支持使用问号符号 (?) 的位置参数。以下是使用位置参数的查询示例：

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

`SELECT` 查询

您可以使用 BigQuery 的 JDBC 驱动程序通过 BigQuery API 或 BigQuery Storage Read API 执行 SELECT 查询。

如果您使用 BigQuery API，请设置 JobCreationMode 连接属性，以指定查询是否在创建作业的情况下运行。

如果您使用 Storage Read API，请使用 EnableHighThroughputAPI 连接属性启用该 API，并验证是否满足以下条件：

相应架构未使用 INTERVAL 类型。
总行数小于 HighThroughputMinTableSize 连接属性的值。
行数与页面大小的比率小于 HighThroughputActivationRatio 连接属性的值。

批量插入

如需使用适用于 BigQuery 的 JDBC 驱动程序执行批量插入操作，请使用 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 驱动程序支持通过 Java Util Logging 记录驱动程序中的操作。日志记录可能会影响性能，因此仅在需要捕获问题时启用，并在完成后停用。

如需配置日志记录，请执行以下操作：

根据下表设置 LogLevel 属性：

`LogLevel` 值	`LogLevel`	说明
`0`	`OFF`	未记录任何消息。
`1`	`SEVERE`	影响应用功能的严重故障或错误。
`2`	`WARNING`	可能存在需要注意的问题或情况。
`3`	`INFO`	有关正常事件和进度的信息性消息。
`4`	`CONFIG`	有关静态配置信息的消息。
`5`	`FINE`	一般跟踪消息。
`6`	`FINER`	详细的跟踪消息。
`7`	`FINEST`	非常详细的跟踪消息，适用于广泛的调试。
`8`	`ALL`	系统会记录所有消息。

将 LogPath 属性设置为要保存日志文件的文件夹的完整路径。

或者，您也可以使用 BIGQUERY_JDBC_LOG_LEVEL 和 BIGQUERY_JDBC_LOG_PATH 环境变量配置日志记录。

连接属性

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

AdditionalProjects

借助此连接属性，查询和元数据操作可以访问指定项目中的数据集，以及连接字符串中定义的主项目。

默认值：不适用
数据类型：字符串（以英文逗号分隔的项目 ID 字符串）
必需：否

AllowLargeResults

此连接属性用于指定当 QueryDialect 连接属性设置为 BIG_QUERY 时，驱动程序是否处理大于 128 MB 的查询结果。如果 QueryDialect 连接属性设置为 SQL，则 AllowLargeResults 连接属性默认设置为 TRUE。如需了解详情，请参阅大型结果集。

默认值：TRUE
数据类型：布尔值
必需：否

BYOID_AudienceUri

此连接属性用于指定外部账号配置文件中的受众群体属性。受众群体属性包含工作负载身份池或员工池的资源名称，以及相应池中的提供方标识符。

默认值：不适用
数据类型：字符串
必需：仅当 OAuthType=4 时

BYOID_CredentialSource

此连接属性用于设置令牌检索信息和环境信息。

默认值：不适用
数据类型：字符串
必需：仅当 OAuthType=4 时

BYOID_PoolUserProject

此连接属性用于在使用员工池时设置用户项目。项目必须具有 serviceusage.services.use IAM 权限。

默认值：不适用
数据类型：字符串
必需：仅当 OAuthType=4 且使用劳动力池时

BYOID_SA_Impersonation_Uri

此连接属性用于在以下情况下设置服务账号模拟的网址：使用工作负载身份池，但 API 尚未与 UberMint 集成。

默认值：不适用
数据类型：字符串
必需：仅当 OAuthType=4 且使用工作负载身份池和服务账号模拟时

BYOID_SubjectTokenType

此连接属性会根据令牌交换规范设置 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
默认值：urn:ietf:params:oauth:tokentype:id_token
数据类型：字符串
必需：仅当 OAuthType=4 时

BYOID_TokenUri

此连接属性用于设置 STS 令牌交换端点。

默认值：https://sts.googleapis.com/v1/token
数据类型：字符串
必需：否

ConnectionPoolSize

如果启用了连接池，此连接属性会设置连接池大小。

默认值：10
数据类型：Long
必需：否

DefaultDataset

此连接属性用于指定在运行未明确指定数据集的查询时所使用的数据集。您可以使用 DATASET_ID 或 PROJECT_ID.DATASET_ID 格式。

默认值：不适用
数据类型：字符串
必需：否

EnableHighThroughputAPI

此连接属性用于确定是否可以使用 Storage Read API。若要使用 Storage Read API，还必须满足 HighThroughputActivationRatio 和 HighThroughputMinTableSize 连接属性。

默认值：FALSE
数据类型：布尔值
必需：否

EnableSession

此连接属性用于确定连接是否启动会话。使用时，会话 ID 会传递给所有后续查询。

默认值：FALSE
数据类型：布尔值
必需：否

EnableWriteAPI

此连接属性用于确定是否可以使用 Storage Write API。必须将其设置为 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() 方法返回的元数据的范围。如果停用此属性，系统不会执行任何过滤操作。还必须设置 DefaultDataset 连接属性才能启用过滤功能。

默认值：FALSE
数据类型：布尔值
必需：否

HighThroughputActivationRatio

此连接属性用于设置查询响应中网页数量的阈值。如果超过此数量，并且满足 EnableHighThroughputAPI 和 HighThroughputMinTableSize 条件，驱动程序会开始使用 Storage Read API。

默认值：2
数据类型：整数
必需：否

HighThroughputMinTableSize

此连接属性用于设置查询响应中行数的阈值。如果超过此数量，并且满足 EnableHighThroughputAPI 和 HighThroughputActivationRatio 条件，驱动程序会开始使用 Storage Read API。

默认值：100
数据类型：整数
必需：否

JobCreationMode

此连接属性用于确定是否在不创建作业的情况下运行查询。值为 1 表示系统会为每个查询创建作业，值为 2 表示可以在没有作业的情况下执行查询。

默认值：2
数据类型：整数
必需：否

JobTimeout

此连接属性用于设置作业超时时间（以秒为单位），超过此时间后，系统会在服务器上取消作业。

默认值：0
数据类型：Long
必需：否

KMSKeyName

此连接属性用于设置加密数据的 KMS 密钥名称。

默认值：不适用
数据类型：字符串
必需：否

Labels

此连接属性用于设置与查询相关联的标签，以便整理和分组查询作业。

默认值：不适用
数据类型：Map<String, String>
必需：否

LargeResultDataset

此连接属性用于设置查询结果的目标数据集。如需了解详情，请参阅大型结果集。

默认值：_google_jdbc，仅当 QueryDialect=BIG_QUERY 或当 QueryDialect=SQL 且设置了 LargeResultTable 连接属性时
数据类型：字符串
必需：否

LargeResultsDatasetExpirationTime

此连接属性用于指定数据集中所有表的生命周期（以毫秒为单位）。如果数据集已设置默认到期时间，则系统会忽略此属性。

默认值：3600000
数据类型：Long
必需：否

LargeResultTable

此连接属性用于设置查询结果的目标表。如需了解详情，请参阅大型结果集。

默认值：temp_table...，仅当 QueryDialect=BIG_QUERY 或 QueryDialect=SQL 且设置了 LargeResultTable 连接属性时
数据类型：字符串
必需：否

ListenerPoolSize

如果启用了连接池，此连接属性会设置监听器池大小。

默认值：10
数据类型：Long
必需：否

Location

此连接属性用于指定创建或查询数据集的位置。如果未设置此值，BigQuery 会自动确定位置。

默认值：不适用
数据类型：字符串
必需：否

LogLevel

此连接属性用于控制数据库交互期间记录的详细信息级别。如需查看级别说明，请参阅日志记录。

默认值：0
数据类型：整数
必需：否

LogPath

此连接属性用于设置写入日志文件的目录。如需了解详情，请参阅日志记录。

默认值：不适用
数据类型：字符串
必需：否

MaximumBytesBilled

此连接属性用于限制结算的字节数。如果查询的收费字节数超出此限制，则查询会失败（不会产生费用）。

默认值：0
数据类型：Long
必需：否

MaxResults

此连接属性用于设置每页的最大结果数。

默认值：10000
数据类型：Long
必需：否

MetaDataFetchThreadCount

此连接属性用于配置数据库元数据方法所使用的线程数。

默认值：32
数据类型：整数
必需：否

OAuthAccessToken

此连接属性用于指定预生成的访问令牌身份验证所使用的访问令牌。

默认值：不适用
数据类型：字符串
必需：当 AUTH_TYPE=2

OAuthClientId

此连接属性用于为预生成的刷新令牌身份验证和用户账号身份验证设置客户端 ID。

默认值：不适用
数据类型：字符串
必需：当 AUTH_TYPE=1 或 AUTH_TYPE=2

OAuthClientSecret

此连接属性用于设置预生成的刷新令牌身份验证和用户账号身份验证的客户端密钥。

默认值：不适用
数据类型：字符串
必需：当 AUTH_TYPE=1 或 AUTH_TYPE=2

OAuthP12Password

此连接属性用于设置 PKCS12 密钥文件的密码。

默认值：notasecret
数据类型：字符串
必需：否

OAuthPvtKey

此连接属性用于在使用服务账号身份验证时设置服务账号密钥。此值可以是原始 JSON 密钥文件对象，也可以是 JSON 密钥文件的路径。

默认值：不适用
数据类型：字符串
必需：当 AUTH_TYPE=0 和 OAuthPvtKeyPath 值未设置时

OAuthPvtKeyPath

此连接属性用于在使用服务账号身份验证时设置服务账号密钥的路径。

默认值：不适用
数据类型：字符串
必需：当未设置 AUTH_TYPE=0 以及 OAuthPvtKey 和 OAuthServiceAcctEmail 值时

OAuthRefreshToken

此连接属性用于为预生成的刷新令牌身份验证设置刷新令牌。OAuth 2.0 刷新令牌是一种特殊类型的令牌，可让应用在当前访问令牌过期时获取新的访问令牌，而无需用户重新进行身份验证。

默认值：不适用
数据类型：字符串
必需：当 AUTH_TYPE=2

OAuthServiceAcctEmail

此连接属性用于在使用服务账号身份验证时设置服务账号电子邮件地址。

默认值：不适用
数据类型：字符串
必需：当 AUTH_TYPE=0 和 OAuthPvtKeyPath 值未设置时

OAuthType

此连接属性用于指定身份验证类型。该值必须为以下项之一：

0：Google 服务账号身份验证
1：Google 用户账号身份验证
2：预生成的刷新令牌或访问令牌身份验证
3：应用默认凭据身份验证
4：外部身份验证方法，例如员工身份联合或工作负载身份联合
默认值：-1
数据类型：整数
必需：是

PartnerToken

此连接属性供 Google Cloud 合作伙伴用于跟踪驱动程序的使用情况。

默认值：不适用
数据类型：字符串
必需：否

PrivateServiceConnectUris

此连接属性与 EndpointOverrides 属性相同。请改用 EndpointOverrides 属性。

ProjectId

此连接属性用于为驱动程序设置默认项目 ID。此项目用于执行查询，并按资源使用情况付费。如果未设置，驱动程序会推断项目 ID。

默认值：不适用
数据类型：字符串
必需：否，但强烈建议

ProxyHost

此连接属性用于设置代理服务器的主机名或 IP 地址，JDBC 连接将通过该代理服务器进行路由。

默认值：不适用
数据类型：字符串
必需：否

ProxyPort

此连接属性用于设置代理服务器监听连接的端口号。

默认值：不适用
数据类型：字符串
必需：否

ProxyPwd

此连接属性用于设置通过需要进行身份验证的代理服务器进行连接时所需的密码。

默认值：不适用
数据类型：字符串
必需：否

ProxyUid

此连接属性用于设置通过需要进行身份验证的代理服务器进行连接时所需的用户名。

默认值：不适用
数据类型：字符串
必需：否

QueryDialect

此连接属性用于设置查询执行的 SQL 方言。使用 SQL（强烈推荐）表示 GoogleSQL，使用 BIG_QUERY 表示旧版 SQL。

默认值：SQL
数据类型：字符串
必需：否

QueryProperties

此连接属性用于配置查询行为修改。

以下是连接字符串中设置的示例：

jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;
QueryProperties=dataset_project_id=TestProjectID,time_zone=America/New_York;

以下是在 DataSource 类中设置的示例：

Map<String, String> queryProperties = new HashMap<>();
queryProperties.put("dataset_project_id", "TestProjectID");
queryProperties.put("time_zone", "America/New_York");
DataSource dataSource = new DataSource();
dataSource.setQueryProperties(queryProperties);

如需了解详情，请参阅 ConnectionProperty。

默认值：不适用
数据类型：Map<String, String>
必需：否

RequestGoogleDriveScope

此连接属性用于请求访问 Google 云端硬盘。启用后，系统会将只读云端硬盘范围添加到连接中。如需启用此属性，请将值设置为 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 握手期间验证服务器的身份。

默认值：不适用
数据类型：字符串
必需：否

SSLTrustStorePwd

此连接属性用于指定 SSLTrustStore 属性中指定的 Java TrustStore 的密码。

默认值：不适用
数据类型：字符串
必需：仅当使用受密码保护的 Java TrustStore 时才需要

SWA_ActivationRowCount

此连接属性用于设置 executeBatch insert 行的阈值数量，当超过此阈值时，连接器会切换到 Storage Write API。

默认值：3
数据类型：整数
必需：否

SWA_AppendRowCount

此连接属性用于设置写入流的大小。

默认值：1000
数据类型：整数
必需：否

Timeout

此连接属性用于设置连接器在超时之前重试失败的 API 调用的时长（以秒为单位）。

默认值：0
数据类型：Long
必需：否

UniverseDomain

此连接属性用于设置宇宙网域，即与组织的 Google Cloud 资源相关联的顶级网域。

默认值：googleapis.com
数据类型：字符串
必需：否

UnsupportedHTAPIFallback

此连接属性用于确定连接器是回退到 REST API（设置为 TRUE 时）还是返回错误（设置为 FALSE 时）。

默认值：TRUE
数据类型：布尔值
必需：否

UseQueryCache

此连接属性可启用查询缓存。

默认值：TRUE
数据类型：布尔值
必需：否

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

准备工作

配置驱动程序

安装驱动程序

向 BigQuery 进行身份验证

使用服务账号进行身份验证

使用 Google 用户账号进行身份验证

使用预生成的访问令牌或刷新令牌进行身份验证

使用应用默认凭据进行身份验证

使用外部方法进行身份验证

建立连接

探索驾驶员功能

SQL 连接器

数据类型映射

嵌套和重复记录

大型结果集

定位参数

SELECT 查询

批量插入

日志记录

连接属性

`SELECT` 查询