Membuat tabel eksternal Bigtable

Halaman ini menjelaskan cara membuat tabel eksternal permanen BigQuery yang dapat digunakan untuk membuat kueri data yang disimpan di Bigtable. Pembuatan kueri data di Bigtable tersedia di semua lokasi Bigtable.

Sebelum memulai

Sebelum membuat tabel eksternal, kumpulkan beberapa informasi dan pastikan Anda memiliki izin untuk membuat tabel tersebut.

Peran yang diperlukan

Untuk membuat tabel eksternal yang akan digunakan untuk membuat kueri data Bigtable, Anda harus menjadi akun utama dalam peran Bigtable Admin (roles/bigtable.admin) untuk instance yang berisi tabel sumber.

Anda juga memerlukan izin BigQuery Identity and Access Management (IAM) bigquery.tables.create.

Setiap peran Identity and Access Management yang telah ditetapkan berikut mencakup izin ini:

  • BigQuery Data Editor (roles/bigquery.dataEditor)
  • BigQuery Data Owner (roles/bigquery.dataOwner)
  • BigQuery Admin (roles/bigquery.admin)

Jika Anda bukan akun utama dI salah satu peran ini, minta administrator untuk memberi Anda akses atau membuat tabel eksternal.

Untuk mengetahui informasi lebih lanjut tentang peran dan izin Identity and Access Management di BigQuery, lihat Peran dan izin yang telah ditetapkan sebelumnya. Untuk melihat informasi tentang izin Bigtable, lihat Kontrol akses dengan Identity and Access Management.

Membuat atau mengidentifikasi set data

Sebelum membuat tabel eksternal, Anda harus membuat set data untuk memuat tabel eksternal. Anda juga dapat menggunakan set data yang sudah ada.

Opsional: Menetapkan atau membuat cluster

Jika Anda berencana untuk sering membuat kueri terhadap data yang sama yang menyalurkan aplikasi produksi, sebaiknya tetapkan sebuah cluster di instance Bigtable Anda yang akan digunakan hanya untuk analisis BigQuery. Tindakan ini mengisolasi traffic dari cluster tersebut atau cluster yang Anda gunakan untuk pembacaan dan penulisan aplikasi. Untuk mempelajari lebih lanjut replikasi dan pembuatan instance yang memiliki lebih dari satu cluster, lihat Tentang replikasi.

Mengidentifikasi atau membuat profil aplikasi

Sebelum membuat tabel eksternal, tentukan profil aplikasi Bigtable yang harus digunakan BigQuery untuk membaca data. Sebaiknya gunakan profil aplikasi yang Anda tetapkan untuk digunakan hanya dengan BigQuery.

Jika Anda memiliki cluster di instance Bigtable yang dikhususkan untuk akses BigQuery, konfigurasikan profil aplikasi untuk menggunakan perutean cluster tunggal ke cluster tersebut.

Untuk mempelajari cara kerja profil aplikasi Bigtable, lihat Tentang profil aplikasi. Untuk mengetahui cara membuat profil aplikasi baru, lihat Membuat dan mengonfigurasi profil aplikasi.

Mengambil URI Bigtable

Untuk membuat tabel eksternal bagi sumber data Bigtable, Anda harus menyediakan URI Bigtable. Untuk mengambil URI Bigtable, lakukan hal berikut:

  1. Buka halaman Bigtable di konsol.

    Buka Bigtable

  2. Ambil detail berikut tentang sumber data Bigtable Anda:

    • Project ID Anda
    • ID instance Bigtable Anda
    • ID profil aplikasi Bigtable yang akan Anda gunakan
    • Nama tabel Bigtable Anda

  3. Buat URI Bigtable menggunakan format berikut, dengan:

    • project_id adalah project yang berisi instance Bigtable Anda
    • instance_id adalah ID instance Bigtable
    • (Opsional) app_profile adalah ID profil aplikasi yang ingin Anda gunakan
    • table_name adalah nama tabel yang Anda minta

    https://googleapis.com/bigtable/projects/project_id/instances/instance_id[/appProfiles/app_profile]/tables/table_name

Membuat tabel eksternal permanen

Saat membuat tabel eksternal permanen di BigQuery yang terhubung ke sumber data Bigtable, ada dua opsi untuk menentukan format tabel eksternal:

  • Jika menggunakan API atau alat command line bq, Anda harus membuat file definisi tabel yang menentukan skema dan metadata untuk tabel eksternal.
  • Jika menggunakan SQL, Anda menggunakan opsi uri dari pernyataan CREATE EXTERNAL TABLE untuk menentukan tabel Bigtable yang akan diambil data, dan opsi bigtable_options untuk menentukan skema tabel.

Data tabel eksternal tidak disimpan di tabel BigQuery. Karena tabel ini bersifat permanen, Anda dapat menggunakan kontrol akses tingkat set data untuk membagikan tabel tersebut kepada orang lain yang juga memiliki akses ke sumber data Bigtable yang mendasarinya.

Untuk membuat tabel permanen, pilih salah satu metode berikut.

SQL

Anda dapat membuat tabel eksternal permanen dengan menjalankan pernyataan DDL CREATE EXTERNAL TABLE. Anda harus menentukan skema tabel secara eksplisit sebagai bagian dari opsi pernyataan.

  1. Di Konsol Google Cloud, buka halaman BigQuery.

    Buka BigQuery

  2. Di editor kueri, masukkan pernyataan berikut:

    CREATE EXTERNAL TABLE DATASET.NEW_TABLE
