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

BigQuery 用の Java Database Connectivity（JDBC）ドライバは、Java アプリケーションを BigQuery に接続し、任意のツールとインフラストラクチャで BigQuery の機能を使用できるようにします。Java 以外のアプリケーションを BigQuery に接続するには、BigQuery 用の 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 ドライバとの接続を確立するときに使用します。メモする必要があるのは、使用する認証方法に対応する情報のみです。

   認証方法	認証情報	例	接続プロパティ（後で設定）
   標準サービス アカウント	サービス アカウントのメールアドレス	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
   	クライアント シークレット	_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
   	ユーザー プロジェクト（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

開発環境を構成します

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

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

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

dependencies {
// ... other dependencies
implementation("com.google.cloud:google-cloud-bigquery-jdbc:0.3.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（省略可）: property_1=value_1; property_2=value_2;... 形式で指定された JDBC ドライバの追加の接続プロパティ。接続プロパティの完全なリストについては、接続プロパティをご覧ください。

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 ドライバでサポートされています。

ドライバを使用してクエリを実行する

JDBC ドライバを介して BigQuery に接続された Java アプリケーションを使用して、標準の 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());

ドライバは、ベースレコードを構造体オブジェクトまたは 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

料金

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

次のステップ

• BigQuery 用の ODBC ドライバの詳細を確認する。
• 他の BigQuery デベロッパー ツールを確認する。