Crea y administra posiciones de datos

Nota: Esta función está disponible en la edición Spanner Enterprise Plus. Para obtener más información, consulta la descripción general de las ediciones de Spanner.

En esta página, se describe cómo crear y administrar ubicaciones de datos en Spanner.

Para obtener más información sobre el funcionamiento de la partición geográfica, consulta la descripción general de la partición geográfica.

Administra los metadatos de enrutamiento

Cuando tu aplicación necesita leer o escribir datos, Spanner usa metadatos de enrutamiento para encontrar qué servidores contienen las filas específicas necesarias.

La elección de dónde residen los metadatos de enrutamiento depende de si la mayoría de las solicitudes del cliente son para datos dentro de la misma región o fuera de ella, y si usas una configuración de varias regiones. La configuración de los metadatos de enrutamiento afecta la latencia y no se puede cambiar después de crear las ubicaciones.

La opción per_placement_routing_metadata determina dónde residen los metadatos de enrutamiento según la siguiente configuración:

• TRUE: Si se establece en TRUE, los metadatos de enrutamiento residen en la misma partición de instancia que los datos. Los metadatos de enrutamiento se fragmentan por región. Esto reduce la latencia de las solicitudes de datos dentro de la región (es decir, el cliente y los datos del usuario solicitados están en la misma región) para que Spanner no tenga que realizar llamadas fuera de la región para los metadatos de enrutamiento. Sin embargo, esta configuración puede aumentar la latencia de las solicitudes fuera de la región, de las búsquedas negativas en las que no existen filas de ubicación y de las consultas que necesitan un índice global.

  Recomendamos esta configuración si esperas que la mayoría de las solicitudes se realicen para los datos del usuario dentro de la misma región que el cliente y si tu partición predeterminada no tiene regiones de lectura y escritura o de solo lectura que estén ubicadas junto con todas las particiones de tu instancia.

• FALSE: Los metadatos de enrutamiento se centralizan en la partición predeterminada.

  Recomendamos esta configuración si esperas que los clientes busquen datos fuera de la región con frecuencia; por ejemplo, un cliente en la región de la UE que busca datos para usuarios en EE.UU.

  También considera esta configuración si la partición de instancia predeterminada usa una configuración de varias regiones que proporciona regiones de lectura y escritura o de solo lectura que están ubicadas junto con todas las particiones de tu instancia. Con esta configuración, se almacena una réplica de los metadatos de enrutamiento completos con cada réplica de la partición de instancia predeterminada. Por lo tanto, todas las regiones con particiones de instancia tienen una réplica de los metadatos de enrutamiento. Esto permite que las solicitudes dentro y fuera de la región busquen metadatos de enrutamiento de forma local.

Nota: Antes de julio de 2026, el valor predeterminado era FALSE. A partir de julio de 2026, el valor predeterminado es TRUE. Es posible que veas diferentes resultados de latencia entre las bases de datos creadas antes y después del cambio de valor predeterminado. Te recomendamos que establezcas esta opción de forma explícita para evitar cambios inesperados.

Establece la opción per_placement_routing_metadata

Nota: Si ya existen ubicaciones de datos, no se podrá establecer esta opción.

Para establecer per_placement_routing_metadata en la Google Cloud consola, actualiza esta opción en el esquema de tu base de datos. Para obtener información sobre cómo actualizar un esquema, consulta Realiza actualizaciones de esquemas.

La opción per_placement_routing_metadata acepta valores booleanos. Si esta opción es TRUE, los metadatos de enrutamiento residen en la misma partición de instancia que los datos. Si es FALSE, los metadatos de enrutamiento residen en la partición de instancia predeterminada.

En el siguiente ejemplo, se muestra un comando ALTER DATABASE de GoogleSQL para establecer esta opción:

ALTER DATABASE DATABASE_NAME SET OPTIONS ( per_placement_routing_metadata = METADATA_BOOLEAN)

Reemplaza lo siguiente:

• DATABASE_NAME: el nombre de tu base de datos.
• METADATA_BOOLEAN: el valor de per_placement_routing_metadata. Si es TRUE, los metadatos de enrutamiento residen en la misma partición de instancia que los datos. Si es FALSE, los metadatos de enrutamiento residen en la partición de instancia predeterminada.

Crea una ubicación de datos

Después de crear las particiones de instancia de Spanner y las bases de datos, y de establecer la opción per_placement_routing_metadata, crea tu ubicación.

Console

1. Ve a la página Instancias en la Google Cloud consola.

   Instancias

2. Selecciona la instancia con las particiones de instancia creadas por el usuario.

3. Selecciona la base de datos en la que deseas particionar los datos.

