Criar e gerenciar posições de dados

Observação:esse recurso está disponível na edição Enterprise Plus do Spanner. Para mais informações, consulte a visão geral das edições do Spanner.

Esta página descreve como criar e gerenciar posições de dados no Spanner.

Para mais informações sobre como o geoparticionamento funciona, consulte a visão geral do geoparticionamento.

Gerenciar metadados de roteamento

Quando o aplicativo precisa ler ou gravar dados, o Spanner usa metadados de roteamento para encontrar os servidores que contêm as linhas específicas necessárias.

A escolha de onde os metadados de roteamento residem depende de se a maioria das solicitações do cliente é de dados na mesma região ou fora dela e se você usa uma configuração multirregional. As configurações de metadados de roteamento afetam a latência e não podem ser alteradas depois que você cria posições.

A opção per_placement_routing_metadata determina onde os metadados de roteamento residem de acordo com as seguintes configurações:

• TRUE: se definido como TRUE, os metadados de roteamento residem na mesma partição de instância que os dados. Os metadados de roteamento são fragmentados por região. Isso reduz a latência das solicitações de dados na região (ou seja, o cliente e os dados do usuário solicitados estão na mesma região), para que o Spanner não precise fazer chamadas fora da região para metadados de roteamento. No entanto, essa configuração pode aumentar a latência de solicitações fora da região, para pesquisas negativas em que as linhas de posição não existem e para consultas que precisam de um índice global.

  Recomendamos essa configuração se você espera que a maioria das solicitações seja feita para dados do usuário na mesma região que o cliente e se a partição padrão não tiver regiões de leitura/gravação ou somente leitura que estejam colocalizadas com todas as partições de instância.

• FALSE: os metadados de roteamento são centralizados na partição padrão.

  Recomendamos essa configuração se você espera que os clientes pesquisem dados fora da região com frequência. Por exemplo, um cliente na região da UE que pesquisa dados de usuários nos EUA.

  Considere também essa configuração se a partição de instância padrão usar uma configuração multirregional que forneça regiões de leitura/gravação ou somente leitura que estejam colocalizadas com todas as partições de instância. Com essa configuração, uma réplica dos metadados de roteamento completos é armazenada com cada réplica da partição de instância padrão. Portanto, todas as regiões com partições de instância têm uma réplica dos metadados de roteamento. Isso permite que as solicitações na região e fora dela pesquisem metadados de roteamento localmente.

Observação: antes de julho de 2026, o valor padrão era FALSE. A partir de julho de 2026, o padrão é TRUE. Você pode encontrar resultados de latência diferentes entre bancos de dados criados antes e depois da mudança de valor padrão. Recomendamos que você defina essa opção explicitamente para evitar mudanças inesperadas.

Definir a opção per_placement_routing_metadata

**Observação**: a definição dessa opção falha se já houver posições de dados.

Para definir per_placement_routing_metadata no Google Cloud console, atualize essa opção no esquema do banco de dados. Para informações sobre como atualizar um esquema, consulte Fazer atualizações de esquema.

A opção per_placement_routing_metadata aceita valores booleanos. Se essa opção for TRUE, os metadados de roteamento residirão na mesma partição de instância que os dados. Se FALSE, os metadados de roteamento residirão na partição de instância padrão.

O exemplo a seguir mostra um comando ALTER DATABASE do GoogleSQL para definir essa opção:

ALTER DATABASE DATABASE_NAME SET OPTIONS ( per_placement_routing_metadata = METADATA_BOOLEAN)

Substitua:

• DATABASE_NAME: o nome do banco de dados.
• METADATA_BOOLEAN: o valor per_placement_routing_metadata. Se TRUE, os metadados de roteamento residirão na mesma partição de instância que os dados. Se FALSE, os metadados de roteamento residirão na partição de instância padrão.

Criar uma posição de dados

Depois de criar as partições e os bancos de dados da instância do Spanner e definir a opção per_placement_routing_metadata, crie a posição.

Console

1. Acesse a página Instâncias no Google Cloud console.

   Instâncias

2. Selecione a instância com partições de instância criadas pelo usuário.

3. Selecione o banco de dados que você quer particionar.

4. No menu de navegação, clique em Spanner Studio.

5. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

