Zeilenschlüsselschemas verwalten

Mit strukturierten Zeilenschlüsseln können Sie auf Ihre Bigtable-Daten mit mehrteiligen Schlüsseln zugreifen, ähnlich wie bei zusammengesetzten Schlüsseln in relationalen Datenbanken. Wenn Sie strukturierte Zeilenschlüssel für eine Tabelle definieren, können Sie mit GoogleSQL für Bigtable-Abfragen auf bestimmte Teile der Zeilenschlüssel zugreifen.

Wenn Sie ein Zeilenschlüssel-Schema erstellen, können Sie den Datentyp jedes Segments eines Zeilenschlüssels und die Art der Codierung definieren. Bigtable speichert die Zeilenschlüssel als lexikografisch sortierte Bytefolgen. Das Zeilenschlüsselschema gibt GoogleSQL für Bigtable an, wie diese Bytefolgen decodiert und interpretiert werden.

Die Best Practices für das Entwerfen von Zeilenschlüsseln gelten unabhängig davon, ob Sie strukturierte Zeilenschlüssel verwenden oder nicht. Weitere Informationen finden Sie unter Zeilenschlüssel.

Hier ist ein Beispiel für einen Zeilenschlüssel mit Trennzeichen zwischen den Werten für Gerätetyp, Land, Hersteller-ID und Seriennummer:

`phone#india#pke5preri2eru#8923695`

Im Zeilenschlüsselschema können Sie # als Trennzeichen festlegen und die Zeilenschlüsselsegmente so definieren:

Zeilenschlüssel-Segment Typ Codierung
Gerätetyp (Smartphone) STRING UTF-8
Land (Indien) STRING UTF-8
Hersteller-ID (pke5preri2eru) STRING UTF-8
Seriennummer (8923695) BYTES Roh

Erforderliche Berechtigungen

Welche Berechtigungen Sie benötigen, hängt von der auszuführenden Aktion ab.

Bitten Sie Ihren Administrator, Ihnen eine Rolle für die Tabelle zuzuweisen, die die Berechtigungen enthält:

  • Schema für einen Zeilenschlüssel ansehen: bigtable.tables.get
  • Erstellen Sie ein Schema für Zeilenschlüssel: bigtable.tables.update
  • Schema für Zeilenschlüssel löschen: bigtable.tables.update

Weitere Informationen zum Gewähren des Zugriffs finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Schema für Zeilenschlüssel erstellen

Wenn Sie eine kontinuierliche materialisierte Ansicht erstellen, generiert Bigtable automatisch ein Zeilenschlüsselschema für die Ansicht. Weitere Informationen finden Sie unter Kontinuierliche materialisierte Ansichten.

Wenn Sie ein Zeilenschlüssel-Schema für eine Tabelle definieren möchten, die keine fortlaufend aktualisierte materialisierte Ansicht ist, aktualisieren Sie die Tabelle, indem Sie ein RowKeySchema-Feld hinzufügen, das als Teil der Tabelle gespeichert wird.

gcloud

Wenn Sie ein Zeilenschlüssel-Schema mit der gcloud CLI definieren möchten, verwenden Sie den Befehl gcloud beta bigtable tables update mit einer YAML- oder JSON-Datei, in der das Schema definiert ist.

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

Ersetzen Sie Folgendes:

  • TABLE_ID: Die eindeutige ID der Tabelle, die Sie aktualisieren möchten
  • INSTANCE_ID: die ID der Instanz, in der sich die Tabelle befindet
  • ROW_KEY_SCHEMA_DEFINITION_FILE: Der Pfad zu Ihrer YAML- oder JSON-Datei, in der das Zeilenschlüssel-Schema definiert ist. Beispiele dafür, wie diese Dateien aussehen sollten, finden Sie unter Beispiel-Schemadateien.

Standardmäßig wird die Base64-Codierung auf alle binären Felder in einer YAML- oder JSON-Datei angewendet, z. B. encoding.delimitedBytes.delimiter für das Trennzeichen für Zeilenschlüssel. Das Flag --row-key-schema-pre-encoded-bytes weist Bigtable darauf hin, dass Binärfelder in der Datei codiert sind und nicht noch einmal codiert werden sollten.

Go

Verwenden Sie die Funktion UpdateTableWithRowKeySchema, um ein Zeilenschlüssel-Schema für eine Tabelle zu erstellen.

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

Im folgenden Beispiel wird ein Schema mit dem Namen rks erstellt und der Tabelle hinzugefügt.

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)

Row-Key-Schema löschen

gcloud

Verwenden Sie den Befehl gcloud beta bigtable tables update mit dem Flag --clear-row-key-schema, um das Schema für den Zeilenschlüssel einer Tabelle zu löschen.

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

Ersetzen Sie Folgendes:

  • TABLE_NAME: Der eindeutige Name der Tabelle, aus der Sie das Schema für den Zeilenschlüssel löschen möchten
  • INSTANCE_ID: die ID der Instanz, in der sich die Tabelle befindet

Go

Verwenden Sie die Funktion UpdateTableRemoveRowKeySchema, um das Schema für den Zeilenschlüssel einer Tabelle zu löschen:

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

Zeilenschlüssel-Schema ändern

Sie können ein Zeilenschlüsselschema nicht direkt ändern. Wenn Sie ein Zeilenschlüsselschema ändern möchten, müssen Sie das Schema löschen und ein neues erstellen, das Ihre Änderungen enthält.

Schema für Zeilenschlüssel ansehen

gcloud

Verwenden Sie den Befehl gcloud beta bigtable tables describe, um ein Row-Key-Schema aufzurufen:

  gcloud bigtable tables describe TABLE_NAME \
    --instance=INSTANCE_ID

Ersetzen Sie Folgendes:

  • TABLE_NAME: der eindeutige Name der Tabelle, deren Zeilenschlüssel-Schema Sie aufrufen möchten
  • INSTANCE_ID: die ID der Instanz, in der sich die Tabelle befindet

Die Antwort im Terminal sieht in etwa so aus. Wenn die Tabelle kein Zeilenschlüssel-Schema hat, enthält die Antwort keinen rowKeySchema-Abschnitt.

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

Das Feld RowKeySchema ist Teil des TableInfo-Objekts und wird mit der Methode .TableInfo() abgerufen.

type TableInfo struct {
  ...
  RowKeySchema          *StructType
}

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

Strukturierte Zeilenschlüssel abfragen

Wenn Sie die Spalten in strukturierten Zeilenschlüsseln abfragen möchten, müssen Sie SQL verwenden. Die Methode ReadRows der Bigtable Data API ignoriert ein Zeilenschlüssel-Schema, wenn Daten aus einer Tabelle gelesen werden.

Beispiele für Abfragen, mit denen strukturierte Zeilenschlüssel ausgewählt werden, finden Sie unter Abfragen mit strukturierten Zeilenschlüsseln.

Eine Liste der Bigtable-Clientbibliotheken, die SQL-Abfragen unterstützen, einschließlich Codebeispielen, finden Sie unter SQL mit einer Bigtable-Clientbibliothek verwenden.

Beispielhafte Schemadateien

Wenn Sie ein Zeilenschlüssel-Schema mit der gcloud CLI erstellen, können Sie die strukturierten Zeilenschlüssel entweder mit einer YAML-Datei oder einer JSON-Datei definieren.

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": "#"
    }
  }
}

Nächste Schritte