使用 BigQuery 的 JDBC 驅動程式

BigQuery 的 Java 資料庫連線 (JDBC) 驅動程式可將 Java 應用程式連結至 BigQuery，讓您透過偏好的工具和基礎架構使用 BigQuery 功能。如要將非 Java 應用程式連結至 BigQuery，請使用 BigQuery 的開放式資料庫連線 (ODBC) 驅動程式。

限制

BigQuery 的 JDBC 驅動程式有下列限制：

• 這項驅動程式專用於 BigQuery，無法與其他產品或服務搭配使用。
• BigQuery Storage Read API 不支援 INTERVAL 資料類型。
• 所有資料操縱語言 (DML) 限制皆適用。

事前準備

1. 請務必熟悉 JDBC 驅動程式、Apache Maven 和 java.sql 套件。
2. 確認系統已設定 Java Runtime Environment (JRE) 8.0 以上版本。如要瞭解如何檢查 JRE 版本，請參閱「驗證 JRE 環境」。

3. 向 BigQuery 驗證，並記下下列資訊，稍後使用 BigQuery 的 JDBC 驅動程式建立連線時會用到。您只需要記下與所用驗證方式對應的資訊。

   驗證方式	驗證資訊	範例	連線屬性 (稍後設定)
   標準服務帳戶	服務帳戶電子郵件地址	bq-jdbc-sa@mytestproject.s3ns.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

安裝及設定 JDBC 驅動程式

您可以直接下載 uber-JAR 檔案，或使用 Maven，安裝及設定 BigQuery 的 JDBC 驅動程式。

直接下載設定

如要透過直接下載設定 JDBC 驅動程式，請按照下列步驟操作：

1. 下載 1.6.0 版驅動程式。
2. 將下載的檔案複製到軟體指定的位置。

如要瞭解功能異動和工作流程更新，請參閱變更記錄。

Maven 設定

BigQuery 的 JDBC 驅動程式可在 Maven Central 取得。

如要使用 JDBC 驅動程式設定開發環境，請將驅動程式新增為專案的依附元件：

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

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

dependencies {
// ... other dependencies
implementation("com.google.cloud:google-cloud-bigquery-jdbc:1.6.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 驅動程式支援下列連線屬性。

使用驅動程式執行查詢

Java 應用程式透過 JDBC 驅動程式連結至 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());

驅動程式會以 struct 物件或 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。
• 分頁：系統會追蹤額外結果頁面的非同步擷取作業 (使用 REST API 路徑時)，並使用 OpenTelemetry Span Links，將這些作業與原始查詢執行範圍建立因果連結。系統會為這些作業建立名為 BigQueryStatement.pagination 的 Span。
• 內容傳播：JDBC 驅動程式會將有效內容傳播至基礎 google-cloud-bigquery SDK。因此，SDK 產生的 span (例如 HTTP RPC 呼叫) 會自動顯示為 JDBC 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。

免設定 Cloud de Confiance 遙測

如果您在 Cloud de Confiance 上執行，且想快速設定，可以啟用自動匯出追蹤記錄和記錄檔至 Cloud de Confiance 觀測能力 (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 整合時，請留意下列有關記錄行為、驗證、Proxy 設定和定價的注意事項。

與 LogLevel 互動

現有的 LogLevel 連線屬性是記錄功能的主要守門員。

• 如果設為 LogLevel=0 (OFF)，系統就不會產生記錄。因此，即使 EnableGcpLogExporter=true，系統也不會使用 OpenTelemetry 匯出任何記錄，也不會將記錄匯出至 Logging。
• 如要啟用 OTel 記錄功能，請務必將 LogLevel 設為大於 0 的值 (例如，5 代表詳細記錄)。

遙測資料驗證

遙測匯出 (追蹤和記錄) 搭配自動Cloud de Confiance 備用機制，支援應用程式預設憑證 (ADC) 和使用GcpTelemetryCredentials提供的明確服務帳戶憑證。

如果提供 GcpTelemetryProjectId 或 GcpTelemetryCredentials，系統會使用相同的設定憑證，將記錄和追蹤記錄傳送至同一個指定目的地專案。

使用 OpenTelemetry 和記錄功能設定 Proxy

如果應用程式透過 Proxy 伺服器連線至 BigQuery，驅動程式會按照下列方式處理 Proxy 轉送：

• 追蹤記錄匯出 (HTTP)。使用 OpenTelemetry 追蹤記錄匯出的預設 HTTP 通訊協定 (otel.exporter.otlp.protocol=http/protobuf) 時，驅動程式會使用 ProxyHost 和 ProxyPort，自動透過連線屬性中設定的 Proxy 轉送追蹤記錄匯出流量。

• 記錄匯出和 gRPC 遙測。自動 Cloud de Confiance 記錄匯出工具 (EnableGcpLogExporter=true) 和以 gRPC 為基礎的 OpenTelemetry 匯出工具 (otel.exporter.otlp.protocol=grpc) 使用 gRPC，不支援個別連線 Proxy 設定。如要透過 Proxy 伺服器轉送記錄匯出和 gRPC 遙測流量，請使用下列系統屬性，在 JVM 層級設定 Proxy 設定：

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

必要的 API 和 IAM 權限

如要成功將遙測資料寫入 Cloud de Confiance by S3NS 觀測能力，請在目標 Cloud de Confiance 專案中執行下列設定：

1. 啟用 API：
   • 啟用 Cloud Trace API (cloudtrace.googleapis.com)。
   • 啟用 Cloud Logging API (logging.googleapis.com)。
2. 授予 IAM 角色：
   • 匯出追蹤記錄：將 Trace 代理程式 (roles/cloudtrace.agent) 角色授予主體或服務帳戶。
   • 匯出記錄：將記錄寫入者 (roles/logging.logWriter) 角色授予主體或服務帳戶。

價格與計費

使用零設定 Cloud de Confiance 遙測 (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：做為行李金鑰，並以標籤形式附加至驅動程式傳送至 Logging 的所有記錄項目。
• 追蹤記錄 ID 和 Span ID：在查詢執行範圍內產生的記錄，會自動包含有效的 trace_id 和 span_id。

定價

您可以免付費下載 BigQuery 的 JDBC 驅動程式。不過，使用驅動程式時，須支付標準 BigQuery 費用。

後續步驟

• 如需其他設定操作說明、連線網址屬性參考手冊、程式碼範例和本機建構操作說明，請造訪 GitHub 上的開放原始碼存放區：
  • 使用手冊 (docs/USER_GUIDE.md)
  • 開發指南 (DEVELOPMENT.md)
  • 深入瞭解 BigQuery Storage API (docs/STORAGE_APIS.md)
• 進一步瞭解 BigQuery 的 ODBC 驅動程式。
• 探索其他 BigQuery 開發人員工具。