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 ファイル。
- 依存関係を含む thin 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 接続プロパティをサービスアカウントキーファイルのフルパスに設定します。

次の 2 つの例では、サービスアカウント認証を使用しています。

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;

外部メソッドで認証する

Workforce Identity 連携や 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 ドライバとの接続を確立するには、次の操作を行います。

Maven POM/Gradle ビルドファイルに google-cloud-bigquery-jdbc 依存関係を追加します。

<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: Workforce Identity 連携や Workload Identity 連携などの外部認証方法
- 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 クラスにはセッターメソッドもあります。このメソッドを使用すると、接続文字列にすべてのプロパティを含めるのではなく、接続プロパティを設定できます。次に例を示します。

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 クエリを実行できます。使用する SQL 言語を指定するには、QueryDialect 接続プロパティを使用します。

データ型マッピング

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 ドライバは、ネストされた繰り返しレコードをサポートしています。ドライバは、基本型を struct オブジェクトまたは JSON オブジェクトの文字列表現として返します。

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

結果は次のようになります。

{
  "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 ドライバでは、接続プロパティは、データベースへの接続を確立するときに接続文字列に含めるか、セッターメソッドを介して渡すことができる構成パラメータです。BigQuery 用 JDBC ドライバでは、次の接続プロパティがサポートされています。

AdditionalProjects

この接続プロパティを使用すると、接続文字列で定義されたプライマリプロジェクトに加えて、指定されたプロジェクト内のデータセットにクエリとメタデータオペレーションでアクセスできます。

デフォルト値: なし
データ型: String（プロジェクト ID のカンマ区切り文字列）
必須: いいえ

AllowLargeResults

この接続プロパティは、QueryDialect 接続プロパティが BIG_QUERY に設定されている場合に、ドライバが 128 MB を超えるクエリ結果を処理するかどうかを指定します。QueryDialect 接続プロパティが SQL に設定されている場合、AllowLargeResults 接続プロパティはデフォルトで TRUE に設定されます。詳細については、大きな結果セットをご覧ください。

デフォルト値: TRUE
データ型: Boolean
必須: いいえ

BYOID_AudienceUri

この接続プロパティは、外部アカウント構成ファイル内のオーディエンスプロパティを指定します。audience プロパティには、Workload Identity プールまたは Workforce プールと、そのプール内のプロバイダ ID のリソース名が含まれます。

デフォルト値: なし
データ型: String
必須: OAuthType=4 の場合のみ

BYOID_CredentialSource

この接続プロパティは、トークン取得情報と環境情報を設定します。

デフォルト値: なし
データ型: String
必須: OAuthType=4 の場合のみ

BYOID_PoolUserProject

この接続プロパティは、Workforce プールが使用されているときにユーザープロジェクトを設定します。プロジェクトには serviceusage.services.use IAM 権限が必要です。

デフォルト値: なし
データ型: String
必須: OAuthType=4 を使用し、workforce プールを使用している場合のみ

BYOID_SA_Impersonation_Uri

この接続プロパティは、Workload Identity プールが使用されていて、API が UberMint と統合されていない場合に、サービスアカウントの権限借用の URL を設定します。

デフォルト値: なし
データ型: String
必須: OAuthType=4 で、サービスアカウントの権限借用で Workload Identity プールを使用している場合のみ

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
データ型: String
必須: OAuthType=4 の場合のみ

BYOID_TokenUri

この接続プロパティは、STS トークン交換エンドポイントを設定します。

デフォルト値: https://sts.googleapis.com/v1/token
データ型: String
必須: いいえ

ConnectionPoolSize

この接続プロパティは、接続プーリングが有効になっている場合に接続プールサイズを設定します。

デフォルト値: 10
データ型: Long
必須: いいえ

DefaultDataset

この接続プロパティは、データセットを明示的に指定せずにクエリを実行するときに使用されるデータセットを指定します。DATASET_ID 形式または PROJECT_ID.DATASET_ID 形式のいずれかを使用できます。

デフォルト値: なし
データ型: String
必須: いいえ

EnableHighThroughputAPI

この接続プロパティは、Storage Read API を使用できるかどうかを決定します。Storage Read API を使用するには、HighThroughputActivationRatio と HighThroughputMinTableSize の接続プロパティも満たしている必要があります。

デフォルト値: FALSE
データ型: Boolean
必須: いいえ

EnableSession

この接続プロパティは、接続がセッションを開始するかどうかを決定します。使用すると、セッション ID は後続のすべてのクエリに渡されます。

デフォルト値: FALSE
データ型: Boolean
必須: いいえ

EnableWriteAPI

この接続プロパティは、Storage Write API を使用できるかどうかを決定します。一括挿入を有効にするには、TRUE に設定する必要があります。

デフォルト値: FALSE
データ型: Boolean
必須: いいえ

EndpointOverrides

この接続プロパティは、カンマ区切りの文字列でカスタムエンドポイントを設定します。

をデフォルト値
- BIGQUERY=https://bigquery.googleapis.com
- READ_API=https://bigquerystorage.googleapis.com
- OAUTH2=https://oauth2.googleapis.com
- STS=https://sts.googleapis.com
データ型: String
必須: いいえ

FilterTablesOnDefaultDataset

この接続プロパティは、DatabaseMetaData.getTables() メソッドと DatabaseMetaData.getColumns() メソッドによって返されるメタデータのスコープを制御します。プロパティが無効になっている場合、フィルタリングは行われません。フィルタリングを有効にするには、DefaultDataset 接続プロパティも設定する必要があります。

デフォルト値: FALSE
データ型: Boolean
必須: いいえ

HighThroughputActivationRatio

この接続プロパティは、クエリレスポンスのページ数のしきい値を設定します。この数を超え、EnableHighThroughputAPI と HighThroughputMinTableSize の条件が満たされると、ドライバは Storage Read API の使用を開始します。

デフォルト値: 2
データ型: 整数
必須: いいえ

HighThroughputMinTableSize

この接続プロパティは、クエリレスポンスの行数のしきい値を設定します。この数を超え、EnableHighThroughputAPI と HighThroughputActivationRatio の条件が満たされると、ドライバは Storage Read API の使用を開始します。

デフォルト値: 100
データ型: 整数
必須: いいえ

JobCreationMode

この接続プロパティは、ジョブを作成せずにクエリを実行するかどうかを決定します。1 値は、すべてのクエリに対してジョブが作成されることを意味します。2 値は、ジョブなしでクエリを実行できることを意味します。

デフォルト値: 2
データ型: 整数
必須: いいえ

JobTimeout

この接続プロパティは、ジョブがサーバーでキャンセルされるまでのジョブタイムアウト（秒単位）を設定します。

デフォルト値: 0
データ型: Long
必須: いいえ

KMSKeyName

この接続プロパティは、データを暗号化するための KMS 鍵の名前を設定します。

デフォルト値: なし
データ型: String
必須: いいえ

Labels

この接続プロパティは、クエリに関連付けられたラベルを設定して、クエリジョブを整理およびグループ化します。

デフォルト値: なし
データ型: Map<String, String>
必須: いいえ

LargeResultDataset

この接続プロパティは、クエリ結果の宛先データセットを設定します。詳細については、大きな結果セットをご覧ください。

デフォルト値: _google_jdbc（QueryDialect=BIG_QUERY の場合、または QueryDialect=SQL と LargeResultTable 接続プロパティが設定されている場合のみ）
データ型: String
必須: いいえ

LargeResultsDatasetExpirationTime

この接続プロパティは、データセット内のすべてのテーブルの存続期間をミリ秒単位で指定します。データセットにすでにデフォルトの有効期限が設定されている場合、このプロパティは無視されます。

デフォルト値: 3600000
データ型: Long
必須: いいえ

LargeResultTable

この接続プロパティは、クエリ結果の宛先テーブルを設定します。詳細については、大きな結果セットをご覧ください。

デフォルト値: temp_table...（QueryDialect=BIG_QUERY の場合、または QueryDialect=SQL と LargeResultTable 接続プロパティが設定されている場合のみ）
データ型: String
必須: いいえ

ListenerPoolSize

この接続プロパティは、接続プーリングが有効になっている場合にリスナープールサイズを設定します。

デフォルト値: 10
データ型: Long
必須: いいえ

Location

この接続プロパティは、データセットが作成またはクエリされるロケーションを指定します。この値が設定されていない場合、BigQuery はロケーションを自動的に決定します。

デフォルト値: なし
データ型: String
必須: いいえ

LogLevel

この接続プロパティは、データベースのやり取り中にログに記録される詳細レベルを制御します。レベルの説明については、ロギングをご覧ください。

デフォルト値: 0
データ型: 整数
必須: いいえ

LogPath

この接続プロパティは、ログファイルが書き込まれるディレクトリを設定します。詳細については、ロギングをご覧ください。

デフォルト値: なし
データ型: String
必須: いいえ

MaximumBytesBilled

この接続プロパティは、課金されるバイト数を制限します。この上限を超える課金対象となるバイト数が発生するクエリは失敗し、料金は発生しません。

デフォルト値: 0
データ型: Long
必須: いいえ

MaxResults

この接続プロパティは、ページあたりの結果の最大数を設定します。

デフォルト値: 10000
データ型: Long
必須: いいえ

MetaDataFetchThreadCount

この接続プロパティは、データベースメタデータメソッドに使用されるスレッド数を構成します。

デフォルト値: 32
データ型: 整数
必須: いいえ

OAuthAccessToken

この接続プロパティは、事前生成されたアクセストークン認証に使用されるアクセストークンを指定します。

デフォルト値: なし
データ型: String
必須: AUTH_TYPE=2 の場合

OAuthClientId

この接続プロパティは、事前生成された更新トークン認証とユーザーアカウント認証のクライアント ID を設定します。

デフォルト値: なし
データ型: String
必須: AUTH_TYPE=1 または AUTH_TYPE=2 の場合

OAuthClientSecret

この接続プロパティは、事前生成された更新トークン認証とユーザーアカウント認証のクライアントシークレットを設定します。

デフォルト値: なし
データ型: String
必須: AUTH_TYPE=1 または AUTH_TYPE=2 の場合

OAuthP12Password

この接続プロパティは、PKCS12 鍵ファイルのパスワードを設定します。

デフォルト値: notasecret
データ型: String
必須: いいえ

OAuthPvtKey

この接続プロパティは、サービスアカウント認証を使用するときにサービスアカウントキーを設定します。この値は、未加工の JSON キーファイルオブジェクトまたは JSON キーファイルへのパスにできます。

デフォルト値: なし
データ型: String
必須: AUTH_TYPE=0 と OAuthPvtKeyPath の値が設定されていない場合

OAuthPvtKeyPath

この接続プロパティは、サービスアカウント認証を使用するときにサービスアカウントキーのパスを設定します。

デフォルト値: なし
データ型: String
必須: AUTH_TYPE=0 と OAuthPvtKey、OAuthServiceAcctEmail の値が設定されていない場合

OAuthRefreshToken

この接続プロパティは、事前生成された更新トークン認証の更新トークンを設定します。OAuth 2.0 更新トークンは、現在のアクセストークンの有効期限が切れたときに、ユーザーの再認証を必要とせずにアプリケーションが新しいアクセストークンを取得できるようにする特別なトークンです。

デフォルト値: なし
データ型: String
必須: AUTH_TYPE=2 の場合

OAuthServiceAcctEmail

この接続プロパティは、サービスアカウント認証を使用するときにサービスアカウントのメールアドレスを設定します。

デフォルト値: なし
データ型: String
必須: AUTH_TYPE=0 と OAuthPvtKeyPath の値が設定されていない場合

OAuthType

この接続プロパティは、認証タイプを指定します。値は次のいずれかにする必要があります。

0: Google サービスアカウントの認証
1: Google ユーザーアカウントの認証
2: 事前生成された更新トークンまたはアクセストークンの認証
3: アプリケーションのデフォルト認証情報による認証
4: Workforce Identity 連携や Workload Identity 連携などの外部認証方法
デフォルト値: -1
データ型: 整数
必須: はい

PartnerToken

この接続プロパティは、 Google Cloud パートナーがドライバの使用状況を追跡するために使用します。

デフォルト値: なし
データ型: String
必須: いいえ

PrivateServiceConnectUris

この接続プロパティは EndpointOverrides プロパティと同じです。代わりに EndpointOverrides プロパティを使用してください。

ProjectId

この接続プロパティは、ドライバのデフォルトのプロジェクト ID を設定します。このプロジェクトはクエリの実行に使用され、リソース使用量に対して課金されます。設定されていない場合、ドライバはプロジェクト ID を推測します。

デフォルト値: なし
データ型: String
必須: いいえ（ただし、強く推奨します）

ProxyHost

この接続プロパティは、JDBC 接続がルーティングされるプロキシサーバーのホスト名または IP アドレスを設定します。

デフォルト値: なし
データ型: String
必須: いいえ

ProxyPort

この接続プロパティは、プロキシサーバーが接続をリッスンするポート番号を設定します。

デフォルト値: なし
データ型: String
必須: いいえ

ProxyPwd

この接続プロパティは、プロキシサーバー経由で接続する際に認証が必要な場合に、認証に必要なパスワードを設定します。

デフォルト値: なし
データ型: String
必須: いいえ

ProxyUid

この接続プロパティは、プロキシサーバー経由で接続する際に認証が必要な場合に、認証に必要なユーザー名を設定します。

デフォルト値: なし
データ型: String
必須: いいえ

QueryDialect

この接続プロパティは、クエリ実行の SQL 言語を設定します。GoogleSQL には SQL（強く推奨）、レガシー SQL には BIG_QUERY を使用します。

デフォルト値: SQL
データ型: String
必須: いいえ

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

この接続プロパティは、権限借用チェーン内のサービスアカウントのメールアドレスのカンマ区切りリストを指定します。

デフォルト値: なし
データ型: String
必須: いいえ

ServiceAccountImpersonationEmail

この接続プロパティは、なりすますサービスアカウントのメールアドレスを設定します。

デフォルト値: なし
データ型: String
必須: いいえ

ServiceAccountImpersonationScopes

この接続プロパティは、権限を借用したアカウントで使用する OAuth2 スコープのカンマ区切りリストを指定します。

デフォルト値: https://www.googleapis.com/auth/bigquery
データ型: String
必須: いいえ

ServiceAccountImpersonationTokenLifetime

この接続プロパティは、権限を借用したアカウントのトークンの有効期間（秒単位）を設定します。

デフォルト値: 3600
データ型: 整数
必須: いいえ

SSLTrustStore

この接続プロパティは、信頼できる認証局（CA）証明書を含む Java TrustStore の完全パスを指定します。ドライバはこのトラストストアを使用して、SSL/TLS handshake 中にサーバーの ID を検証します。

デフォルト値: なし
データ型: String
必須: いいえ

SSLTrustStorePwd

この接続プロパティは、SSLTrustStore プロパティで指定された Java TrustStore のパスワードを指定します。

デフォルト値: なし
データ型: String
必須: パスワードで保護された Java TrustStore を使用している場合のみ

SWA_ActivationRowCount

この接続プロパティは、executeBatch insert 行のしきい値を設定します。このしきい値を超えると、コネクタは Storage Write API に切り替わります。

デフォルト値: 3
データ型: 整数
必須: いいえ

SWA_AppendRowCount

この接続プロパティは、書き込みストリームのサイズを設定します。

デフォルト値: 1000
データ型: 整数
必須: いいえ

Timeout

この接続プロパティは、コネクタがタイムアウトする前に失敗した API 呼び出しを再試行する時間の長さ（秒単位）を設定します。

デフォルト値: 0
データ型: Long
必須: いいえ

UniverseDomain

この接続プロパティは、組織の Google Cloud リソースに関連付けられているトップレベルドメインであるユニバースドメインを設定します。

デフォルト値: googleapis.com
データ型: String
必須: いいえ

UnsupportedHTAPIFallback

この接続プロパティは、コネクタが REST API にフォールバックするか（TRUE に設定されている場合）、エラーを返すか（FALSE に設定されている場合）を決定します。

デフォルト値: TRUE
データ型: Boolean
必須: いいえ

UseQueryCache

この接続プロパティにより、クエリキャッシュ保存が有効になります。

デフォルト値: TRUE
データ型: Boolean
必須: いいえ

BigQuery 用の JDBC ドライバを使用する

始める前に

ドライバを構成する

ドライバをインストールする

BigQuery に対する認証

サービス アカウントで認証を行う

Google ユーザー アカウントで認証する

事前に生成されたアクセス トークンまたは更新トークンで認証する

アプリケーションのデフォルト認証情報で認証する

外部メソッドで認証する

接続を確立する

ドライバー向け機能を確認する

SQL コネクタ

データ型マッピング

ネストされたレコードと繰り返しレコード

大規模な結果セット

位置パラメータ

SELECT 件のクエリ

一括挿入

ロギング

接続プロパティ

サービスアカウントで認証を行う

Google ユーザーアカウントで認証する

事前に生成されたアクセストークンまたは更新トークンで認証する

`SELECT` 件のクエリ