Criar e gerenciar posições de dados

Nesta página, descrevemos como criar e gerenciar posicionamentos de dados no Spanner.

Para mais informações sobre como funciona o particionamento geográfico, consulte a Visão geral do particionamento geográfico.

Gerenciar metadados de roteamento

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

A escolha do local em que os metadados de roteamento residem depende de a maioria das solicitações do cliente ser para 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 as 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 rotear metadados. No entanto, essa configuração pode aumentar a latência de solicitações fora da região, de pesquisas negativas em que não há linhas de posicionamento e de 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 do cliente e sua partição padrão não tenha regiões de leitura e gravação ou somente leitura que estejam colocalizadas com todas as partições da 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 façam pesquisa rápida com frequência dados de fora da região. Por exemplo, um cliente na região da UE que faz pesquisa rápida 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 e 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 dentro e fora da região procurem metadados de roteamento localmente.

Defina a opção per_placement_routing_metadata.

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

Para definir a opção per_placement_routing_metadata, atualize o esquema do banco de dados. Para informações sobre outras maneiras de atualizar um esquema, como bibliotecas de cliente ou as APIs REST e RPC, consulte Fazer atualizações de esquema.

Selecione uma das seguintes opções:

Console

  1. No console do Google Cloud , acesse a página Instâncias.

    Acesse "Instâncias"

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

  3. Selecione o banco de dados em que você quer definir os metadados de roteamento.

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

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

  6. Insira a instrução DDL do ALTER DATABASE (GoogleSQL, PostgreSQL):

    GoogleSQL

    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 de per_placement_routing_metadata. Se for TRUE, os metadados de roteamento vão residir na mesma partição de instância que os dados. Se FALSE, os metadados de roteamento residem na partição de instância padrão.

    PostgreSQL

    ALTER DATABASE "DATABASE_NAME"
      SET spanner.per_placement_routing_metadata = METADATA_BOOLEAN;
    

    Substitua:

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

gcloud

Para definir a opção per_placement_routing_metadata com a Google Cloud CLI, use gcloud spanner databases ddl update:

GoogleSQL

gcloud spanner databases ddl update DATABASE_NAME \
    --instance=INSTANCE_ID \
    --ddl='ALTER DATABASE `DATABASE_NAME`
      SET OPTIONS (per_placement_routing_metadata = METADATA_BOOLEAN)'

Substitua:

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

PostgreSQL

gcloud spanner databases ddl update DATABASE_NAME \
    --instance=INSTANCE_ID \
    --ddl='ALTER DATABASE "DATABASE_NAME"
      SET spanner.per_placement_routing_metadata = METADATA_BOOLEAN'

Substitua:

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

Criar um posicionamento de dados

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

Console

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

    Instâncias

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

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

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

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

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

    Por exemplo, é possível executar o seguinte para criar uma tabela de posicionamento 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: use o painel Pesquisador de objetos para visualizar, pesquisar e interagir com os objetos de posicionamento. Para mais informações, consulte Analisar seus dados.

  7. Clique em Executar.

gcloud

Para criar um posicionamento com o comando da CLI gcloud, 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 para uma posição

É possível definir a região líder padrão de um posicionamento se o local 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 posicionamento multirregional. Para mais informações, consulte as tabelas de configurações multirregionais disponíveis.

Se você não definir uma região líder, o posicionamento usará a região líder padrão, conforme especificado pelo local. Para uma lista da região líder de cada local multirregional, consulte as tabelas Configurações multirregionais disponíveis. A região líder padrão é indicada com um L. Por exemplo, a região líder padrão de nam8 fica 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 console do Google Cloud .

    Instâncias

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

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

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

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

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

    Por exemplo, é possível executar o seguinte para criar uma tabela de posicionamento 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: use o painel Pesquisador de objetos para visualizar, pesquisar e interagir com os objetos de posicionamento. Para mais informações, consulte Analisar seus dados.

  7. Clique em Executar.

gcloud

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

Por exemplo, crie uma tabela de posicionamento nam8placement na partição de instância nam8-partition com o local do 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 um posicionamento de dados

Antes de descartar uma posição, remova todos os dados de linha dela. Depois disso, use o Google Cloud console ou a CLI gcloud para descartar o posicionamento.

Console

  1. No menu de navegação, clique em Spanner Studio.
  2. Na página do Spanner Studio, clique em Nova guia ou use a guia do editor vazia.
  3. Insira a instrução DDL do DROP PLACEMENT(GoogleSQL, PostgreSQL).

    Por exemplo, execute o seguinte para descartar a tabela de canais 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, posição de soltar europeplacement:

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

Erros de posicionamento de soltura

Se o posicionamento estiver em uso, a operação DROP PLACEMENT vai falhar com uma mensagem de erro como: "Falha na instrução: o posicionamento PLACEMENT_NAME não pode ser descartado porque está em uso pela tabela de posicionamento 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 o posicionamento que você quer descartar.
  2. Siga uma destas instruções:

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

      UPDATE PLACEMENT_TABLE_NAME SET LOCATION = NEW_PLACEMENT_NAME
      WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
      
    • Exclua as linhas de posicionamento com uma instrução DML particionada como esta:

      DELETE FROM PLACEMENT_TABLE_NAME
      WHERE LOCATION = ORIGINAL_PLACEMENT_NAME;
      

      As instruções DML anteriores específicas de posicionamento só funcionam com DML particionada. Elas vão falhar como instruções DML normais. Saiba mais em Limitações. Também é possível usar a API de mutação para mover ou descartar linhas de posicionamento.

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 o posicionamento do esquema do banco de dados. Para saber como conseguir 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 posicionamento

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 vazia do editor.
  3. Insira a instrução DDL do CREATE TABLE (GoogleSQL, PostgreSQL).

    Por exemplo, é possível criar uma tabela Singers que usa uma chave de posicionamento 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 posicionamento 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 posicionamento de uma tabela. Também não é possível adicionar uma chave de posicionamento a uma tabela depois que ela foi criada. No entanto, é possível usar a instrução DDL ALTER TABLE (GoogleSQL, PostgreSQL) para alterar outros campos na tabela, por exemplo, adicionando e removendo colunas de chave que não são de posicionamento.

Excluir uma tabela com uma chave de posicionamento

Antes de excluir uma tabela com uma chave de posicionamento, você precisa:

  1. Exclua todas as linhas da tabela de canais.
  2. Aguarde a aprovação 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 vazia do editor.
  3. Insira a instrução DDL do DROP TABLE (GoogleSQL, PostgreSQL).

    Por exemplo, remova a tabela Singers:

    DROP TABLE Singers;
    

gcloud

Para descartar 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ções

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 vazia do editor.
  3. Insira a instrução DDL do INSERT INTO (GoogleSQL, PostgreSQL).

    Por exemplo, adicione um cantor, Marc Richards, à tabela Singers e particione-a 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-a 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 posicionamento

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 vazia do editor.
  3. Use DML ou mutações para atualizar dados em uma tabela de posicionamento.

    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 posicionamento, 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ções

Console

  1. Crie uma nova partição de instância e um posicionamento, 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 vazia do editor.
  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 o posicionamento para onde você quer mover os 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 em uma tabela de posições

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 vazia do editor.
  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ções

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 vazia do editor.
  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