Gérer les schémas de clé de ligne

Les clés de ligne structurées vous permettent d'accéder à vos données Bigtable à l'aide de clés en plusieurs parties, semblables aux clés composites des bases de données relationnelles. Définir des clés de ligne structurées pour une table vous permet d'accéder à des parties spécifiques des clés de ligne à l'aide de requêtes GoogleSQL pour Bigtable.

En créant un schéma de clé de ligne, vous pouvez définir le type de données de chaque segment de une clé de ligne et la façon dont il est encodé. Bigtable stocke les clés de ligne sous forme d'octets triés de façon lexicographique, et le schéma de clé de ligne indique à GoogleSQL pour Bigtable comment décoder et interpréter ces octets.

Les bonnes pratiques pour la conception de clés de ligne s'appliquent que vous utilisiez ou non des clés de ligne structurées. Pour en savoir plus, consultez la section Clés de ligne.

Prenons l'exemple de la clé de ligne suivante, qui comporte des délimiteurs entre les valeurs du type d'appareil, du pays, de l'ID du fabricant et du numéro de série :

`phone#india#pke5preri2eru#8923695`

Dans le schéma de clé de ligne, vous pouvez identifier # comme délimiteur et définir les segments de clé de ligne comme suit :

Segment de clé de ligne Type Encodage
Type d'appareil (téléphone) STRING UTF-8
Pays (Inde) STRING UTF-8
ID du fabricant (pke5preri2eru) STRING UTF-8
Numéro de série (8923695) BYTES Brut

Autorisations requises

Les autorisations dont vous avez besoin dépendent de l'action que vous souhaitez effectuer.

Pour obtenir ces autorisations, demandez à votre administrateur de vous attribuer un rôle sur la table qui inclut les autorisations suivantes :

  • Afficher un schéma de clé de ligne : bigtable.tables.get
  • Créer un schéma de clé de ligne : bigtable.tables.update
  • Supprimer un schéma de clé de ligne : bigtable.tables.update

Pour en savoir plus sur l'attribution d'accès, consultez Gérer l'accès aux projets, dossiers et aux organisations.

Créer un schéma de clé de ligne

Lorsque vous créez une vue matérialisée continue, Bigtable crée automatiquement un schéma de clé de ligne pour la vue. Pour en savoir plus, consultez la section Vues matérialisées continues.

Pour définir un schéma de clé de ligne pour une table qui n'est pas une vue matérialisée continue, mettez à jour la table en ajoutant un champ RowKeySchema stocké dans la table.

Console

Pour définir un schéma de clé de ligne à l'aide de la Google Cloud console, procédez comme suit :

  1. Dans la Google Cloud console, ouvrez la page Instances Bigtable.

    Accéder à la liste des instances

  2. Sélectionnez une instance dans la liste.

  3. Dans le menu de navigation, cliquez sur Bigtable Studio.

    Le volet Explorateur affiche une liste des tables, des vues et des requêtes de l'instance.

  4. Dans la liste Tables, pour la table dans laquelle vous souhaitez créer un schéma de clé de ligne, cliquez sur le menu Afficher les actions, puis sur Créer un schéma de clé de ligne.

    L'onglet Schéma de clé de ligne s'ouvre.

  5. Dans la liste Encodage, sélectionnez un type d'encodage pour votre schéma de clé de ligne.

  6. Si vous avez sélectionné DelimitedBytes, dans le champ Délimiteur, saisissez un délimiteur qui sépare les segments de vos clés de ligne existantes. La valeur par défaut est un symbole dièse (#).

  7. Dans le champ Segment, saisissez un nom pour le segment, par exemple device_type.

  8. Dans la liste Type, sélectionnez le type de données du segment de clé de ligne.

  9. Selon le type de données sélectionné, dans la liste Encodage d'octets, conservez le type d'encodage par défaut du segment de clé de ligne ou modifiez-le.

  10. (Facultatif) Si votre segment de clé de ligne comporte plusieurs parties, cliquez sur Ajouter un segment de clé de ligne pour ajouter des champs supplémentaires.

  11. Cliquez sur Enregistrer.

gcloud

Pour définir un schéma de clé de ligne à l'aide de gcloud CLI, utilisez la gcloud beta bigtable tables update commande avec un fichier YAML ou JSON qui définit le schéma.

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

Remplacez les éléments suivants :

  • TABLE_ID : ID unique de la table que vous souhaitez mettre à jour
  • INSTANCE_ID : ID de l'instance dans laquelle se trouve la table
  • ROW_KEY_SCHEMA_DEFINITION_FILE : chemin d'accès à votre fichier YAML ou JSON qui définit le schéma de clé de ligne. Pour obtenir des exemples de l'apparence de ces fichiers, consultez la section Exemples de fichiers de schéma.

Par défaut, l'encodage Base64 est appliqué à tous les champs binaires d'un fichier YAML ou JSON, tels que encoding.delimitedBytes.delimiter pour le délimiteur de clé de ligne. L'option --row-key-schema-pre-encoded-bytes indique à Bigtable que les champs binaires sont encodés dans le fichier et ne doivent pas être encodés à nouveau.

Go

Utilisez la fonction UpdateTableWithRowKeySchema pour créer un schéma de clé de ligne pour une table.

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

L'exemple suivant crée un schéma appelé rks et l'ajoute à la table.

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)

