Créer et gérer des emplacements de données

Remarque : Cette fonctionnalité est disponible dans l'édition Spanner Enterprise Plus. Pour en savoir plus, consultez la présentation des éditions Spanner.

Cette page explique comment créer et gérer des emplacements de données dans Spanner.

Pour en savoir plus sur le fonctionnement du géopartitionnement, consultez la présentation du géopartitionnement.

Gérer les métadonnées de routage

Lorsque votre application doit lire ou écrire des données, Spanner utilise des métadonnées de routage pour trouver les serveurs qui contiennent les lignes spécifiques requises.

Le choix de l'emplacement des métadonnées de routage dépend du fait que la plupart des requêtes client concernent des données situées dans la même région ou en dehors de la région, et si vous utilisez une configuration multirégionale. Les paramètres des métadonnées de routage affectent la latence et ne peuvent pas être modifiés après la création des emplacements.

L'option per_placement_routing_metadata détermine l'emplacement des métadonnées de routage en fonction des paramètres suivants :

• TRUE: si la valeur est définie sur TRUE, les métadonnées de routage se trouvent dans la même partition d'instance que les données. Les métadonnées de routage sont fragmentées par région. Cela réduit la latence des requêtes de données dans la région (c'est-à-dire que le client et les données utilisateur demandées se trouvent dans la même région), de sorte que Spanner n'a pas besoin d'effectuer d'appels hors région pour les métadonnées de routage. Toutefois, ce paramètre peut augmenter la latence des requêtes hors région, des recherches négatives où les lignes d'emplacement n'existent pas et des requêtes qui nécessitent un index global.

  Nous vous recommandons ce paramètre si vous prévoyez que la plupart des requêtes seront effectuées pour des données utilisateur dans la même région que le client, et si votre partition par défaut ne comporte pas de régions en lecture/écriture ou en lecture seule colocalisées avec toutes vos partitions d'instance.

• FALSE : les métadonnées de routage sont centralisées dans la partition par défaut.

  Nous vous recommandons ce paramètre si vous prévoyez que les clients rechercheront fréquemment des données hors région. Par exemple, un client de la région UE qui recherche des données pour des utilisateurs aux États-Unis.

  Envisagez également ce paramètre si votre partition d'instance par défaut utilise une configuration multirégionale qui fournit des régions en lecture/écriture ou en lecture seule colocalisées avec toutes vos partitions d'instance. Avec ce paramètre, une instance dupliquée des métadonnées de routage complètes est stockée avec chaque instance dupliquée de la partition d'instance par défaut. Par conséquent, toutes les régions comportant des partitions d'instance disposent d'une instance dupliquée des métadonnées de routage. Cela permet aux requêtes dans la région et hors région de rechercher localement les métadonnées de routage.

Remarque : Avant juillet 2026, la valeur par défaut était FALSE. À partir de juillet 2026, la valeur par défaut est TRUE. Vous pouvez constater des résultats de latence différents entre les bases de données créées avant et après la modification de la valeur par défaut. Nous vous recommandons de définir cette option explicitement pour éviter les modifications inattendues.

Définir l'option per_placement_routing_metadata

Remarque : La définition de cette option échoue s'il existe déjà des emplacements de données.

Pour définir per_placement_routing_metadata dans la Google Cloud console, mettez à jour cette option dans le schéma de votre base de données. Pour savoir comment mettre à jour un schéma, consultez la section Effectuer des mises à jour de schéma.

L'option per_placement_routing_metadata accepte les valeurs booléennes. Si cette option est TRUE, les métadonnées de routage se trouvent dans la même partition d'instance que les données. Si la valeur est FALSE, les métadonnées de routage se trouvent dans la partition d'instance par défaut.

L'exemple suivant montre une commande GoogleSQL ALTER DATABASE permettant de définir cette option :

ALTER DATABASE DATABASE_NAME SET OPTIONS ( per_placement_routing_metadata = METADATA_BOOLEAN)

Remplacez les éléments suivants :

• DATABASE_NAME : nom de votre base de données.
• METADATA_BOOLEAN: valeur per_placement_routing_metadata. Si la valeur est TRUE, les métadonnées de routage se trouvent dans la même partition d'instance que les données. Si la valeur est FALSE, les métadonnées de routage se trouvent dans la partition d'instance par défaut.

Créer un emplacement de données

Après avoir créé vos partitions d'instance Spanner et vos bases de données, et défini l'option per_placement_routing_metadata, créez votre emplacement.

Console

1. Accédez à la page Instances dans la Google Cloud console.

   Instances

2. Sélectionnez l'instance avec une ou plusieurs partitions d'instance créées par l'utilisateur.

3. Sélectionnez la base de données dans laquelle vous souhaitez partitionner les données.

4. Dans le menu de navigation, cliquez sur Spanner Studio.

