使用 BigQuery 的 JDBC 驅動程式

BigQuery 的 Java Database Connectivity (JDBC) 驅動程式可將 Java 應用程式連線至 BigQuery，讓您使用偏好的工具和基礎架構，運用 BigQuery 功能。這個驅動程式專為 BigQuery 設計，無法用於其他產品或服務。使用這個驅動程式不需取得額外授權。

事前準備

請務必熟悉 JDBC 驅動程式和 java.sql 套件。
確認系統已設定 Java Runtime Environment (JRE) 8.0 以上版本。

設定驅動程式

如要設定 BigQuery 的 JDBC 驅動程式，您必須安裝驅動程式、向 BigQuery 驗證，並建立連線。

安裝驅動程式

下載下列其中一個 JDBC 套件：
- Uber JAR。包含所有依附元件的單一 JAR 檔案。
- 含有依附元件的精簡 JAR。包含 Thin 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;

使用外部方法進行驗證

您可以透過外部方法進行驗證，例如員工身分聯盟或 Workload Identity 聯盟。

使用 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 建構檔：

<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 專案，請將下列內容新增至建構檔案：

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 connection 屬性啟用 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

這個連線屬性會指定驅動程式是否處理大於 128 MB 的查詢結果 (當 QueryDialect 連線屬性設為 BIG_QUERY 時)。如果 QueryDialect 連線屬性設為 SQL，AllowLargeResults 連線屬性預設會設為 TRUE。詳情請參閱「大型結果集」。

預設值：TRUE
資料類型：布林 (值)
必要：否

BYOID_AudienceUri

這項連結屬性會在外部帳戶設定檔中指定目標對象屬性。這個屬性包含 workload identity pool 或 workforce pool 的資源名稱，以及該集區中的提供者 ID。

預設值：不適用
資料類型：字串
必要條件：僅限 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：外部驗證方法，例如 Workforce Identity Federation 或 Workload Identity Federation
預設值：-1
資料類型：整數
必要：是

PartnerToken

合作夥伴會使用這項連線屬性追蹤驅動程式的使用情形。 Google Cloud

預設值：不適用
資料類型：字串
必要：否

PrivateServiceConnectUris

這項連結資源屬性與 EndpointOverrides 資源屬性相同。請改用 EndpointOverrides 屬性。

ProjectId

這項連線屬性會為驅動程式設定預設專案 ID。這項專案用於執行查詢，並會根據資源用量計費。如未設定，驅動程式會推斷專案 ID。

預設值：不適用
資料類型：字串
必要性：否，但強烈建議使用

ProxyHost

這項連線屬性會設定 Proxy 伺服器的主機名稱或 IP 位址，JDBC 連線會透過該伺服器路由傳輸。

預設值：不適用
資料類型：字串
必要：否

ProxyPort

這項連線屬性會設定 Proxy 伺服器接聽連線的連接埠號碼。

預設值：不適用
資料類型：字串
必要：否

ProxyPwd

透過需要驗證的 Proxy 伺服器連線時，這項連線屬性會設定驗證所需的密碼。

預設值：不適用
資料類型：字串
必要：否

ProxyUid

透過需要驗證的 Proxy 伺服器連線時，這項連線屬性會設定驗證所需的使用者名稱。

預設值：不適用
資料類型：字串
必要：否

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

這個連線屬性會指定 Java TrustStore 的完整路徑，其中包含受信任的憑證授權單位 (CA) 憑證。驅動程式會使用這個信任儲存區，在 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` 個查詢