Mengelola skema kunci baris

Kunci baris terstruktur memungkinkan Anda mengakses data Bigtable menggunakan kunci multi-bagian, mirip dengan kunci komposit dalam database relasional. Dengan menentukan kunci baris terstruktur untuk tabel, Anda dapat mengakses bagian tertentu dari kunci baris menggunakan kueri GoogleSQL untuk Bigtable.

Dengan membuat skema kunci baris, Anda dapat menentukan jenis data setiap segmen kunci baris dan cara penyandiannya. Bigtable menyimpan kunci baris sebagai byte yang diurutkan secara leksikografis, dan skema kunci baris memberi tahu GoogleSQL for Bigtable cara mendekode dan menafsirkan byte tersebut.

Praktik terbaik untuk mendesain row key berlaku baik Anda menggunakan row key terstruktur maupun tidak. Untuk mengetahui informasi selengkapnya, lihat Kunci baris.

Pertimbangkan kunci baris contoh berikut, yang memiliki pembatas antara nilai untuk jenis perangkat, negara, ID produsen, dan nomor seri:

`phone#india#pke5preri2eru#8923695`

Dalam skema kunci baris, Anda dapat mengidentifikasi # sebagai pemisah dan menentukan segmen kunci baris sebagai berikut:

Segmen kunci baris Type Encoding
Jenis perangkat (ponsel) STRING UTF-8
Negara (India) STRING UTF-8
ID Produsen (pke5preri2eru) STRING UTF-8
Nomor seri (8923695) BYTES Mentah

Izin yang diperlukan

Izin yang Anda perlukan bergantung pada tindakan yang ingin Anda lakukan.

Untuk mendapatkan izin ini, minta administrator Anda untuk memberi Anda peran pada tabel yang menyertakan izin tersebut:

  • Melihat skema kunci baris: bigtable.tables.get
  • Buat skema kunci baris: bigtable.tables.update
  • Menghapus skema kunci baris: bigtable.tables.update

Untuk mengetahui informasi selengkapnya tentang pemberian akses, lihat Mengelola akses ke project, folder, dan organisasi.

Membuat skema kunci baris

Saat Anda membuat tampilan terwujud berkelanjutan, Bigtable akan otomatis membuat skema kunci baris untuk tampilan tersebut. Untuk mengetahui informasi selengkapnya, lihat Tampilan terwujud berkelanjutan.

Untuk menentukan skema kunci baris untuk tabel yang bukan tampilan terwujud berkelanjutan, Anda memperbarui tabel dengan menambahkan kolom RowKeySchema yang disimpan sebagai bagian dari tabel.

gcloud

Untuk menentukan skema kunci baris menggunakan gcloud CLI, gunakan perintah gcloud beta bigtable tables update dengan file YAML atau JSON yang menentukan skema.

gcloud bigtable beta tables update TABLE_ID \
  --instance=INSTANCE_ID \
  --row-key-schema-definition-file=ROW_KEY_SCHEMA_DEFINITION_FILE \
  --row-key-schema-pre-encoded-bytes

Ganti kode berikut:

  • TABLE_ID: ID unik tabel yang ingin Anda update
  • INSTANCE_ID: ID instance tempat tabel berada
  • ROW_KEY_SCHEMA_DEFINITION_FILE: jalur ke file YAML atau JSON yang menentukan skema kunci baris. Untuk contoh tampilan file tersebut, lihat Example-schema-files.

Secara default, encoding Base64 diterapkan ke semua kolom biner dalam file YAML atau JSON, seperti encoding.delimitedBytes.delimiter untuk pembatas kunci baris. Flag --row-key-schema-pre-encoded-bytes memberi tahu Bigtable bahwa kolom biner dienkode dalam file dan tidak boleh dienkode lagi.

Go

Gunakan fungsi UpdateTableWithRowKeySchema untuk membuat skema kunci baris untuk tabel.

func (ac *AdminClient) UpdateTableWithRowKeySchema(ctx context.Context, tableID
string, rowKeySchema StructType) error

Contoh berikut membuat skema bernama rks dan menambahkannya ke tabel.