5. Sur la page Spanner Studio, cliquez sur Nouvel onglet ou utilisez l'onglet d'éditeur vide.

6. Saisissez l'instruction LDD CREATE PLACEMENT (GoogleSQL, PostgreSQL) .

   Par exemple, vous pouvez exécuter la commande suivante pour créer une table d'emplacement europeplacement dans la partition d'instance europe-partition :

   GoogleSQL

   CREATE PLACEMENT europeplacement OPTIONS (instance_partition="europe-partition");
   

   PostgreSQL

   CREATE PLACEMENT europeplacement WITH (instance_partition='europe-partition');
   

   Facultatif : Vous pouvez également utiliser le volet Explorateur d'objets pour afficher vos objets d'emplacement, effectuer des recherches et interagir avec eux. Pour en savoir plus, consultez la section Explorer vos données.

7. Cliquez sur Exécuter.

gcloud

Pour créer un emplacement avec la commande Google Cloud CLI, utilisez gcloud spanner databases ddl update.

Par exemple, créez un emplacement dans la partition d'instance europe-partition :

GoogleSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT europeplacement OPTIONS (instance_partition='europe-partition')"

PostgreSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT europeplacement WITH (instance_partition='europe-partition')"

Définir le leader par défaut pour un emplacement

Vous pouvez définir la région principale par défaut d'un emplacement si celui-ci se trouve dans une région multirégionale. La nouvelle région principale doit être l'une des deux régions en lecture/écriture dans l'emplacement multirégional. Pour en savoir plus, consultez les tableaux des configurations disponibles dans les régions multirégionales.

Si vous ne définissez pas de région principale, votre emplacement utilise la région principale par défaut spécifiée par son emplacement. Pour obtenir la liste des régions principales pour chaque emplacement multirégional, consultez les tableaux des configurations disponibles dans les régions multirégionales. La région principale par défaut est indiquée par un L. Par exemple, la région principale par défaut de nam8 se trouve à Los Angeles(us-west2). Les instructions suivantes expliquent comment la définir sur l'Oregon(us-west1).

Console

1. Accédez à la page Instances dans la Google Cloud console.

   Instances

2. Sélectionnez l'instance avec une ou plusieurs partitions d'instance créées par l'utilisateur.

3. Sélectionnez la base de données dans laquelle vous souhaitez partitionner les données.

4. Dans le menu de navigation, cliquez sur Spanner Studio.

5. Sur la page Spanner Studio, cliquez sur Nouvel onglet ou utilisez l'onglet d'éditeur vide.

6. Saisissez l'instruction LDD CREATE PLACEMENT (GoogleSQL, PostgreSQL) .

   Par exemple, vous pouvez exécuter la commande suivante pour créer une table d'emplacement nam8placement dans la partition d'instance nam8-partition avec l'emplacement principal par défaut défini sur us-west1 :

   GoogleSQL

   CREATE PLACEMENT `nam8placement`
     OPTIONS (instance_partition="nam8-partition", default_leader="us-west1");
   

   PostgreSQL

   CREATE PLACEMENT nam8placement WITH (instance_partition='nam8-partition', default_leader='us-west1');
   

   Facultatif : Vous pouvez également utiliser le volet Explorateur d'objets pour afficher vos objets d'emplacement, effectuer des recherches et interagir avec eux. Pour en savoir plus, consultez la section Explorer vos données.

7. Cliquez sur Exécuter.

gcloud

Pour créer un emplacement avec la commande gcloud CLI, utilisez gcloud spanner databases ddl update.

Par exemple, créez une table d'emplacement nam8placement dans la partition d'instance nam8-partition avec l'emplacement principal par défaut défini sur us-west1 :

GoogleSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT nam8placement \
     OPTIONS (instance_partition='nam8-partition', default_leader='us-west1')"

PostgreSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE PLACEMENT nam8placement WITH (instance_partition='nam8-partition', default_leader='us-west1')"

Supprimer un emplacement de données

Avant de supprimer un emplacement, vous devez supprimer toutes les données de ligne de l'emplacement. Une fois cette opération effectuée, vous pouvez utiliser la Google Cloud console ou gcloud CLI pour supprimer l'emplacement.

Console

1. Dans le menu de navigation, cliquez sur Spanner Studio.
2. Sur la page Spanner Studio, cliquez sur Nouvel onglet ou utilisez l'onglet d'éditeur vide.

3. Saisissez l'instruction LDD DROP PLACEMENT(GoogleSQL, PostgreSQL).

   Par exemple, vous pouvez exécuter la commande suivante pour supprimer la table d'emplacement europeplacement :

   GoogleSQL

   DROP PLACEMENT europeplacement;
   

   PostgreSQL

   DROP PLACEMENT europeplacement;
   

gcloud