4. En el menú de navegación, haz clic en Spanner Studio.

5. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

6. Ingresa la instrucción DDL CREATE PLACEMENT (GoogleSQL, PostgreSQL) .

   Por ejemplo, puedes ejecutar lo siguiente para crear una tabla de ubicación europeplacement en la partición de instancia europe-partition:

   GoogleSQL

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

   PostgreSQL

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

   Opcional: También puedes usar el panel Explorador de objetos para ver, buscar e interactuar con tus objetos de ubicación. Para obtener más información, consulta Explora tus datos.

7. Haz clic en Ejecutar.

gcloud

Para crear una ubicación con el comando de Google Cloud CLI, usa gcloud spanner databases ddl update.

Por ejemplo, crea una ubicación en la partición de instancia 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')"

Establece el líder predeterminado para una ubicación

Puedes establecer la región líder predeterminada de una ubicación si su ubicación está en una región múltiple. La región líder nueva debe ser una de las dos regiones de lectura y escritura dentro de la ubicación de la ubicación de varias regiones. Para obtener más información, configuraciones disponibles de varias regiones tablas.

Si no estableces una región líder, tu ubicación usa la región líder predeterminada según lo especificado por su ubicación. Para obtener una lista de la región líder de cada ubicación de varias regiones, consulta las tablas de configuraciones disponibles de varias regiones. La región líder predeterminada se indica con una L. Por ejemplo, la región líder predeterminada de nam8 está en Los Ángeles(us-west2). En las siguientes instrucciones, se explica cómo establecerla en Oregón(us-west1).

Console

1. Ve a la página Instancias en la Google Cloud consola.

   Instancias

2. Selecciona la instancia con las particiones de instancia creadas por el usuario.

3. Selecciona la base de datos en la que deseas particionar los datos.

4. En el menú de navegación, haz clic en Spanner Studio.

5. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

6. Ingresa la instrucción DDL CREATE PLACEMENT (GoogleSQL, PostgreSQL) .

   Por ejemplo, puedes ejecutar lo siguiente para crear una tabla de ubicación nam8placement en la partición de instancia nam8-partition con la ubicación líder predeterminada establecida como 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');
   

   Opcional: También puedes usar el panel Explorador de objetos para ver, buscar e interactuar con tus objetos de ubicación. Para obtener más información, consulta Explora tus datos.

7. Haz clic en Ejecutar.

gcloud

Para crear una ubicación con el comando de gcloud CLI, usa gcloud spanner databases ddl update.

Por ejemplo, crea una tabla de ubicación nam8placement en la partición de instancia nam8-partition con la ubicación líder predeterminada establecida como 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')"

Quita una ubicación de datos

Antes de quitar una ubicación, debes quitar todos los datos de fila de la ubicación. Después de hacerlo, puedes usar la Google Cloud consola o la gcloud CLI para quitar la ubicación.

Console

1. En el menú de navegación, haz clic en Spanner Studio.
2. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

3. Ingresa la instrucción DDL DROP PLACEMENT(GoogleSQL, PostgreSQL).

   Por ejemplo, puedes ejecutar lo siguiente para quitar la tabla de ubicación europeplacement:

   GoogleSQL

   DROP PLACEMENT europeplacement;
   

   PostgreSQL

   DROP PLACEMENT europeplacement;
   

gcloud

Para quitar una ubicación con el comando de gcloud CLI, usa gcloud spanner databases ddl update.

Por ejemplo, quita la ubicación europeplacement:

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

Errores de eliminación de ubicación

Si la ubicación está en uso, la operación DROP PLACEMENT falla con un mensaje de error como el siguiente: "Statement failed: Placement PLACEMENT_NAME can't be dropped because it is in use by placement table PLACEMENT_TABLE_NAME.". Si encuentras este error, completa los siguientes pasos:

1. Modifica tu aplicación para dejar de insertar o actualizar filas con la ubicación que deseas quitar.

2. Realiza una de las siguientes acciones:

   • Mueve las filas de ubicación existentes que usan la ubicación que deseas borrar a una ubicación diferente con una instrucción DML particionada como la siguiente:

     UPDATE PLACEMENT_TABLE_NAME SET LOCATION = NEW_PLACEMENT_NAME
     WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
     

   • Borra las filas de ubicación con una declaración DML particionada como la siguiente:

     DELETE FROM PLACEMENT_TABLE_NAME
     WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
     

     Las instrucciones DML anteriores específicas de la ubicación solo funcionan con DML particionado. Fallarán como instrucciones DML normales. Para obtener más información, consulta Limitaciones. También puedes usar la API de mutación para mover o quitar filas de ubicación.

Cancela una operación DROP PLACEMENT

