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

适用于 BigQuery 的 Java Database Connectivity (JDBC) 驱动程序可将 Java 应用连接到 BigQuery，让您能够将 BigQuery 功能与首选工具和基础架构结合使用。如需将非 Java 应用连接到 BigQuery，请使用 Simba Open Database Connectivity (ODBC) 驱动程序（适用于 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.iam.gserviceaccount.com	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

配置开发环境

如需使用适用于 BigQuery 的 JDBC 驱动程序配置开发环境，请执行以下操作：

1. 下载以下 JDBC 软件包之一：

   • Uber JAR。 包含所有依赖项的 JAR 文件。
   • 阴影 Uber JAR。 包含所有依赖项的阴影 JAR 文件。
   • 包含依赖项的精简 JAR。 包含精简 JAR 文件和所有依赖项的 ZIP 文件。

2. 将下载的 JAR 文件添加到类路径中，以便 Java 编译器和运行时可以找到必要的 JDBC 类。如需了解如何将文件添加到类路径，请参阅设置类路径。

3. 将以下依赖项添加到您的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>

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

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

建立连接

如需使用适用于 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 驱动程序支持以下连接属性。

使用驱动程序运行查询

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

数据类型映射

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

示例

以下部分提供了通过适用于 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 驱动程序，并且无需任何其他许可即可使用这些驱动程序。不过，当您使用该驱动程序时，需要按标准 BigQuery 价格付费。

后续步骤

• 详细了解适用于 BigQuery 的 Simba ODBC 驱动程序。
• 探索其他 BigQuery 开发者工具。