Mengkueri data protobuf

Dokumen ini memberikan contoh pola kueri umum untuk membaca dan membuat kueri data buffer protokol (protobuf) yang disimpan di Bigtable.

Sebelum membaca halaman ini, pahami hal-hal berikut:

Contoh data

Contoh berikut menggunakan tabel Music yang menyimpan informasi tentang album dan artis. Data disimpan dalam grup kolom bernama album_details, dengan penentu kolom album. Penentu kolom berisi pesan protobuf.

Skema protobuf ditentukan dalam file proto berikut:

  • artist.proto:

    syntax = "proto3";

package package_name;

message Artist {
 string name = 1;
}

  • album.proto:

    syntax = "proto3";

package package_name;

import "artist.proto";

message Album {
 string title = 1;
 Artist artist = 2;
 int32 release_year = 3;
}

Akibatnya, Bigtable membuat paket skema untuk tabel ini yang berisi set deskriptor berikut untuk definisi protobuf ini:

file {
  name: "artist.proto"
  package: "package_name"
  message_type {
    name: "Artist"
    field {
      name: "name"
      number: 1
      label: LABEL_OPTIONAL
      type: TYPE_STRING
      json_name: "name"
    }
  }
  syntax: "proto3"
}
file {
  name: "album.proto"
  package: "package_name"
  dependency: "artist.proto"
  message_type {
    name: "Album"
    field {
      name: "title"
      number: 1
      label: LABEL_OPTIONAL
      type: TYPE_STRING
      json_name: "title"
    }
    field {
      name: "artist"
      number: 2
      label: LABEL_OPTIONAL
      type: TYPE_MESSAGE
      type_name: ".package_name.Artist"
      json_name: "artist"
    }
    field {
      name: "release_year"
      number: 3
      label: LABEL_OPTIONAL
      type: TYPE_INT32
      json_name: "releaseYear"
    }
  }
  syntax: "proto3"
}

Contoh kueri

Contoh berikut menunjukkan cara membuat kueri data protobuf menggunakan GoogleSQL untuk tabel eksternal Bigtable dan BigQuery.

Mentransmisikan kolom ke pesan protobuf

Anda dapat menggunakan operator CAST untuk menafsirkan nilai BYTES sebagai pesan protobuf. Untuk melakukannya, Anda harus memberikan nama lengkap pesan protobuf dalam format berikut: SCHEMA_BUNDLE_ID.FULLY_QUALIFIED_MESSAGE_NAME.

Ganti kode berikut:

  • SCHEMA_BUNDLE_ID: ID unik yang Anda tetapkan ke paket skema saat Anda membuatnya.
  • FULLY_QUALIFIED_MESSAGE_NAME: Nama lengkap pesan, yang harus menyertakan nama paket yang ditentukan dalam file proto Anda–misalnya, package_name.message_name.

Contoh kueri berikut melakukan transmisi kolom album ke pesan protobuf Album. Pesan ini ditentukan dalam paket package_name dan merupakan bagian dari paket skema bernama bundle_name:

SELECT
  CAST(album_details['album'] AS bundle_name.package_name.Album).title
FROM
  Music;

Mengakses kolom bertingkat

Anda dapat mengakses kolom bertingkat dalam pesan protobuf menggunakan notasi titik.

Kueri berikut mengambil nama artis dari pesan Artist bertumpuk dalam pesan Album:

SELECT
  CAST(album_details['album'] AS bundle_name.package_name.Album).artist.name
FROM
  Music;

Memfilter berdasarkan kolom protobuf

Anda dapat menggunakan klausa WHERE untuk memfilter baris berdasarkan nilai kolom dalam pesan protobuf.

Kueri berikut memilih semua album dari artis Dana A.:

SELECT
  *
FROM
  Music
WHERE
  CAST(album_details['album'] AS bundle_name.package_name.Album).artist.name = 'Dana A.';

Menggabungkan kolom protobuf

Anda dapat menggunakan fungsi agregat seperti SUM, AVG, MIN, MAX, dan COUNT pada kolom numerik dalam pesan protobuf Anda.

Kueri berikut menghitung tahun rilis rata-rata semua album dalam tabel:

SELECT
  AVG(CAST(album_details['album'] AS bundle_name.package_name.Album).release_year)
FROM
  Music;

Mengurutkan menurut kolom protobuf

Anda dapat menggunakan klausa ORDER BY untuk mengurutkan set hasil berdasarkan kolom dalam pesan protobuf Anda.

Kueri berikut mengambil semua album dan mengurutkannya berdasarkan tahun rilis dalam urutan menurun:

SELECT
  *
FROM
  Music
ORDER BY
  CAST(album_details['album'] AS bundle_name.package_name.Album).release_year DESC;

Penggunaan dengan tabel eksternal BigQuery

Anda dapat membuat kueri data protobuf yang disimpan di Bigtable dari BigQuery dengan membuat tabel eksternal. Saat membuat tabel eksternal, Anda menentukan jenis kolom sebagai JSON, encoding-nya sebagai PROTO_BINARY, dan mengaitkannya dengan paket skema. Proses ini mengonversi byte pesan protobuf menjadi data JSON yang setara, sehingga Anda dapat membuat kueri kolomnya secara langsung.

Berikut adalah contoh file definisi tabel untuk membuat tabel eksternal BigQuery di atas tabel Music:

{
    "sourceFormat": "BIGTABLE",
    "sourceUris": [
        "https://googleapis.com/bigtable/projects/PROJECT_ID/instances/INSTANCE_ID/tables/Music"
    ],
    "bigtableOptions": {
        "columnFamilies" : [
            {
                "familyId": "album_details",
                "columns": [
                    {
                        "qualifierString": "album",
                        "type": "JSON",
                        "encoding": "PROTO_BINARY",
                        "protoConfig": {
                            "schemaBundleId": "bundle_name",
                            "protoMessageName": "package_name.Album"
                        }
                    }
                ]
            }
        ]
    }
}

Setelah tabel eksternal dibuat, Anda dapat mengkueri data protobuf sebagai kolom JSON di BigQuery.

Kueri berikut mengambil judul semua album yang dirilis pada tahun 2022 dari tabel eksternal BigQuery:

SELECT JSON_VALUE(value, '$.title') AS title
FROM
`PROJECT_ID.DATASET.TABLE_NAME` AS t,
UNNEST(t.album_details.album.cell)
WHERE INT64(JSON_EXTRACT(value, '$.releaseYear')) = 2022;

Langkah berikutnya