OPTIONS (
  format = 'CLOUD_BIGTABLE',
  uris = ['URI'],
  bigtable_options = BIGTABLE_OPTIONS );

    Ganti kode berikut:

    • DATASET: set data untuk membuat tabel eksternal Bigtable.
    • NEW_TABLE: nama untuk tabel eksternal Bigtable.
    • URI: URI untuk tabel Bigtable yang ingin Anda gunakan sebagai sumber data. URI ini harus mengikuti format yang dijelaskan dalam Mengambil URI Bigtable.
    • BIGTABLE_OPTIONS: skema untuk tabel Bigtable dalam format JSON. Untuk daftar opsi definisi tabel Bigtable, lihat BigtableOptions dalam referensi REST API.

  3. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

Pernyataan untuk membuat tabel Bigtable eksternal mungkin terlihat mirip dengan berikut ini:

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

Anda dapat membuat tabel di alat command line bq menggunakan perintah bq mk. Saat menggunakan alat command line bq untuk membuat tabel yang terhubung ke sumber data eksternal, Anda mengidentifikasi skema tabel menggunakan file definisi tabel.

  1. Gunakan perintah bq mk untuk membuat tabel permanen.

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

    Ganti kode berikut:

    • DEFINITION_FILE: jalur ke file definisi tabel di mesin lokal Anda.
    • DATASET: nama set data yang berisi tabel.
    • TABLE: nama tabel yang Anda buat.

API

Gunakan tables.insert API, dan buat sebuah ExternalDataConfiguration di resource Table yang Anda teruskan.

Untuk properti sourceUris dalam resource Table, tentukan hanya satu Bigtable URI. Harus berupa URL HTTPS yang valid.

Untuk properti sourceFormat, tentukan "BIGTABLE".

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien. 

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

Membuat kueri tabel eksternal

Untuk mengetahui informasi selengkapnya, lihat Membuat kueri data Bigtable.

Skema yang dihasilkan

Secara default, BigQuery mengekspos nilai dalam grup kolom sebagai array kolom, dan di dalamnya berupa array nilai yang ditulis pada stempel waktu yang berbeda. Skema ini mempertahankan tata letak alami data di Bigtable, tetapi kueri SQL bisa menjadi tantangan tersendiri. Anda dapat mempromosikan kolom ke subkolom dalam grup kolom induk dan hanya membaca nilai terbaru dari setiap sel. Ini mewakili kedua array dalam skema default sebagai nilai skalar.

Contoh

Anda menyimpan profil pengguna untuk jejaring sosial fiktif. Satu model data untuk ini mungkin adalah grup kolom profile dengan masing-masing kolom untuk gender, age, dan email:

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

Dengan menggunakan skema default, kueri GoogleSQL untuk menghitung jumlah pengguna pria di atas 30 tahun adalah:

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)

Kueri data tidak akan terlalu sulit jika gender dan age diekspos sebagai subkolom. Untuk menampilkannya sebagai subkolom, cantumkan gender dan age sebagai kolom bernama dalam grup kolom profile saat menentukan tabel. Anda juga dapat menginstruksikan BigQuery untuk mengekspos nilai terbaru dari kelompok kolom ini karena biasanya, hanya nilai terbaru (dan mungkin satu-satunya nilai) yang menarik.

Setelah mengekspos kolom sebagai subkolom, kueri GoogleSQL untuk menghitung jumlah pengguna laki-laki berusia di atas 30 tahun adalah:

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

Perhatikan cara gender dan age dirujuk langsung sebagai kolom. Konfigurasi JSON untuk penyiapan ini adalah:

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

Encoding nilai

Bigtable menyimpan data sebagai byte mentah, terlepas dari encoding data. Namun, nilai byte hanya dapat digunakan dalam analisis kueri SQL. Bigtable menyediakan dua jenis dasar decoding skalar: teks dan HBase-biner.

Format teks mengasumsikan bahwa semua nilai disimpan sebagai string teks alfanumerik. Misalnya, bilangan bulat 768 akan disimpan sebagai string "768". Encoding biner mengasumsikan bahwa class Bytes.toBytes HBase digunakan untuk mengenkode data dan menerapkan metode decoding yang sesuai.

Region dan zona yang didukung

Pembuatan kueri data di Bigtable tersedia di semua zona Bigtable yang didukung. Anda dapat menemukan daftar zona di sini. Untuk instance multi-cluster, BigQuery merutekan traffic berdasarkan setelan profil aplikasi Bigtable.

Batasan

Untuk informasi tentang batasan yang berlaku untuk tabel eksternal, lihat Batasan tabel eksternal.

Cakupan untuk instance Compute Engine

Saat membuat instance Compute Engine, Anda dapat menentukan daftar cakupan untuk instance tersebut. Cakupan mengontrol akses instance ke produk Google Cloud, termasuk Bigtable. Aplikasi yang berjalan di VM menggunakan akun layanan untuk memanggil Google Cloud API.

Jika Anda menyiapkan instance Compute Engine untuk dijalankan sebagai akun layanan, dan akun layanan tersebut mengakses tabel eksternal yang ditautkan ke sumber data Bigtable, Anda harus menambahkan cakupan akses data hanya baca Bigtable (https://www.googleapis.com/auth/bigtable.data.readonly) ke instance. Untuk informasi selengkapnya, lihat Membuat instance Compute Engine untuk Bigtable.

Untuk mengetahui informasi cara menerapkan cakupan ke instance Compute Engine, lihat Mengubah akun layanan dan cakupan akses untuk instance. Untuk mengetahui informasi selengkapnya tentang akun layanan Compute Engine, lihat Akun layanan.

Langkah berikutnya