6. Insira a instrução DDL CREATE PLACEMENT (GoogleSQL, PostgreSQL) .

   Por exemplo, execute o comando a seguir para criar uma tabela de posição europeplacement na partição de instância europe-partition:

   GoogleSQL

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

   PostgreSQL

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

   Opcional: também é possível usar o painel Object Explorer para visualizar, pesquisar e interagir com os objetos de posição. Para mais informações, consulte Explorar seus dados.

7. Clique em Executar.

gcloud

Para criar um posicionamento com o comando da Google Cloud CLI, use gcloud spanner databases ddl update.

Por exemplo, crie uma posição na partição de instância 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')"

Definir o líder padrão de uma posição

É possível definir a região líder padrão de uma posição se o local dela estiver em uma multirregião. A nova região líder precisa ser uma das duas regiões de leitura e gravação no local de posição multirregional. Para mais informações, consulte as tabelas de configurações disponíveis multirregionais.

Se você não definir uma região líder, a posição usará a região líder padrão especificada pelo local. Para uma lista da região líder de cada local multirregional, consulte as tabelas de configurações disponíveis multirregionais. A região líder padrão é indicada com um L. Por exemplo, a região líder padrão de nam8 está em Los Angeles(us-west2). As instruções a seguir explicam como defini-la como Oregon(us-west1).

Console

1. Acesse a página Instâncias no Google Cloud console.

   Instâncias

2. Selecione a instância com partições de instância criadas pelo usuário.

3. Selecione o banco de dados que você quer particionar.

4. No menu de navegação, clique em Spanner Studio.

5. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

6. Insira a instrução DDL CREATE PLACEMENT (GoogleSQL, PostgreSQL) .

   Por exemplo, execute o comando a seguir para criar uma tabela de posição nam8placement na partição de instância nam8-partition com o local líder padrão definido 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: também é possível usar o painel Object Explorer para visualizar, pesquisar e interagir com os objetos de posição. Para mais informações, consulte Explorar seus dados.

7. Clique em Executar.

gcloud

Para criar uma posição com o comando da CLI gcloud, use gcloud spanner databases ddl update.

Por exemplo, crie uma tabela de posição nam8placement na partição de instância nam8-partition com o local líder padrão definido 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')"

Remover uma posição de dados

Antes de remover uma posição, é necessário remover todos os dados de linha dela. Depois de fazer isso, use o Google Cloud console ou a CLI gcloud para remover a posição.

Console

1. No menu de navegação, clique em Spanner Studio.
2. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

3. Insira a instrução DDL DROP PLACEMENT(GoogleSQL, PostgreSQL).

   Por exemplo, execute o comando a seguir para remover a tabela de posição europeplacement:

   GoogleSQL

   DROP PLACEMENT europeplacement;
   

   PostgreSQL

   DROP PLACEMENT europeplacement;
   

gcloud

Para remover uma posição com o comando da CLI gcloud, use gcloud spanner databases ddl update.

Por exemplo, remova a posição europeplacement:

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

Erros de remoção de posição

Se a posição estiver em uso, a operação DROP PLACEMENT falhará com uma mensagem de erro como: "Statement failed: Placement PLACEMENT_NAME can't be dropped because it is in use by placement table PLACEMENT_TABLE_NAME.". Se você encontrar esse erro, siga estas etapas:

1. Modifique o aplicativo para interromper a inserção ou atualização de linhas com a posição que você quer remover.

2. Siga uma destas instruções:

   • Mova as linhas de posição atuais que usam a posição que você quer excluir para uma posição diferente com uma instrução DML particionada como a seguinte:

     UPDATE PLACEMENT_TABLE_NAME SET LOCATION = NEW_PLACEMENT_NAME
     WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
     

   • Exclua as linhas de posição com uma instrução DML particionada como a seguinte:

     DELETE FROM PLACEMENT_TABLE_NAME
     WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
     

     As instruções DML específicas da posição anterior só funcionam com DML particionada. Elas falharão como instruções DML normais. Saiba mais em Limitações. Também é possível usar a API Mutation para mover ou remover linhas de posição.

Cancelar uma operação DROP PLACEMENT

