Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

BigQuery 用の Java Database Connectivity（JDBC）ドライバは、Java アプリケーションを BigQuery に接続します。これにより、任意のツールとインフラストラクチャで BigQuery の機能を使用できます。Java 以外のアプリケーションを BigQuery に接続するには、BigQuery 用の Open Database Connectivity（ODBC）ドライバを使用します。

制限事項

BigQuery 用の JDBC ドライバには、次の制限があります。

このドライバは BigQuery 専用であり、他のプロダクトやサービスでは使用できません。
INTERVAL データ型は、BigQuery Storage Read API ではサポートされていません。
データ操作言語（DML）の制限事項がすべて適用されます。

始める前に

JDBC ドライバ、Apache Maven、java.sql パッケージについて理解しておいてください。
システムが Java Runtime Environment（JRE）8.0 以降で構成されていることを確認します。JRE バージョンを確認する方法については、JRE 環境の確認をご覧ください。

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`
Google ユーザーアカウント	クライアントシークレット	`_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`
その他	外部アカウント構成ファイルの audience プロパティ	`//iam.googleapis.com/projects/my-project/locations/US-EAST1/workloadIdentityPools/my-pool-/providers/my-provider`	`BYOID_AudienceUri`
	トークンの取得と環境情報ファイル	`{\"file\":\"/path/to/file\"}`	`BYOID_CredentialSource`
	ユーザープロジェクト（Workforce プールを使用している場合のみ）	`my_project`	`BYOID_PoolUserProject`
	サービスアカウントの権限借用の URI（Workforce プールを使用している場合のみ）	`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 ドライバをインストールして構成する

BigQuery 用の JDBC ドライバをインストールして構成するには、uber-JAR ファイルを直接ダウンロードするか、Maven を使用します。

直接ダウンロードの設定

直接ダウンロードで JDBC ドライバを構成する手順は次のとおりです。

1.6.0 バージョンのドライバをダウンロードします。
ダウンロードしたファイルを、ソフトウェアで指定された場所にコピーします。

機能の変更とワークフローの更新については、変更履歴をご覧ください。

BigQuery 用 JDBC ドライバの以前のバージョン

Maven の構成

BigQuery 用の JDBC ドライバは Maven Central で入手できます。

JDBC ドライバを使用して開発環境を構成するには、ドライバを依存関係としてプロジェクトに追加します。

Maven

pom.xml ファイルに次の依存関係を追加します。

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

uber-JAR を使用する Maven

pom.xml ファイルに次の依存関係を追加します。

<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>

Gradle

次のコードを build.gradle ファイルに追加します。

dependencies {
// ... other dependencies
implementation("com.google.cloud:google-cloud-bigquery-jdbc:1.6.0")
}

接続を確立する

BigQuery 用の JDBC ドライバを使用して Java アプリケーションと BigQuery の間に接続を確立するには、次の操作を行います。

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;... 形式で指定します。接続プロパティの一覧については、接続プロパティをご覧ください。

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

接続プロパティ	説明	デフォルト値	データの種類	必須
`AdditionalProjects`	`ProjectId` プロパティで設定されたプライマリプロジェクトに加えて、ドライバがクエリとメタデータオペレーションにアクセスできるプロジェクト。	なし	カンマ区切りの文字列	いいえ
`AllowLargeResults`	`QueryDialect` プロパティが `BIG_QUERY` に設定されている場合に、ドライバが 128 MB を超えるクエリ結果を処理するかどうかを決定します。`QueryDialect` プロパティが `SQL` に設定されている場合、ドライバは常に大規模なクエリ結果を処理します。	`TRUE`	ブール値	いいえ
`BYOID_AudienceUri`	外部アカウント構成ファイルの audience プロパティ。audience プロパティには、Workload Identity プールまたは Workforce プールのリソース名と、そのプール内のプロバイダ ID を含めることができます。	なし	文字列	`OAuthType=4` の場合のみ
`BYOID_CredentialSource`	トークンの取得と環境情報。	なし	文字列	`OAuthType=4` の場合のみ
`BYOID_PoolUserProject`	Workforce プールが認証に使用されている場合のユーザープロジェクト。	なし	文字列	`OAuthType=4` で、Workforce プールを使用している場合のみ
`BYOID_SA_Impersonation_Uri`	認証に Workforce プールが使用されている場合のサービスアカウントの権限借用の URI。	なし	文字列	`OAuthType=4` で、Workforce プールを使用している場合のみ
`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`	長い	いいえ
`DefaultDataset`	クエリでデータセットが指定されていない場合に使用されるデータセット。	なし	文字列	いいえ
`EnableGcpLogExporter`	ドライバがログを Cloud Logging に自動的にエクスポートするかどうかを決定します（カスタムまたはグローバルの OpenTelemetry インスタンスが使用されていない場合）。詳細については、OpenTelemetry をご覧ください。	`FALSE`	ブール値	いいえ
`EnableGcpTraceExporter`	ドライバがトレースを Cloud Trace に自動的にエクスポートするかどうかを決定します（カスタムまたはグローバルの OpenTelemetry インスタンスが使用されていない場合）。詳細については、OpenTelemetry をご覧ください。	`FALSE`	ブール値	いいえ
`EnableHighThroughputAPI`	Storage Read API を使用できるかどうかを判断します。Storage Read API を使用するには、`HighThroughputActivationRatio` プロパティと `HighThroughputMinTableSize` プロパティも `TRUE` に設定する必要があります。	`FALSE`	ブール値	いいえ
`EnableProjectDiscovery`	データベースメタデータメソッドが、アクセス可能なすべての Google Cloud プロジェクトでデータセットを検出するかどうかを決定します。`FALSE` に設定すると、検出はデフォルトの `ProjectId` に制限されます。	`FALSE`	ブール値	いいえ
`EnableSession`	接続がセッションを開始するかどうかを決定します。`TRUE` に設定すると、セッション ID は後続のすべてのクエリに渡されます。	`FALSE`	ブール値	いいえ
`EnableTimestampPicos`	ドライバがピコ秒の精度で `TIMESTAMP(12)` 値を取得するかどうかを決定します。`TRUE` に設定すると、`TIMESTAMP(12)` 値は `getString()` メソッドと `getObject()` メソッドによって UTC 形式の `String` オブジェクトとして返されます。`FALSE` に設定すると、`TIMESTAMP(12)` 値は 6 桁のマイクロ秒精度に切り捨てられます。このプロパティは、レガシー SQL（`QueryDialect=BIG_QUERY`）と互換性がありません。	`FALSE`	ブール値	いいえ
`EnableWriteAPI`	Storage Write API（gRPC）を使用できるかどうかを判断します。一括挿入を有効にするには、`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`	ブール値	いいえ
`GcpTelemetryCredentials`	テレメトリーエクスポーターの認証に使用される認証情報。サービスアカウントの JSON キーまたは未加工の JSON 文字列のパスを受け入れます。設定されていない場合は、デフォルトで接続の認証情報になります。詳細については、OpenTelemetry をご覧ください。	なし	文字列	いいえ
`GcpTelemetryProjectId`	テレメトリーの宛先 Google Cloud プロジェクト ID。デフォルトはプライマリ `ProjectId` です。詳細については、OpenTelemetry をご覧ください。	なし	文字列	いいえ
`HighThroughputActivationRatio`	クエリレスポンスのページ数のしきい値。この数を超え、`EnableHighThroughputAPI` と `HighThroughputMinTableSize` の条件が満たされると、ドライバは Storage Read API の使用を開始します。	`2`	Integer	いいえ
`HighThroughputMinTableSize`	クエリレスポンスの行数のしきい値。この数を超え、`EnableHighThroughputAPI` と `HighThroughputActivationRatio` の条件が満たされると、ドライバは Storage Read API の使用を開始します。	`10000`	Integer	いいえ
`JobCreationMode`	クエリをジョブの有無にかかわらず実行するかどうかを決定します。`1` 値は、すべてのクエリに対してジョブが作成されることを意味します。`2` 値は、ジョブなしでクエリを実行できることを意味します。	`2`	Integer	いいえ
`JobTimeout`	ジョブのタイムアウト（秒単位）。この時間を経過すると、サーバーでジョブがキャンセルされます。	`0`	長い	いいえ
`KMSKeyName`	データを暗号化するための KMS 鍵名。	なし	文字列	いいえ
`Labels`	クエリジョブを整理してグループ化するためにクエリに関連付けられているラベル。	なし	Map<String, String>	いいえ
`LargeResultDataset`	大規模なクエリ結果の宛先データセット。`LargeResultTable` プロパティが設定されている場合にのみ使用されます。このプロパティを設定すると、データ書き込みは結果キャッシュをバイパスし、結果が小さくてもクエリごとに課金されます。	`_google_jdbc`	文字列	いいえ
`LargeResultsDatasetExpirationTime`	大規模な結果データセット内のすべてのテーブルの存続期間（ミリ秒）。データセットにデフォルトの有効期限がすでに設定されている場合、このプロパティは無視されます。	`3600000`	長い	いいえ
`LargeResultTable`	大規模なクエリ結果の宛先テーブル。`LargeResultDataset` プロパティが設定されている場合にのみ使用されます。このプロパティを設定すると、データ書き込みは結果キャッシュをバイパスし、結果が小さくてもクエリごとに課金されます。	`temp_table...`	文字列	いいえ
`ListenerPoolSize`	接続プーリングが有効になっている場合のリスナープールのサイズ。	`10`	長い	いいえ
`Location`	データセットが作成またはクエリされるロケーション。このプロパティが設定されていない場合、BigQuery はロケーションを自動的に決定します。	なし	文字列	いいえ
`LogLevel`	ドライバによってログに記録される詳細レベル。詳細については、Logging をご覧ください。	`0`	Integer	いいえ
`LogPath`	ログファイルが書き込まれるディレクトリ。	なし	文字列	いいえ
`MaximumBytesBilled`	課金されるバイト数の上限。課金対象のバイト数がこの数を超えるクエリは失敗し、料金は発生しません。	`0`	長い	いいえ
`MaxResults`	1 ページあたりの結果の最大数。	`10000`	長い	いいえ
`MetaDataFetchThreadCount`	データベースメタデータメソッドに使用されるスレッドの数。	`32`	Integer	いいえ
`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`	Integer	○
`PartnerToken`	Google Cloud パートナーがドライバの使用状況を追跡するために使用するトークン。	なし	文字列	いいえ
`ProjectId`	ドライバのデフォルトのプロジェクト ID。このプロジェクトはクエリの実行に使用され、リソースの使用量に対して課金されます。設定されていない場合、ドライバはプロジェクト ID を推測します。	なし	文字列	×（ただし強く推奨）
`ProxyHost`	JDBC 接続がルーティングされるプロキシサーバーのホスト名または IP アドレス。	なし	文字列	いいえ
`ProxyPort`	プロキシサーバーが接続をリッスンするポート番号。	なし	文字列	いいえ
`ProxyPwd`	認証が必要なプロキシサーバー経由で接続する場合の認証用パスワード。	なし	文字列	いいえ
`ProxyUid`	認証が必要なプロキシサーバー経由で接続する場合の認証用のユーザー名。	なし	文字列	いいえ
`QueryDialect`	クエリ実行用の SQL 言語。GoogleSQL（強く推奨）には `SQL` を、レガシー SQL には `BIG_QUERY` を使用します。	`SQL`	文字列	いいえ
`QueryProperties`	クエリの動作をカスタマイズする REST 接続プロパティ。	なし	Map<String, String>	いいえ
`RequestGoogleDriveScope`	`1` に設定すると、読み取り専用のドライブスコープが接続に追加されます。	`0`	Integer	いいえ
`RetryInitialDelay`	最初の再試行までの遅延（秒単位）を設定します。	`0`	長い	いいえ
`RetryMaxDelay`	再試行の遅延の最大上限（秒単位）を設定します。	`0`	長い	いいえ
`ServiceAccountImpersonationChain`	権限借用チェーン内のサービスアカウントのメールアドレスのカンマ区切りリスト。	なし	文字列	いいえ
`ServiceAccountImpersonationEmail`	権限を借用するサービスアカウントのメールアドレス。	なし	文字列	いいえ
`ServiceAccountImpersonationScopes`	権限を借用したアカウントで使用する OAuth2 スコープのカンマ区切りのリスト。	`https://www.googleapis.com/auth/bigquery`	文字列	いいえ
`ServiceAccountImpersonationTokenLifetime`	権限を借用したアカウントトークンの存続期間（秒単位）。	`3600`	Integer	いいえ
`SSLTrustStore`	信頼できる認証局（CA）証明書を含む Java TrustStore のフルパス。ドライバは、このトラストストアを使用して、SSL/TLS handshake 中にサーバーの ID を検証します。	なし	文字列	いいえ
`SSLTrustStoreProvider`	`SSLTrustStore` プロパティに使用される Java Cryptography Extension（JCE）プロバイダ。	なし	文字列	いいえ
`SSLTrustStorePwd`	`SSLTrustStore` プロパティで指定された Java TrustStore のパスワード。	なし	文字列	Java TrustStore がパスワードで保護されている場合のみ
`SSLTrustStoreType`	`SSLTrustStore` プロパティで指定されたトラストストアファイルの形式（`JKS`、`PKCS12`、`ROTKS` など）。	なし	文字列	いいえ
`SWA_ActivationRowCount`	`executeBatch insert` 行のしきい値。この値を超えると、コネクタは Storage Write API（gRPC）に切り替えます。	`3`	Integer	いいえ
`SWA_AppendRowCount`	書き込みストリームのサイズ。	`1000`	Integer	いいえ
`Timeout`	コネクタが失敗した API 呼び出しを再試行する時間（秒単位）。この時間が経過するとタイムアウトになります。	`0`	長い	いいえ
`UniverseDomain`	組織の Google Cloud リソースに関連付けられているトップレベルドメイン。	`googleapis.com`	文字列	いいえ
`UnsupportedHTAPIFallback`	コネクタが REST API にフォールバックするか（`TRUE` に設定されている場合）、エラーを返すか（`FALSE` に設定されている場合）を決定します。	`TRUE`	ブール値	いいえ
`UseGlobalOpenTelemetry`	ドライバがインストルメンテーションに `GlobalOpenTelemetry.get()` を使用するかどうかを決定します。詳細については、OpenTelemetry をご覧ください。	`FALSE`	ブール値	いいえ
`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 ドライバの問題をトラブルシューティングするには、接続プロパティまたは環境変数を設定してロギングを有効にします。ロギングはパフォーマンスに影響し、ディスク容量を消費する可能性があるため、問題をキャプチャするために一時的にのみ有効にしてください。

ログレベル

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 が有効になっている場合、ドライバは次のオペレーションのスパンを生成します。

クエリの実行: BigQueryStatement（execute()、executeQuery()、executeLargeUpdate()、executeBatch()）と BigQueryPreparedStatement（execute()、executeQuery()、executeLargeUpdate()）のスパンが生成されます。
メタデータオペレーション: 特定の DatabaseMetaData メソッド（getCatalogs()、getSchemas()、getTables()、getColumns()）に対してスパンが生成されます。
ページネーション: 結果の追加ページの非同期フェッチ（REST API パスを使用する場合）は、OpenTelemetry スパンリンクを使用してトレースされ、元のクエリ実行スパンに因果関係でリンクされます。これらのオペレーション用に BigQueryStatement.pagination という名前のスパンが作成されます。
コンテキストの伝播: JDBC ドライバは、アクティブなコンテキストを基盤となる google-cloud-bigquery SDK に伝播します。その結果、SDK によって生成されたスパン（HTTP RPC 呼び出しなど）が JDBC スパンの子として自動的に表示され、完全なエンドツーエンドのトレース階層が提供されます。

構成モード

アプリケーションのアーキテクチャと要件に応じて、次のいずれかのモードを使用して JDBC ドライバで OpenTelemetry を構成できます。

アプリケーション管理のテレメトリー

アプリケーションですでに OpenTelemetry を使用している場合は、OpenTelemetry インスタンスを JDBC ドライバに挿入して、ドライバのテレメトリーがアプリケーションのテレメトリーと関連付けられるようにできます。

これを行うには、BigQueryDataSource API を使用します。

BigQueryDataSource dataSource = new BigQueryDataSource();
// ... set other properties ...
dataSource.setCustomOpenTelemetry(yourOpenTelemetryInstance);

グローバルな OpenTelemetry のサポート

アプリケーションで OpenTelemetry をグローバルに初期化している場合（OpenTelemetry Java Agent を使用するか、GlobalOpenTelemetry.set() 関数を呼び出すなど）、このグローバルインスタンスを使用するようにドライバを構成できます。

グローバルインスタンスを有効にするには、UseGlobalOpenTelemetry 接続プロパティを TRUE に設定します。

ゼロ構成の Google Cloud テレメトリー

Google Cloud で実行していて、迅速な設定が必要な場合は、 Google Cloud オブザーバビリティ（Trace と Logging）へのトレースとログの自動エクスポートを有効にできます。

このエクスポートを有効にするには、JDBC URL で次の接続プロパティを設定します。

EnableGcpTraceExporter=true
EnableGcpLogExporter=true

接続 URL の例を次に示します。

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 インテグレーションをデプロイする際は、ロギングの動作、認証、プロキシ構成、料金に関する次の点を考慮してください。

LogLevel との相互作用

既存の LogLevel 接続プロパティは、ロギングのプライマリゲートキーパーとして機能します。

LogLevel=0（OFF）が設定されている場合、ログレコードは生成されません。そのため、EnableGcpLogExporter=true であっても、OpenTelemetry を使用して、または Logging にログはエクスポートされません。
OTel ロギングを有効にするには、LogLevel が 0 より大きい値に設定されていることを確認します（詳細ログの場合は 5 など）。

テレメトリーの認証

自動Google Cloud フォールバックを使用したテレメトリーエクスポート（トレースとロギングの両方）は、アプリケーションのデフォルト認証情報（ADC）と、GcpTelemetryCredentials を使用して提供される明示的なサービスアカウント認証情報の両方をサポートしています。

GcpTelemetryProjectId または GcpTelemetryCredentials が指定されている場合、ログとトレースの両方が、同じ構成済みの認証情報を使用して、指定された同じ宛先プロジェクトに送信されます。

OpenTelemetry とロギングを使用したプロキシ構成

アプリケーションがプロキシサーバーを介して BigQuery に接続する場合、ドライバは次のようにプロキシルーティングを処理します。

トレースエクスポート（HTTP）。OpenTelemetry トレースエクスポート（otel.exporter.otlp.protocol=http/protobuf）にデフォルトの HTTP プロトコルを使用すると、ドライバは ProxyHost と ProxyPort を使用して、接続プロパティで構成されたプロキシを介してトレースエクスポートトラフィックを自動的にルーティングします。
ログのエクスポートと gRPC テレメトリー。自動 Google Cloud ログエクスポータ（EnableGcpLogExporter=true）と gRPC ベースの OpenTelemetry エクスポータ（otel.exporter.otlp.protocol=grpc）は gRPC を使用します。gRPC は、接続ごとのプロキシ構成をサポートしていません。ログのエクスポートと gRPC テレメトリートラフィックをプロキシサーバー経由でルーティングするには、次のシステムプロパティを使用して JVM レベルでプロキシ設定を構成します。
```
-Dhttps.proxyHost=PROXY_HOST -Dhttps.proxyPort=PROXY_PORT
```

必要な API と IAM 権限

Google Cloud オブザーバビリティにテレメトリーデータを正常に書き込むには、ターゲットの Google Cloud プロジェクトで次の設定を行います。

API を有効にする:
- Cloud Trace API（cloudtrace.googleapis.com）を有効にします。
- Cloud Logging API（logging.googleapis.com）を有効にします。
IAM ロールを付与する:
- トレースをエクスポートする場合: プリンシパルまたはサービスアカウントに Trace エージェント（roles/cloudtrace.agent）ロールを付与します。
- ログのエクスポートの場合: プリンシパルまたはサービスアカウントにログ書き込み（roles/logging.logWriter）ロールを付与します。

料金と課金

ゼロ構成の Google Cloud テレメトリー（EnableGcpTraceExporter=true または EnableGcpLogExporter=true）を使用すると、テレメトリーデータが Trace と Logging に送信されます。これらのサービスでは、取り込まれたデータの量に基づいて料金が発生する場合があります。詳細については、Google Cloud Observability をご覧ください。

指標

この統合は OpenTelemetry 指標をサポートしていません。

依存関係のシェーディング

アプリケーションとのクラスパスの競合を防ぐため、ドライバは OpenTelemetry SDK とエクスポータの依存関係をシェーディングします。OpenTelemetry API は、アプリケーション提供の SDK との相互運用性を確保するために、シェーディングされないままになります。

ロギングとトレースの相関関係

OpenTelemetry が有効になっている場合、ドライバはログをトレースに自動的に関連付けます。

db.connection_id: すべての JDBC スパンにスパン属性としてアタッチされます。
jdbc.connection_id: バゲージキーとして使用され、ドライバから Logging に出力されるすべてのログエントリにラベルとして追加されます。
トレース ID とスパン ID: クエリ実行のスコープ内で生成されたログには、アクティブな trace_id と span_id が自動的に含まれます。

料金

BigQuery 用の JDBC ドライバは無料でダウンロードできます。ただし、ドライバを使用する場合は、標準の BigQuery の料金が適用されます。

次のステップ

その他の設定手順、接続 URL プロパティのリファレンスマニュアル、コードサンプル、ローカルビルドの手順については、GitHub のオープンソースリポジトリをご覧ください。
BigQuery 用の ODBC ドライバの詳細を確認する。
他の BigQuery デベロッパーツールを確認する。