使用 BigQuery 的 JDBC 驅動程式

預先發布版

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

注意： 如要尋求支援或針對這項功能提供意見回饋，請傳送電子郵件至 [e-mail]。

BigQuery 的 Java Database Connectivity (JDBC) 驅動程式可將 Java 應用程式連線至 BigQuery，讓您透過偏好的工具和基礎架構使用 BigQuery 功能。如要將非 Java 應用程式連線至 BigQuery，請使用 BigQuery 專用的 Simba Open Database Connectivity (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 驅動程式建立連線時會用到。您只需要記下與所用驗證方法相應的資訊。

   驗證方式	驗證資訊	範例	連結資源 (稍後設定)
   標準服務帳戶	服務帳戶電子郵件地址	[e-mail]	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 檔案。
   • 含有依附元件的 Thin JAR。 包含 Thin JAR 檔案和所有依附元件的 ZIP 檔案。

2. 將下載的 JAR 檔案新增至類別路徑，讓 Java 編譯器和執行階段可以找到必要的 JDBC 類別。如要瞭解如何將檔案新增至類別路徑，請參閱「設定類別路徑」。

3. 在建構檔案中加入下列依附元件：

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

   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 類別也有設定器方法，可用來設定連線屬性，不必將這些屬性納入連線字串。範例如下：

     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	外部帳戶設定檔中的目標對象屬性。這個目標對象屬性可以包含 workload identity pool 或 workforce pool 的資源名稱，以及該集區中的提供者 ID。	不適用	字串	只有在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	如果查詢未指定資料集，系統會使用這個資料集。	不適用	字串	否
EnableHighThroughputAPI	決定是否可以使用 Storage Read API。如要使用 Storage Read API，也必須將 HighThroughputActivationRatio 和 HighThroughputMinTableSize 屬性設為 TRUE。	FALSE	布林值	否
EnableSession	決定連線是否會啟動工作階段。如果設為 TRUE，系統會將工作階段 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() 方法傳回的中繼資料範圍。如果設為 FALSE，系統就不會進行篩選。此外，您也必須設定 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	大型查詢結果的目的地資料集，僅在設定 LargeResultTable 屬性時適用。設定這項屬性後，資料寫入作業會略過結果快取，並針對每項查詢觸發計費，即使結果很小也是如此。	_google_jdbc	字串	否
LargeResultsDatasetExpirationTime	大型結果資料集中所有資料表的生命週期 (以毫秒為單位)。 如果資料集已設定預設到期時間，系統會忽略這項屬性。	3600000	Long	否
LargeResultTable	大型查詢結果的目的地資料表，僅在設定 LargeResultDataset 屬性時適用。設定這項屬性後，資料寫入作業會略過結果快取，並針對每項查詢觸發計費，即使結果很小也一樣。	temp_table...	字串	否
ListenerPoolSize	如果已啟用連線集區，則為接聽程式集區大小。	10	Long	否
Location	建立或查詢資料集的位置。如果未設定這項屬性，BigQuery 會自動判斷位置。	不適用	字串	否
LogLevel	java.util.logging 套件在資料庫互動期間記錄的詳細程度。記錄功能可能會影響效能，因此請只在需要擷取問題時暫時啟用。下列其中一項： 0：OFF 層級 1：SEVERE 層級 2：WARNING 層級 3：INFO 層級 4：CONFIG 層級 5：FINE 層級 6：FINER 層級 7：FINEST 層級 8：ALL 層級	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	Proxy 伺服器的主機名稱或 IP 位址，JDBC 連線會透過該伺服器路由傳輸。	不適用	字串	否
ProxyPort	Proxy 伺服器監聽連線的通訊埠編號。	不適用	字串	否
ProxyPwd	透過需要驗證的 Proxy 伺服器連線時，驗證用的密碼。	不適用	字串	否
ProxyUid	透過需要驗證的 Proxy 伺服器連線時，使用的驗證使用者名稱。	不適用	字串	否
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	Java TrustStore 的完整路徑，該檔案含有受信任的憑證授權單位 (CA) 憑證。驅動程式會在 SSL/TLS 握手期間，使用這個信任儲存區驗證伺服器的身分。	不適用	字串	否
SSLTrustStorePwd	Java TrustStore 的密碼，在 SSLTrustStore 屬性中指定。	不適用	字串	僅限 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	布林值	否

使用驅動程式執行查詢

Java 應用程式透過 JDBC 驅動程式連線至 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 驅動程式，而且使用驅動程式時不需要任何額外授權。不過，使用驅動程式時，須支付標準 BigQuery 費率。

後續步驟

• 進一步瞭解 BigQuery 專用的 Simba ODBC 驅動程式。
• 探索其他 BigQuery 開發人員工具。