Zeilenschlüsselschemas verwalten

Mit strukturierten Zeilenschlüsseln können Sie mit mehrteiligen Schlüsseln auf Ihre Bigtable-Daten zugreifen, ähnlich wie mit 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.

Durch das Erstellen eines Zeilenschlüsselschemas können Sie den Datentyp jedes Segments von einem Zeilenschlüssel und dessen Codierung definieren. Bigtable speichert die Zeilenschlüssel als lexikografisch sortierte Byte. Das Zeilenschlüsselschema teilt GoogleSQL für Bigtable mit, wie diese Byte 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 Zeilen schlüssel.

Betrachten Sie den folgenden Beispiel-Zeilenschlüssel, der Trennzeichen zwischen den Werten für Gerätetyp, Land, Hersteller-ID und Seriennummer enthält:

`phone#india#pke5preri2eru#8923695`

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

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

Erforderliche Berechtigungen

Die erforderlichen Berechtigungen hängen von der Aktion ab, die Sie ausführen möchten.

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

  • Zeilenschlüsselschema ansehen: bigtable.tables.get
  • Zeilenschlüsselschema erstellen: bigtable.tables.update
  • Zeilenschlüsselschema löschen: bigtable.tables.update

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

Zeilenschlüsselschema erstellen

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

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

gcloud

Verwenden Sie den gcloud beta bigtable tables update Befehl mit einer YAML- oder JSON-Datei, die das Schema definiert, um ein Zeilenschlüsselschema mit der gcloud CLI zu definieren.

gcloud beta bigtable 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, die das Zeilenschlüsselschema definiert. Beispiele für das Aussehen dieser Dateien finden Sie unter Beispieldateien für Schemas.

Standardmäßig wird die Base64-Codierung auf alle Binärfelder in einer YAML- oder JSON-Datei angewendet, z. B. encoding.delimitedBytes.delimiter für das Trennzeichen des Zeilenschlüssels. Das Flag --row-key-schema-pre-encoded-bytes teilt Bigtable mit, dass Binärfelder in der Datei codiert sind und nicht noch einmal codiert werden müssen.

Go

Verwenden Sie die Funktion UpdateTableWithRowKeySchema, um ein Zeilenschlüsselschema 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)

Zeilenschlüsselschema löschen

gcloud

Verwenden Sie den gcloud beta bigtable tables update Befehl mit dem --clear-row-key-schema Flag, um das Zeilenschlüsselschema 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 Zeilenschlüsselschema löschen möchten
  • INSTANCE_ID: die ID der Instanz, in der sich die Tabelle befindet

Go

Verwenden Sie die Funktion UpdateTableRemoveRowKeySchema, um das Zeilenschlüsselschema für eine Tabelle zu löschen:

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

Zeilenschlüsselschema ä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.

Zeilenschlüsselschema ansehen

gcloud

Verwenden Sie den gcloud beta bigtable tables describe Befehl, um ein Zeilenschlüsselschema anzusehen:

  gcloud bigtable tables describe TABLE_NAME \
    --instance=INSTANCE_ID

Ersetzen Sie Folgendes:

  • TABLE_NAME: der eindeutige Name der Tabelle deren Zeilenschlüsselschema Sie ansehen 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üsselschema hat, enthält die Antwort keinen Abschnitt 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

Das Feld RowKeySchema ist Teil des Objekts TableInfo 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 Bigtable Data API-Methode ReadRows ignoriert ein Zeilenschlüsselschema, wenn sie Daten aus einer Tabelle liest.

Beispiele für Abfragen, die strukturierte Zeilenschlüssel auswählen, 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.

Beispieldateien für Schemas

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

YAML 

fields:
  - fieldName: "user_id"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: "purchase_date"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: "order_number"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
encoding:
  delimitedBytes:
    delimiter: "Iw=="

JSON 

{
  "fields": [
    {
      "fieldName": "user_id",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    },
    {
      "fieldName": "purchase_date",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    },
    {
      "fieldName": "order_number",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    }
  ],
  "encoding": {
    "delimitedBytes": {
      "delimiter": "Iw=="
    }
  }
}

Nächste Schritte