建立 Bigtable 外部資料表

本頁面說明如何建立 BigQuery 永久外部資料表，以便查詢儲存在 Bigtable 中的資料。所有 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 資料」。

建立或找出資料集

建立外部資料表前，您必須先建立資料集來存放外部資料表。您也可以使用現有資料集。

規劃運算資源用量

決定查詢資料時要使用的運算類型。您可以在應用程式設定檔設定中，指定要使用 Data Boost 或轉送至專屬叢集。

Data Boost

為避免影響應用程式服務流量，您可以使用 BigQuery 外部資料表讀取 Bigtable 資料，並搭配 Data Boost 無伺服器運算。如要使用 Data Boost，您必須使用 Data Boost 應用程式設定檔，並在編寫 Bigtable URI 時加入應用程式設定檔 ID。詳情請參閱「Bigtable Data Boost 總覽」。

已佈建的節點

如果不使用 Data Boost，系統會使用叢集節點進行運算。

如果不使用 Data Boost，且打算頻繁查詢正式版應用程式使用的相同資料，建議您在 Bigtable 執行個體中指定一個叢集，專門用於 BigQuery 分析。這會將流量與您用於應用程式讀寫作業的叢集區隔開來。如要進一步瞭解複製作業，以及如何建立具有多個叢集的執行個體，請參閱「關於複製作業」。

找出或建立應用程式設定檔

建立外部資料表前，請先決定 BigQuery 應使用哪個 Bigtable 應用程式設定檔讀取資料。建議您使用專為 BigQuery 指定的應用程式設定檔。應用程式設定檔可以是標準應用程式設定檔或 Data Boost 應用程式設定檔，具體取決於您要用於查詢資料的運算類型。

如果 Bigtable 執行個體中有專門用於 BigQuery 存取的叢集，請將應用程式設定檔設為使用單一叢集轉送，轉送至該叢集。

如要使用 Data Boost 無伺服器運算功能，請建立 Data Boost 應用程式設定檔。如要使用叢集節點進行運算，請建立標準應用程式設定檔。如要瞭解 Bigtable 應用程式設定檔的運作方式，請參閱「關於應用程式設定檔」。如要瞭解如何建立新的應用程式設定檔，請參閱「建立及設定應用程式設定檔」。

擷取 Bigtable URI

如要為 Bigtable 資料來源建立外部資料表，您必須提供 Bigtable URI。如要擷取 Bigtable URI，請按照下列步驟操作：

  1. 在控制台中開啟 Bigtable 頁面。

    前往 Bigtable

  2. 擷取 Bigtable 資料來源的下列詳細資料：

    • 您的專案 ID。
    • Bigtable 執行個體 ID。
    • 您要使用的 Bigtable 應用程式設定檔 ID。視您要使用的運算類型而定，這可以是標準應用程式設定檔或 Data Boost 應用程式設定檔。如未指定應用程式設定檔 ID，系統會使用預設應用程式設定檔。
    • Bigtable 資料表的名稱。

  3. 請使用下列格式建立 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

建立永久外部資料表

在 BigQuery 建立永久外部資料表並連結至 Bigtable 資料來源時，您可以透過兩種方式指定外部資料表的格式：

  • 如果您使用的是 API 或 bq 指令列工具，請建立資料表定義檔案，定義外部資料表的結構定義和中繼資料。
  • 如果使用 SQL，請透過 CREATE EXTERNAL TABLE 陳述式的 uri 選項指定要從哪個 Bigtable 資料表提取資料，並使用 bigtable_options 選項指定資料表結構定義。

外部資料表資料不會儲存在 BigQuery 資料表中。由於資料表是永久性的，您可以使用資料集層級的存取控管功能，與其他有權存取基礎 Bigtable 資料來源的使用者共用資料表。

如要建立永久資料表，請選擇下列其中一種方法。

SQL