rks := StructType{
Fields: []StructField{
    {FieldName: "key1", FieldType: Int64Type{Encoding: Int64OrderedCodeBytesEncoding{}}},
    {FieldName: "key2", FieldType: StringType{Encoding: StringUtf8BytesEncoding{}}},
  },
  Encoding: StructDelimitedBytesEncoding{Delimiter: []byte{'#'}}}

err := c.UpdateTableWithRowKeySchema(context.Background(), "my-table", rks)

Menghapus skema kunci baris

gcloud

Untuk menghapus skema kunci baris tabel, gunakan perintah gcloud beta bigtable tables update dengan tanda --clear-row-key-schema.

  gcloud beta bigtable tables update TABLE_NAME \
    --instance=INSTANCE_ID \
    --clear-row-key-schema

Ganti kode berikut:

  • TABLE_NAME: nama unik tabel yang skema kunci barisnya ingin Anda hapus
  • INSTANCE_ID: ID instance tempat tabel berada

Go

Gunakan fungsi UpdateTableRemoveRowKeySchema untuk menghapus skema kunci baris untuk tabel:

func (ac *AdminClient) UpdateTableRemoveRowKeySchema(ctx context.Context,
tableID string) error

Mengubah skema kunci baris

Anda tidak dapat mengubah skema kunci baris secara langsung. Untuk mengubah skema kunci baris, Anda harus menghapus skema dan membuat skema baru yang menyertakan perubahan Anda.

Melihat skema kunci baris

gcloud

Untuk melihat skema kunci baris, gunakan perintah gcloud beta bigtable tables describe:

  gcloud bigtable tables describe TABLE_NAME \
    --instance=INSTANCE_ID

Ganti kode berikut:

  • TABLE_NAME: nama unik tabel yang skema kunci barisnya ingin Anda lihat
  • INSTANCE_ID: ID instance tempat tabel berada

Respons di terminal mirip dengan berikut ini. Jika tabel tidak memiliki skema kunci baris, respons tidak menyertakan bagian rowKeySchema.

columnFamilies:
  cf: {}
createTime: '2025-05-28T17:25:39.433058Z'
granularity: MILLIS
name: projects/<project>/instances/<instance>/tables/<table>
rowKeySchema:
  encoding:
    delimitedBytes:
      delimiter: Iw==
  fields:
  - fieldName: <field_name_1>
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: <field_name_2>
    type:
      intType:
        encoding:
          bigEndianBytes: {}
  - fieldName: <field_name_3>
    type:
      timestampType:
        encoding:
          unixMicrosInt64: {
              encoding: {
                  orderedCodeBytes: {}
              }
          }
updateTime: '2025-05-28T17:25:39.433058Z'

Go

Kolom RowKeySchema tersedia sebagai bagian dari objek TableInfo, dan Anda mengambilnya menggunakan metode .TableInfo().

type TableInfo struct {
  ...
  RowKeySchema          *StructType
}

func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)

Mengkueri kunci baris terstruktur

Untuk mengkueri kolom dalam kunci baris terstruktur, Anda harus menggunakan SQL. Metode Bigtable Data API ReadRows mengabaikan skema kunci baris saat membaca dari tabel.

Untuk contoh kueri yang memilih kunci baris terstruktur, lihat Kueri kunci baris terstruktur.

Untuk mengetahui daftar library klien Bigtable yang mendukung kueri SQL, termasuk contoh kode, lihat Menggunakan SQL dengan library klien Bigtable.

Contoh file skema

Saat membuat skema kunci baris menggunakan gcloud CLI, Anda dapat menentukan kunci baris terstruktur menggunakan file YAML atau file JSON.

YAML 

fields:
  - field_name: "user_id"
    type:
      bytesType:
        encoding:
          raw: {}
  - fieldBame: "purchase_date"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: "order_number"
    type:
      bytes_type:
        encoding:
          utf8Bytes: {}
encoding:
  delimited_bytes:
    delimiter: "#"

JSON 

{
  "fields": [
    {
      "fieldName": "user_id",
      "type": {
        "bytesType": {
          "encoding": {
            "raw": {}
          }
        }
      }
    },
    {
      "fieldName": "purchase_date",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    },
    {
      "fieldName": "order_number",
      "type": {
        "bytesType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    }
  ],
  "encoding": {
    "delimitedBytes": {
      "delimiter": "#"
    }
  }
}

Langkah berikutnya