このページは Cloud Translation API によって翻訳されました。

Bigtable の外部テーブルを作成する

このページでは、Bigtable に保存されているデータのクエリに使用できる BigQuery の外部の永続テーブルを作成する方法について説明します。Bigtable のデータのクエリは、すべての Bigtable のロケーションで使用できます。

始める前に

外部テーブルを作成する前に、情報を収集して、テーブルの作成権限があることを確認します。

必要なロール

Bigtable データのクエリに使用する外部テーブルを作成するには、ソーステーブルを含むインスタンスの Bigtable 管理者（roles/bigtable.admin）ロールのプリンシパルである必要があります。

また、bigquery.tables.create BigQuery Identity and Access Management（IAM）権限も必要です。

この権限は、次のそれぞれの事前定義 Identity and Access Management ロールに含まれています。

BigQuery データ編集者（roles/bigquery.dataEditor）
BigQuery データオーナー（roles/bigquery.dataOwner）
BigQuery 管理者（roles/bigquery.admin）

これらのロールのいずれでもプリンシパルでない場合は、アクセス権の付与または外部テーブルの作成を管理者に依頼してください。

BigQuery での Identity and Access Management のロールと権限の詳細については、事前定義ロールと権限をご覧ください。Bigtable の権限の詳細については、Identity and Access Management によるアクセス制御をご覧ください。

データセットを作成または特定する

外部テーブルを作成する前に、その外部テーブルを含むデータセットを作成する必要があります。既存のデータセットを使用することもできます。

省略可: クラスタを指定または作成する

本番環境のアプリケーション用と同じデータを頻繁にクエリする場合は、Bigtable インスタンスのクラスタを BigQuery 分析専用に指定することをおすすめします。これにより、トラフィックの読み取りと書き込みに使用するクラスタからトラフィックが分離されます。レプリケーションと、複数のクラスタを持つインスタンスの作成の詳細については、レプリケーションについてをご覧ください。

アプリプロファイルを特定または作成する

外部テーブルを作成する前に、BigQuery がデータの読み取りに使用する Bigtable アプリプロファイルを決めます。BigQuery 専用で使用するように指定したアプリプロファイルを使用することをおすすめします。

Bigtable インスタンスに BigQuery アクセス専用のクラスタがある場合は、そのクラスタへの単一クラスタルーティングを使用するようにアプリプロファイルを構成します。

Bigtable アプリプロファイルの仕組みについては、アプリプロファイルについてをご覧ください。新しいアプリプロファイルの作成方法については、アプリプロファイルの作成と構成をご覧ください。

Bigtable URI を取得する

Bigtable データソースの外部テーブルを作成するには、Bigtable URI が必要です。Bigtable URI を取得する手順は次のとおりです。

コンソールで [Bigtable] ページを開きます。

Bigtable に移動
Bigtable データソースについて次の詳細を取得します。
- プロジェクト ID
- Bigtable インスタンス ID
- 使用する予定の Bigtable アプリプロファイルの ID
- Bigtable テーブルの名前
次の形式で Bigtable URI を作成します。
- project_id は Bigtable インスタンスを含むプロジェクトです。
- instance_id は Bigtable インスタンス ID です。
- （省略可）app_profile は、使用するアプリプロファイル ID です。
- table_name はクエリ対象のテーブルの名前です。
https://googleapis.com/bigtable/projects/project_id/instances/instance_id[/appProfiles/app_profile]/tables/table_name

外部の永続テーブルを作成する

Bigtable データソースにリンクされる外部の永続テーブルを BigQuery で作成する場合、外部テーブルの形式の指定についてはオプションが 2 つあります。

API か bq コマンドラインツールを使用している場合は、外部テーブルのスキーマとメタデータを定義するテーブル定義ファイルを作成します。
SQL を使用する場合は、CREATE EXTERNAL TABLE ステートメントの uri オプションを使用してデータを取得する Bigtable テーブルを指定し、bigtable_options オプションを使用して、テーブルスキーマを指定します。

外部テーブルデータは BigQuery テーブルに保存されません。テーブルが永続的であるため、データセットレベルのアクセス制御を使用すると、基礎となる Bigtable データソースへのアクセスが可能な他のユーザーとテーブルを共有できます。

永続テーブルを作成するには、次のいずれかの方法を選択します。

SQL

永続外部テーブルを作成するには、CREATE EXTERNAL TABLE DDL ステートメントを実行します。テーブルスキーマは、ステートメントオプションの一部として明示的に指定する必要があります。

Google Cloud コンソールで [BigQuery] ページに移動します。