Supprimer un schéma de clé de ligne

Console

Pour supprimer le schéma de clé de ligne d'une table à l'aide de la Google Cloud console, procédez comme suit :

  1. Dans la Google Cloud console, ouvrez la page Instances Bigtable.

    Accéder à la liste des instances

  2. Sélectionnez une instance dans la liste.

  3. Dans le menu de navigation, cliquez sur Bigtable Studio.

    Le volet Explorateur affiche une liste des tables, des vues et des requêtes de l'instance.

  4. Dans la liste des tables, cliquez sur la table contenant le schéma de clé de ligne que vous souhaitez supprimer.

  5. Cliquez sur le menu Afficher les actions pour le schéma de clé de ligne que vous souhaitez supprimer.

  6. Cliquez sur Supprimer.

gcloud

Pour supprimer le schéma de clé de ligne d'une table, utilisez la gcloud beta bigtable tables update commande avec l'--clear-row-key-schema option.

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

Remplacez les éléments suivants :

  • TABLE_NAME : nom unique de la table à partir de laquelle vous souhaitez supprimer le schéma de clé de ligne
  • INSTANCE_ID : ID de l'instance dans laquelle se trouve la table

Go

Utilisez la fonction UpdateTableRemoveRowKeySchema pour effacer le schéma de clé de ligne d'une table :

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

Modifier un schéma de clé de ligne

Vous ne pouvez pas modifier directement un schéma de clé de ligne. Pour modifier un schéma de clé de ligne, vous devez le supprimer et en créer un autre qui inclut vos modifications.

Afficher un schéma de clé de ligne

Console

Pour afficher le schéma de clé de ligne d'une table à l'aide de la Google Cloud console, procédez comme suit :

  1. Dans la Google Cloud console, ouvrez la page Instances Bigtable.

    Accéder à la liste des instances

  2. Cliquez sur l'instance dont vous souhaitez afficher le schéma de clé de ligne de la table.

  3. Dans le menu de navigation, cliquez sur Bigtable Studio.

    Le volet Explorateur affiche une liste des tables, des vues et des requêtes de l'instance.

  4. Dans la liste des tables, cliquez sur la table contenant le schéma de clé de ligne que vous souhaitez afficher.

  5. Cliquez sur le schéma de clé de ligne.

    L'onglet "Détails" s'ouvre.

gcloud

Pour afficher un schéma de clé de ligne, utilisez la gcloud beta bigtable tables describe commande :

  gcloud bigtable tables describe TABLE_NAME \
    --instance=INSTANCE_ID

Remplacez les éléments suivants :

  • TABLE_NAME : nom unique de la table dont vous souhaitez afficher le schéma de clé de ligne
  • INSTANCE_ID : ID de l'instance dans laquelle se trouve la table

La réponse dans le terminal est semblable à la suivante. Si la table ne comporte pas de schéma de clé de ligne, la réponse n'inclut pas de section 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

Le champ RowKeySchema est disponible dans l'objet TableInfo, et vous le récupérez à l'aide de la méthode .TableInfo().

type TableInfo struct {
  ...
  RowKeySchema          *StructType
}

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

Interroger des clés de ligne structurées

Pour interroger les colonnes des clés de ligne structurées, vous devez utiliser SQL. La méthode ReadRows de l'API Bigtable Data ignore un schéma de clé de ligne lorsqu'elle lit une table.

Pour obtenir des exemples de requêtes sélectionnant des clés de ligne structurées, consultez la section Requêtes de clé de ligne structurées.

Pour obtenir la liste des bibliothèques clientes Bigtable compatibles avec les requêtes SQL, y compris des exemples de code, consultez la section Utiliser SQL avec une bibliothèque cliente Bigtable.

Exemples de fichiers de schéma

Lorsque vous créez un schéma de clé de ligne à l'aide de la gcloud CLI, vous pouvez définir les clés de ligne structurées à l'aide d'un fichier YAML ou JSON.

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=="
    }
  }
}

Étape suivante