Pour supprimer un emplacement avec la commande gcloud CLI, utilisez gcloud spanner databases ddl update.

Par exemple, supprimez l'emplacement europeplacement :

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="DROP PLACEMENT europeplacement"

Erreurs de suppression d'emplacement

Si l'emplacement est en cours d'utilisation, l'opération DROP PLACEMENT échoue et affiche un message d'erreur tel que : "Statement failed: Placement PLACEMENT_NAME can't be dropped because it is in use by placement table PLACEMENT_TABLE_NAME." (Échec de l'instruction : l'emplacement PLACEMENT_NAME ne peut pas être supprimé, car il est utilisé par la table d'emplacement PLACEMENT_TABLE_NAME). Si cette erreur se produit, procédez comme suit :

1. Modifiez votre application pour arrêter d'insérer ou de mettre à jour des lignes avec l'emplacement que vous souhaitez supprimer.

2. L'une des options ci-dessous :

   • Déplacez les lignes d'emplacement existantes qui utilisent l'emplacement que vous souhaitez supprimer vers un autre emplacement à l'aide d'une instruction LMD partitionnée comme suit :

     UPDATE PLACEMENT_TABLE_NAME SET LOCATION = NEW_PLACEMENT_NAME
     WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
     

   • Supprimez les lignes d'emplacement à l'aide d'une instruction LMD partitionnée comme suit :

     DELETE FROM PLACEMENT_TABLE_NAME
     WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
     

     Les instructions LMD spécifiques à l'emplacement précédentes ne fonctionnent qu'avec le LMD partitionné. Elles échoueront en tant qu'instructions LMD régulières. Pour en savoir plus, consultez la section Limites. Vous pouvez également utiliser l'API de mutation pour déplacer ou supprimer des lignes d'emplacement.

Annuler une opération DROP PLACEMENT

Vous pouvez annuler une opération DROP PLACEMENT à tout moment avant que l'opération de longue durée ne supprime complètement l'emplacement du schéma de la base de données. Pour savoir comment obtenir l'ID de l'opération de longue durée afin de vérifier l'état ou d'annuler l'opération, consultez la section Gérer et observer les opérations de longue durée.

Créer une table avec une clé d'emplacement

Console

1. Dans le menu de navigation, cliquez sur Spanner Studio.
2. Sur la page Spanner Studio, cliquez Nouvel onglet ou utilisez l'onglet d'éditeur vide.

3. Saisissez l'instruction LDD CREATE TABLE (GoogleSQL, PostgreSQL).

   Par exemple, vous pouvez créer une table Singers qui utilise une clé d'emplacement pour partitionner les données des chanteurs :

   GoogleSQL

   CREATE TABLE Singers (
     SingerId INT64 NOT NULL,
     SingerName STRING(MAX) NOT NULL,
     ...
     Location STRING(MAX) NOT NULL PLACEMENT KEY
   ) PRIMARY KEY (SingerId);
   

   PostgreSQL

   CREATE TABLE Singers (
     SingerId bigint PRIMARY KEY,
     SingerName varchar(1024),
     ...
     Location varchar(1024) NOT NULL PLACEMENT KEY
   );
   

gcloud

Pour créer une table, utilisez gcloud spanner databases ddl update.

Par exemple, vous pouvez créer une table Singers qui utilise une clé d'emplacement pour partitionner les données des chanteurs :

GoogleSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE TABLE Singers ( SingerId INT64 NOT NULL, SingerName STRING(MAX) NOT NULL, Location STRING(MAX) NOT NULL PLACEMENT KEY ) PRIMARY KEY (SingerId);"

PostgreSQL

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="CREATE TABLE Singers ( SingerId bigint PRIMARY KEY, SingerName varchar(1024), Location varchar(1024) NOT NULL PLACEMENT KEY );"

Modifier une table avec une clé d'emplacement

Vous ne pouvez pas supprimer une clé d'emplacement d'une table. Vous ne pouvez pas non plus ajouter de clé d'emplacement à une table après sa création. Toutefois, vous pouvez utiliser l' ALTER TABLE (GoogleSQL, PostgreSQL) instruction LDD pour modifier d'autres champs dans la table, par exemple en ajoutant et en supprimant des colonnes de clé qui ne sont pas des emplacements.

Supprimer une table avec une clé d'emplacement

Avant de supprimer une table avec une clé d'emplacement, vous devez d'abord :

1. Supprimer toutes les lignes de la table d'emplacement.
2. Attendre que le version_retention_period pour la base de données soit écoulé. Pour en savoir plus, consultez la section Récupération à un moment précis. Ensuite, procédez comme suit :

Console

1. Dans le menu de navigation, cliquez sur Spanner Studio.
2. Sur la page Spanner Studio, cliquez Nouvel onglet ou utilisez l'onglet d'éditeur vide.

3. Saisissez l'instruction LDD DROP TABLE (GoogleSQL, PostgreSQL).

   Par exemple, supprimez la table Singers :

   DROP TABLE Singers;
   

gcloud

Pour supprimer une table, utilisez gcloud spanner databases ddl update.

Par exemple, supprimez la table Singers :

gcloud spanner databases ddl update example-db \
  --instance=test-instance \
  --ddl="DROP TABLE Singers"

Insérer une ligne dans une table d'emplacement

Console

1. Dans le menu de navigation, cliquez sur Spanner Studio.
2. Sur la page Spanner Studio, cliquez Nouvel onglet ou utilisez l'onglet d'éditeur vide.

3. Saisissez l'instruction LDD INSERT INTO (GoogleSQL, PostgreSQL).

   Par exemple, ajoutez un chanteur, Marc Richards, à la table Singers et partitionnez-le dans europeplacement :

   INSERT INTO Singers(SingerId, SingerName, Location)
   VALUES (1, 'Marc Richards', 'europeplacement')
   

gcloud

Pour écrire des données dans une table, utilisez gcloud spanner rows insert.

Par exemple, ajoutez un chanteur, Marc Richards, à la table Singers et partitionnez-le dans europeplacement :

gcloud spanner rows insert --table=Singers --database=example-db \
  --instance=test-instance --data=SingerId=1,SingerName='Marc Richards',Location='europeplacement'

Mettre à jour une ligne dans une table d'emplacement

Console

1. Dans le menu de navigation, cliquez sur Spanner Studio.
2. Sur la page Spanner Studio, cliquez Nouvel onglet ou utilisez l'onglet d'éditeur vide.

3. Utilisez le DML ou les mutations pour mettre à jour les données d'une table d'emplacement.

   Par exemple, remplacez le nom de singerid=1 dans la table Singers par Catalina Smith :

   UPDATE Singers s
   SET s.name='Catalina Smith'
   WHERE s.id=1;
   

gcloud

Pour mettre à jour des données dans une table d'emplacement, utilisez gcloud spanner rows update.

Par exemple, remplacez le nom de singerid=1 dans la table Singers par Catalina Smith :

gcloud spanner rows update --table=Singers --database=example-db \
  --instance=test-instance --data=SingerId=1,SingerName='Catalina Smith'

Déplacer une ligne dans une table d'emplacement

Console

1. Créez une partition d'instance et un emplacement si ce n'est pas déjà fait.
2. Dans le menu de navigation, cliquez sur Spanner Studio.
3. Sur la page Spanner Studio, cliquez Nouvel onglet ou utilisez l'onglet d'éditeur vide.

4. Utilisez DML ou des mutations pour déplacer les données vers la nouvelle partition d'instance.

   Par exemple, déplacez singerid=1 dans la table Singers vers asiaplacement :

   UPDATE Singers s
   SET s.location='asiaplacement'
   WHERE s.id=1;
   

gcloud

Après avoir créé la partition d'instance et l'emplacement vers lesquels vous souhaitez déplacer vos données, utilisez gcloud spanner rows update.

Par exemple, déplacez singerid=1 dans la table Singers vers asiaplacement :

gcloud spanner rows update --table=Singers --database=example-db \
  --instance=test-instance --data=SingerId=1,Location='asiaplacement'

Supprimer une ligne dans une table d'emplacement

Console

1. Dans le menu de navigation, cliquez sur Spanner Studio.
2. Sur la page Spanner Studio, cliquez Nouvel onglet ou utilisez l'onglet d'éditeur vide.

3. Utilisez le DML ou les mutations pour supprimer des données.

   Par exemple, supprimez singerid=1 dans la table Singers :

   DELETE FROM Singers s
   WHERE s.id=1;
   

gcloud

Pour supprimer des données, utilisez gcloud spanner rows delete.

Par exemple, supprimez singerid=1 dans la table Singers :

gcloud spanner rows delete --table=Singers --database=example-db \
  --instance=test-instance --keys=1

Interroger les données d'une table d'emplacement

Console

1. Dans le menu de navigation, cliquez sur Spanner Studio.
2. Sur la page Spanner Studio, cliquez Nouvel onglet ou utilisez l'onglet d'éditeur vide.

3. Exécutez votre requête.

   Par exemple, interrogez la table Singers :

   SELECT * FROM Singers s WHERE s.SingerId=1;
   

gcloud

Pour interroger des données, utilisez gcloud spanner databases execute-sql.

Par exemple, interrogez la table Singers :

gcloud spanner databases execute-sql example-db \
  --instance=test-instance \
  --sql='SELECT * FROM Singers s WHERE s.SingerId=1'

Étape suivante

• En savoir plus sur le géopartitionnement.

• Découvrez comment créer et gérer des partitions d'instance.