BigQuery に移動
クエリエディタで次のステートメントを入力します。
```
CREATE EXTERNAL TABLE DATASET.NEW_TABLE
OPTIONS (
  format = 'CLOUD_BIGTABLE',
  uris = ['URI'],
  bigtable_options = BIGTABLE_OPTIONS );
```
次のように置き換えます。
- DATASET: Bigtable 外部テーブルを作成するデータセット。
- NEW_TABLE: Bigtable 外部テーブルの名前。
- URI: データソースとして使用する Bigtable テーブルの URI。この URI は、Bigtable URI の取得で説明されている形式に従う必要があります。
- BIGTABLE_OPTIONS: JSON 形式の Bigtable テーブルのスキーマ。Bigtable テーブル定義オプションの一覧については、REST API リファレンスの BigtableOptions をご覧ください。
[ 実行] をクリックします。

クエリの実行方法については、インタラクティブクエリを実行するをご覧ください。

外部 Bigtable テーブルを作成するステートメントは次のようになります。

CREATE EXTERNAL TABLE mydataset.BigtableTable
OPTIONS (
  format = 'CLOUD_BIGTABLE',
  uris = ['https://googleapis.com/bigtable/projects/myproject/instances/myBigtableInstance/tables/table1'],
  bigtable_options =
    """
    {
      columnFamilies: [
        {
          "familyId": "familyId1",
          "type": "INTEGER",
          "encoding": "BINARY"
        }
      ],
      readRowkeyAsString: true
    }
    """
);

bq

bq mk コマンドを使用して bq コマンドラインツールでテーブルを作成します。外部データソースにリンクされるテーブルを bq コマンドラインツールを使用して作成する場合は、テーブル定義ファイルを使用してテーブルのスキーマを指定します。

永続テーブルの作成には、bq mk コマンドを使用します。
```
bq mk \
--external_table_definition=DEFINITION_FILE \
DATASET.TABLE
```
以下を置き換えます。
- DEFINITION_FILE: ローカルマシン上のテーブル定義ファイルへのパス。
- DATASET: テーブルを含むデータセットの名前。
- TABLE: 作成するテーブルの名前。

API

tables.insert API メソッドを呼び出して、渡す Tableリソースに ExternalDataConfiguration を作成します。

Table リソースの sourceUris プロパティには、1 つの Bigtable URI のみを指定します。有効な HTTPS URL を指定する必要があります。

sourceFormat プロパティに、"BIGTABLE" を指定します。

Java

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンスドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証情報を設定するをご覧ください。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.BigtableColumn;
import com.google.cloud.bigquery.BigtableColumnFamily;
import com.google.cloud.bigquery.BigtableOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;
import com.google.cloud.bigquery.TableResult;
import com.google.common.collect.ImmutableList;
import org.apache.commons.codec.binary.Base64;