您可以執行 CREATE EXTERNAL TABLE DDL 陳述式，建立永久外部資料表。您必須在陳述式選項中明確指定資料表結構定義。

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 在查詢編輯器中輸入下列陳述式：

    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：Bigtable 資料表的結構定義，採用 JSON 格式。如需 Bigtable 資料表定義選項清單，請參閱 REST API 參考資料中的 BigtableOptions。

  3. 按一下「 執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

建立外部 Bigtable 資料表的陳述式可能如下所示：

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

bq

您可以使用 bq mk 指令，在 bq 指令列工具中建立資料表。使用 bq 指令列工具建立連結至外部資料來源的資料表時，您可以使用資料表定義檔識別資料表的結構定義。

  1. 使用 bq mk 指令建立永久資料表。

    bq mk \
--external_table_definition=DEFINITION_FILE \
DATASET.TABLE

    更改下列內容：

    • DEFINITION_FILE：本機電腦上的資料表定義檔案路徑。
    • DATASET：資料表所在的資料集名稱。
    • TABLE：要建立的資料表名稱。

API

使用 tables.insert API 方法，並在傳入的 Table 資源中建立 ExternalDataConfiguration。

針對 Table 資源中的 sourceUris 屬性，請僅指定一個 Bigtable URI。必須是有效的 HTTPS 網址。

針對 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 查詢可能較為困難。您可以將資料欄升級為父項資料欄系列中的子欄位，並只讀取每個儲存格的最新值。這會將預設結構定義中的兩個陣列表示為純量值。

範例

您要儲存虛擬社交網路的使用者個人資料。其中一個資料模型可能會是 profile 資料欄系列加上 gender、age 及 email 的個別資料欄：

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

使用預設結構定義，GoogleSQL 查詢會計算 30 歲以上的男性使用者人數：

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 以子欄位的形式呈現，要查詢資料就相對簡單許多。如要以子欄位的形式呈現這些項目，請在定義資料表時將 gender 和 age 列為 profile 資料欄系列中的已命名資料欄。您也可以指示 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 會將資料儲存為原始位元組，與資料編碼無關。不過，位元組值在 SQL 查詢分析中的用途有限。Bigtable 提供兩種基本類型的純量解碼：文字和 HBase-binary。

文字格式假定所有的值都會儲存為英數文字字串。例如，整數 768 會儲存為字串「768」。二進位編碼會假設使用 HBase 的 Bytes.toBytes 類別方法對資料進行編碼，並套用適當的解碼方法。

支援的地區與區域

在 Bigtable 查詢資料的功能適用於所有支援的 Bigtable 可用區。詳情請參閱「BigQuery 位置」。如果是多叢集執行個體，BigQuery 會根據 Bigtable 應用程式設定檔設定轉送流量。

限制

  • 您無法透過 Bigtable SQL 物件 (例如檢視表和持續增補的 materialized view) 建立外部資料表。
  • 如要進一步瞭解外部資料表的限制，請參閱「外部資料表限制」。

Compute Engine 執行個體的範圍

建立 Compute Engine 執行個體時，您可以指定執行個體的範圍清單。範圍會控管執行個體對 Google Cloud產品 (包括 Bigtable) 的存取權。VM 中運作的應用程式會透過服務帳戶呼叫 Google Cloud API。

如果您將 Compute Engine 執行個體設為以服務帳戶身分執行，且該服務帳戶會存取連結至 Bigtable 資料來源的外部資料表，則必須將 Bigtable 唯讀資料存取權範圍 (https://www.googleapis.com/auth/bigtable.data.readonly) 新增至執行個體。詳情請參閱「為 Bigtable 建立 Compute Engine 執行個體」。

如需為 Compute Engine 執行個體套用範圍的相關資訊，請參閱變更執行個體的服務帳戶與存取權範圍一節。如要進一步瞭解 Compute Engine 服務帳戶，請參閱服務帳戶一文。

後續步驟