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 manière 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'octroi 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 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.
gcloud
Pour définir un schéma de clé de ligne à l'aide de la 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 fichiers, consultez 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
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
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 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 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=="
}
}
}