É possível cancelar uma operação DROP PLACEMENT a qualquer momento antes que a operação de longa duração exclua completamente a posição do esquema do banco de dados. Para detalhes sobre como receber o ID da operação de longa duração para verificar o status ou cancelar a operação, consulte Gerenciar e observar operações de longa duração.

Criar uma tabela com uma chave de posição

Console

1. No menu de navegação, clique em Spanner Studio.
2. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

3. Insira a instrução DDL CREATE TABLE (GoogleSQL, PostgreSQL).

   Por exemplo, é possível criar uma tabela Singers que usa uma chave de posição para particionar dados de cantores:

   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 criar uma tabela, use gcloud spanner databases ddl update.

Por exemplo, é possível criar uma tabela Singers que usa uma chave de posição para particionar dados de cantores:

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

Editar uma tabela com uma chave de posição

Não é possível remover uma chave de posição de uma tabela. Também não é possível adicionar uma chave de posição a uma tabela depois que ela for criada. No entanto, é possível usar a ALTER TABLE (GoogleSQL, PostgreSQL) instrução DDL para mudar outros campos em tabela, por exemplo, adicionando e removendo colunas de chave não posicionadas.

Excluir uma tabela com uma chave de posição

Antes de excluir uma tabela com uma chave de posição, primeiro é necessário:

1. Excluir todas as linhas na tabela de posição.
2. Aguardar a passagem do version_retention_period para o banco de dados. Para mais informações, consulte Recuperação pontual. Em seguida, siga estas etapas:

Console

1. No menu de navegação, clique em Spanner Studio.
2. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

3. Insira a instrução DDL DROP TABLE (GoogleSQL, PostgreSQL).

   Por exemplo, remova a tabela Singers:

   DROP TABLE Singers;
   

gcloud

Para remover uma tabela, use gcloud spanner databases ddl update.

Por exemplo, remova a tabela Singers:

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

Inserir uma linha em uma tabela de posição

Console

1. No menu de navegação, clique em Spanner Studio.
2. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

3. Insira a instrução DDL INSERT INTO (GoogleSQL, PostgreSQL).

   Por exemplo, adicione um cantor, Marc Richards, à tabela Singers e particione-o em europeplacement:

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

gcloud

Para gravar dados em uma tabela, use gcloud spanner rows insert.

Por exemplo, adicione um cantor, Marc Richards, à tabela Singers e particione-o em europeplacement:

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

Atualizar uma linha em uma tabela de posição

Console

1. No menu de navegação, clique em Spanner Studio.
2. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

3. Use DML ou mutações para atualizar dados em uma tabela de posição.

   Por exemplo, atualize o nome de singerid=1 na tabela Singers para Catalina Smith:

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

gcloud

Para atualizar dados em uma tabela de posição, use gcloud spanner rows update.

Por exemplo, atualize o nome de singerid=1 na tabela Singers para Catalina Smith:

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

Mover uma linha em uma tabela de posição

Console

1. Crie uma nova partição de instância e posição, se ainda não tiver feito isso.
2. No menu de navegação, clique em Spanner Studio.
3. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

4. Use DML ou mutações para mover dados para a nova partição de instância.

   Por exemplo, mova singerid=1 na tabela Singers para asiaplacement:

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

gcloud

Depois de criar a partição de instância e a posição em que você quer mover seus dados, use gcloud spanner rows update.

Por exemplo, mova singerid=1 na tabela Singers para asiaplacement:

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

Excluir uma linha de uma tabela de posição

Console

1. No menu de navegação, clique em Spanner Studio.
2. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

3. Use DML ou mutações para excluir dados.

   Por exemplo, exclua singerid=1 na tabela Singers:

   DELETE FROM Singers s
   WHERE s.id=1;
   

gcloud

Para excluir dados, use gcloud spanner rows delete.

Por exemplo, exclua singerid=1 na tabela Singers:

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

Consultar dados em uma tabela de posição

Console

1. No menu de navegação, clique em Spanner Studio.
2. Na página Spanner Studio, clique em Nova guia ou use a guia do editor vazia.

3. Execute a consulta.

   Por exemplo, consulte a tabela Singers:

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

gcloud

Para consultar dados, use gcloud spanner databases execute-sql.

Por exemplo, consulte a tabela Singers:

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

A seguir

• Saiba mais sobre geoparticionamento.

• Saiba como criar e gerenciar partições de instância.