// Sample to queries an external bigtable data source using a permanent table
public class QueryExternalBigtablePerm {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String bigtableInstanceId = "MY_INSTANCE_ID";
    String bigtableTableName = "MY_BIGTABLE_NAME";
    String bigqueryDatasetName = "MY_DATASET_NAME";
    String bigqueryTableName = "MY_TABLE_NAME";
    String sourceUri =
        String.format(
            "https://googleapis.com/bigtable/projects/%s/instances/%s/tables/%s",
            projectId, bigtableInstanceId, bigtableTableName);
    String query = String.format("SELECT * FROM %s ", bigqueryTableName);
    queryExternalBigtablePerm(bigqueryDatasetName, bigqueryTableName, sourceUri, query);
  }

  public static void queryExternalBigtablePerm(
      String datasetName, String tableName, String sourceUri, String query) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      BigtableColumnFamily.Builder statsSummary = BigtableColumnFamily.newBuilder();

      // Configuring Columns
      BigtableColumn connectedCell =
          BigtableColumn.newBuilder()
              .setQualifierEncoded(Base64.encodeBase64String("connected_cell".getBytes()))
              .setFieldName("connected_cell")
              .setType("STRING")
              .setEncoding("TEXT")
              .build();
      BigtableColumn connectedWifi =
          BigtableColumn.newBuilder()
              .setQualifierEncoded(Base64.encodeBase64String("connected_wifi".getBytes()))
              .setFieldName("connected_wifi")
              .setType("STRING")
              .setEncoding("TEXT")
              .build();
      BigtableColumn osBuild =
          BigtableColumn.newBuilder()
              .setQualifierEncoded(Base64.encodeBase64String("os_build".getBytes()))
              .setFieldName("os_build")
              .setType("STRING")
              .setEncoding("TEXT")
              .build();

      // Configuring column family and columns
      statsSummary
          .setColumns(ImmutableList.of(connectedCell, connectedWifi, osBuild))
          .setFamilyID("stats_summary")
          .setOnlyReadLatest(true)
          .setEncoding("TEXT")
          .setType("STRING")
          .build();

      // Configuring BigtableOptions is optional.
      BigtableOptions options =
          BigtableOptions.newBuilder()
              .setIgnoreUnspecifiedColumnFamilies(true)
              .setReadRowkeyAsString(true)
              .setColumnFamilies(ImmutableList.of(statsSummary.build()))
              .build();

      TableId tableId = TableId.of(datasetName, tableName);
      // Create a permanent table linked to the Bigtable table
      ExternalTableDefinition externalTable =
          ExternalTableDefinition.newBuilder(sourceUri, options).build();
      bigquery.create(TableInfo.of(tableId, externalTable));

      // Example query
      TableResult results = bigquery.query(QueryJobConfiguration.of(query));

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));

      System.out.println("Query on external permanent table performed successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

外部テーブルに対してクエリを行う

詳細については、Bigtable データにクエリを実行するをご覧ください。

生成されたスキーマ

BigQuery はデフォルトで、列ファミリーの値を列の配列として公開します。値の配列は異なるタイムスタンプで書き込まれます。このスキーマにより、Bigtable ではデータが未加工のレイアウトで維持されますが、SQL クエリでは操作が難しくなる場合があります。親の列ファミリー内で列がサブフィールドになる場合や、各セルから最新の値だけが読み取られる場合があります。これにより、デフォルトスキーマでは、両方の配列がスカラー値として扱われます。

例

架空のソーシャルネットワークにユーザープロフィールを保存しています。このデータモデルの 1 つは profile 列ファミリーで、gender、age、email という列が個別に存在します。

rowkey | profile:gender| profile:age| profile:email
-------| --------------| -----------| -------------
alice  | female        | 30         | alice@gmail.com

デフォルトのスキーマを使用する場合、30 歳を超えている男性ユーザーの数を確認する GoogleSQL クエリは次のようになります。

SELECT
  COUNT(1)
FROM
  `dataset.table`
OMIT
  RECORD IF NOT SOME(profile.column.name = "gender"
    AND profile.column.cell.value = "male")
  OR NOT SOME(profile.column.name = "age"
    AND INTEGER(profile.column.cell.value) > 30)

gender と age がサブフィールドとして公開されていれば、クエリはそれほど難しいものではありません。これらをサブフィールドとして公開するには、テーブルを定義するときに、profile 列ファミリーで gender と age を名前付きの列として設定します。また、この列ファミリーから最新の値を公開するように BigQuery に指示することもできます。通常は、最新の値（場合によっては唯一の値）だけが注目されるためです。

列をサブフィールドとして公開すると、30 歳を超える男性ユーザー数を確認する GoogleSQL クエリは次のようになります。

SELECT
  COUNT(1)
FROM
  `dataset.table`
WHERE
  profile.gender.cell.value="male"
  AND profile.age.cell.value > 30

gender と age はフィールドとして直接参照されています。この設定の JSON 構成は次のとおりです。

  "bigtableOptions": {
    "readRowkeyAsString": "true",
    "columnFamilies": [
      {
          "familyId": "profile",
          "onlyReadLatest": "true",
          "columns": [
              {
                  "qualifierString": "gender",
                  "type": "STRING"
              },
              {
                  "qualifierString": "age",
                  "type": "INTEGER"
              }
          ]
      }
    ]
  }

値のエンコード

Bigtable はデータを RAW バイトとして保存し、データのエンコードに依存しません。ただし、SQL クエリ分析でバイト値を使用する場合に制限があります。Bigtable には、2 種類の基本的なスカラーデコード（テキストと HBase バイナリ）があります。

テキスト形式は、すべての値が英数字のテキスト文字列で保存されていることを前提としています。たとえば、整数 768 は文字列 "768" として保存されます。バイナリエンコードでは、データのエンコードに HBase の Bytes.toBytes メソッド群が使用されたと想定し、適切なデコード方法が適用されます。

サポート対象リージョンとゾーン

Bigtable のデータのクエリは、サポートされているすべての Bigtable ゾーンで使用できます。ゾーンのリストについては、こちらをご覧ください。マルチクラスタインスタンスの場合、BigQuery は Bigtable のアプリプロファイルの設定に基づいてトラフィックをルーティングします。

制限事項

外部テーブルに適用される制限事項については、外部テーブルの制限事項をご覧ください。

Compute Engine インスタンスのスコープ

Compute Engine インスタンスを作成するときに、インスタンスに対するスコープのリストを指定できます。このスコープは、Bigtable を含む、Google Cloud プロダクトに対するインスタンスのアクセスを制御します。VM 上で実行されるアプリケーションは、サービスアカウントを使用して Google Cloud API を呼び出します。

サービスアカウントとして実行するように Compute Engine インスタンスをセットアップした場合、Bigtable データソースにリンクされた外部テーブルにこのサービスアカウントからアクセスするには、Bigtable 読み取り専用データアクセススコープ（https://www.googleapis.com/auth/bigtable.data.readonly）をインスタンスに追加する必要があります。詳細については、Bigtable 用の Compute Engine インスタンスの作成をご覧ください。

Compute Engine インスタンスへのスコープの適用方法については、インスタンスのサービスアカウントとアクセススコープを変更するをご覧ください。Compute Engine サービスアカウントの詳細については、サービスアカウントをご覧ください。