Puedes cancelar una operación DROP PLACEMENT en cualquier momento antes de que la operación de larga duración borre por completo la ubicación del esquema de la base de datos. Para obtener detalles sobre cómo obtener el ID de la operación de larga duración para verificar el estado o cancelar la operación, consulta Administra y observa operaciones de larga duración.

Crea una tabla con una clave de ubicación

Console

1. En el menú de navegación, haz clic en Spanner Studio.
2. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

3. Ingresa la instrucción DDL CREATE TABLE (GoogleSQL, PostgreSQL).

   Por ejemplo, puedes crear una tabla Singers que use una clave de ubicación para particionar los datos del cantante:

   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

Para crear una tabla, usa gcloud spanner databases ddl update.

Por ejemplo, puedes crear una tabla Singers que use una clave de ubicación para particionar los datos del cantante:

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 );"

Edita una tabla con una clave de ubicación

No puedes quitar una clave de ubicación de una tabla. Tampoco puedes agregar una clave de ubicación a una tabla después de que se creó. Sin embargo, puedes usar la ALTER TABLE (GoogleSQL, PostgreSQL) instrucción DDL para cambiar otros campos de la tabla, por ejemplo, agregando y quitando columnas de clave que no sean de ubicación.

Borra una tabla con una clave de ubicación

Antes de borrar una tabla con una clave de ubicación, primero debes hacer lo siguiente:

1. Borra todas las filas de la tabla de ubicación.
2. Espera a que pase el version_retention_period para la base de datos. Para obtener más información, consulta Recuperación de un momento determinado. Luego, sigue estos pasos:

Console

1. En el menú de navegación, haz clic en Spanner Studio.
2. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

3. Ingresa la instrucción DDL DROP TABLE (GoogleSQL, PostgreSQL).

   Por ejemplo, quita la tabla Singers:

   DROP TABLE Singers;
   

gcloud

Para quitar una tabla, usa gcloud spanner databases ddl update.

Por ejemplo, quita la tabla Singers:

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

Inserta una fila en una tabla de ubicación

Console

1. En el menú de navegación, haz clic en Spanner Studio.
2. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

3. Ingresa la instrucción DDL INSERT INTO (GoogleSQL, PostgreSQL).

   Por ejemplo, agrega un cantante, Marc Richards, a la tabla Singers y particiónalo en europeplacement:

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

gcloud

Para escribir datos en una tabla, usa gcloud spanner rows insert.

Por ejemplo, agrega un cantante, Marc Richards, a la tabla Singers y particiónalo en europeplacement:

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

Actualiza una fila en una tabla de ubicación

Console

1. En el menú de navegación, haz clic en Spanner Studio.
2. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

3. Usa DML o mutaciones para actualizar datos en una tabla de ubicación.

   Por ejemplo, actualiza el nombre de singerid=1 en la tabla Singers a Catalina Smith:

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

gcloud

Para actualizar datos en una tabla de ubicación, usa gcloud spanner rows update.

Por ejemplo, actualiza el nombre de singerid=1 en la tabla Singers a Catalina Smith:

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

Mueve una fila en una tabla de ubicación

Console

1. Crea una nueva partición de instancia y una ubicación si aún no lo hiciste.
2. En el menú de navegación, haz clic en Spanner Studio.
3. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

4. Usa DML o mutaciones para mover datos a la nueva partición de instancia.

   Por ejemplo, mueve singerid=1 en la tabla Singers a asiaplacement:

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

gcloud

Después de crear la partición de instancia y la ubicación a la que deseas mover tus datos, usa gcloud spanner rows update.

Por ejemplo, mueve singerid=1 en la tabla Singers a asiaplacement:

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

Borra una fila en una tabla de ubicación

Console

1. En el menú de navegación, haz clic en Spanner Studio.
2. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

3. Usa DML o mutaciones para borrar datos.

   Por ejemplo, borra singerid=1 en la tabla Singers:

   DELETE FROM Singers s
   WHERE s.id=1;
   

gcloud

Para borrar datos, usa gcloud spanner rows delete.

Por ejemplo, borra singerid=1 en la tabla Singers:

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

Consulta datos en una tabla de ubicación

Console

1. En el menú de navegación, haz clic en Spanner Studio.
2. En la página Spanner Studio, haz clic en Nueva pestaña o usa la pestaña del editor vacía.

3. Ejecuta tu consulta.

   Por ejemplo, consulta la tabla Singers:

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

gcloud

Para consultar datos, usa gcloud spanner databases execute-sql.

Por ejemplo, consulta la tabla Singers:

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

¿Qué sigue?

• Obtén más información sobre la partición geográfica.

• Obtén información para crear y administrar particiones de instancia.