Nesta página, descrevemos como inserir, atualizar e excluir dados do Cloud Spanner usando instruções de linguagem de manipulação de dados (DML). Execute as instruções DML usando as bibliotecas de cliente, o Console do Google Cloud e a ferramenta de linha de comando gcloud
. É possível executar as instruções DML particionadas usando as bibliotecas de cliente e a ferramenta de linha de comando gcloud
.
Para ver a referência completa da sintaxe de DML, consulte Sintaxe da linguagem de manipulação de dados.
Como usar a DML
A DML é compatível com as instruções INSERT
, UPDATE
e DELETE
no Console do Cloud, na ferramenta de linha de comando gcloud
e nas bibliotecas cliente.
Bloqueio
As instruções DML são executadas dentro de transações de leitura e gravação. Quando o Cloud Spanner lê dados, ele adquire bloqueios de leitura compartilhados em partes limitadas dos intervalos de linha lidos por você. Especificamente, ele adquire esses bloqueios apenas nas colunas acessadas. Os bloqueios podem incluir dados que não correspondem à condição de filtro da cláusula WHERE
.
Quando o Cloud Spanner modifica dados usando instruções DML, ele adquire bloqueios exclusivos nos dados específicos que você está modificando. Além disso, ele adquire bloqueios compartilhados da mesma maneira que quando você lê dados. Se a solicitação incluir intervalos de linhas grandes ou uma tabela inteira, os bloqueios compartilhados poderão impedir que outras transações sejam concluídas em paralelo.
Para modificar os dados da forma mais eficiente possível, use uma cláusula WHERE
que permita que o Cloud Spanner leia somente as linhas necessárias. É possível atingir essa meta com um filtro na chave principal ou na chave de um índice secundário. A cláusula WHERE
limita o escopo dos bloqueios compartilhados e permite que o Cloud Spanner processe a atualização de maneira mais eficiente.
Por exemplo, suponha que um dos músicos da tabela Singers
altere seu nome e você precise atualizar essa informação no banco de dados. É possível executar a instrução DML a seguir, mas ela força o Cloud Spanner a verificar a tabela inteira e adquire os bloqueios compartilhados que cobrem toda a tabela. Como resultado, o Cloud Spanner precisa ler mais dados do que o necessário e as transações simultâneas não conseguem modificar os dados em paralelo:
-- ANTI-PATTERN: SENDING AN UPDATE WITHOUT THE PRIMARY KEY COLUMN
-- IN THE WHERE CLAUSE
UPDATE Singers SET FirstName = "Marcel"
WHERE FirstName = "Marc" AND LastName = "Richards";
Para tornar a atualização mais eficiente, inclua a coluna SingerId
na cláusula WHERE
. A coluna SingerId
é a única coluna de chave primária da tabela Singers
:
-- RECOMMENDED: INCLUDING THE PRIMARY KEY COLUMN IN THE WHERE CLAUSE
UPDATE Singers SET FirstName = "Marcel"
WHERE FirstName = "Marc" AND LastName = "Richards" AND SingerId = 1;
Simultaneidade
O Cloud Spanner executa sequencialmente todas as instruções SQL (SELECT
, INSERT
, UPDATE
e DELETE
) dentro de uma transação. Elas não são executadas simultaneamente. A única exceção é que o Cloud Spanner pode executar várias instruções SELECT
simultaneamente porque elas são operações somente leitura.
Limites de transação
Uma transação que inclui declarações DML tem os mesmos limites que qualquer outra transação. Se você tiver alterações em grande escala, considere o uso de DML particionada.
Se as instruções DML de uma transação resultarem em mais de 20.000 mutações, a instrução DML que faz a transação superar o limite retorna um erro
BadUsage
com uma mensagem sobre muitas mutações.Se as instruções DML de uma transação resultarem em uma transação maior que 100 MB, a instrução DML que faz a transação superar o limite retorna um erro
BadUsage
com uma mensagem sobre a transação exceder o limite de tamanho.
Mutações realizadas usando DML não são retornadas ao cliente. Elas são mescladas na solicitação de confirmação quando ela é confirmada e contam para os limites de tamanho máximo. Mesmo que o tamanho da solicitação de confirmação enviada seja pequeno, a transação ainda poderá exceder o limite de tamanho permitido.
Como executar instruções no Console do Cloud
Siga as etapas a seguir para executar uma instrução DML no Console do Cloud.
Acesse a página Instâncias do Cloud Spanner.
Selecione o projeto na lista suspensa na barra de ferramentas.
Clique no nome da instância que contém seu banco de dados para ir para a página Detalhes da instância.
Na guia Visão geral, clique no nome do seu banco de dados. A página Detalhes do banco de dados é exibida.
Clique em Consulta.
Digite uma instrução DML. Por exemplo, a instrução a seguir adiciona uma nova linha à tabela
Singers
.INSERT Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')
Clique em Executar consulta. O Console do Cloud exibe o resultado.
Como executar instruções com a ferramenta de linha de comando gcloud
Para executar instruções DML, use o comando gcloud spanner databases execute-sql
. O exemplo a seguir adiciona uma nova linha à tabela Singers
.
gcloud spanner databases execute-sql example-db --instance=test-instance \ --sql="INSERT Singers (SingerId, FirstName, LastName) VALUES (1, 'Marc', 'Richards')"
Como modificar dados usando a biblioteca de cliente
Para executar declarações DML com a biblioteca de cliente:
- Crie uma transação de leitura/gravação.
- Chame o método da biblioteca de cliente para a execução da DML e transmita a declaração DML.
- Use o valor de retorno do método de execução da DML para receber o número de linhas inseridas, atualizadas ou excluídas.
O exemplo de código a seguir insere uma nova linha na tabela Singers
.
C++
Use a função ExecuteDml()
para executar uma instrução DML.
C#
Use o método ExecuteNonQueryAsync()
para executar uma instrução DML.
Go
Use o método Update()
para executar uma instrução DML.
Java
Use o método executeUpdate()
para executar uma instrução DML.
Node.js
Use o método runUpdate()
para executar uma instrução DML.
PHP
Use o método executeUpdate()
para executar uma instrução DML.
Python
Use o método execute_update()
para executar uma instrução DML.
Ruby
Use o método execute_update()
para executar uma instrução DML.
O exemplo de código a seguir atualiza a coluna MarketingBudget
da tabela Albums
com base em uma cláusula WHERE
.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
O exemplo de código a seguir exclui todas as linhas da tabela Singers
em que a coluna FirstName
é Alice
.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
O exemplo a seguir usa STRUCT
com parâmetros vinculados para atualizar o LastName
em linhas filtradas por FirstName
e LastName
.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Ler dados gravados na mesma transação
As alterações que você faz usando declarações DML são visíveis para declarações subsequentes na mesma transação. Isso é diferente de usar mutações, em que as alterações não são visíveis até que a transação seja confirmada.
Cloud Spanner verifica as restrições após cada declaração DML. Isso é diferente de usar mutações, em que o Cloud Spanner armazena mutações no cliente até confirmar e verificar as restrições no momento do commit. A avaliação das restrições após cada declaração permite que o Cloud Spanner garanta que os dados que uma instrução DML retorna são consistentes com o esquema.
O exemplo a seguir atualiza uma linha na tabela Singers
e depois executa uma instrução SELECT
para imprimir os novos valores.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Gravar carimbos de data/hora de commit
Use a função PENDING_COMMIT_TIMESTAMP
para gravar o carimbo
de data/hora de confirmação em uma instrução DML. O Cloud Spanner seleciona o carimbo de data/hora de confirmação quando a transação
é confirmada.
O exemplo de código a seguir usa a função PENDING_COMMIT_TIMESTAMP
para gravar o carimbo de data/hora de confirmação na coluna LastUpdateTime
.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Receber o plano de consulta
É possível recuperar um plano de consulta usando o Console do Cloud, as bibliotecas de cliente e a ferramenta de linha de comando gcloud
.
Usar a DML particionada
A DML particionada foi projetada para atualizações e exclusões em massa, particularmente limpeza periódica e preenchimento.
Como executar instruções com a ferramenta de linha de comando gcloud
Para executar uma instrução DML particionada, use o comando gcloud spanner databases execute-sql
com a opção --enable-partitioned-dml
. O exemplo a seguir atualiza linhas na tabela Albums
.
gcloud spanner databases execute-sql example-db \ --instance=test-instance --enable-partitioned-dml \ --sql='UPDATE Albums SET MarketingBudget = 0 WHERE MarketingBudget IS NULL'
Como modificar dados usando a biblioteca de cliente
O exemplo de código a seguir atualiza a coluna MarketingBudget
da tabela Albums
.
C++
Use a função ExecutePartitionedDml()
para executar uma instrução DML particionada.
C#
Use o método ExecutePartitionedUpdateAsync()
para executar uma instrução DML particionada.
Go
Use o método PartitionedUpdate()
para executar uma instrução DML particionada.
Java
Use o método executePartitionedUpdate()
para executar uma instrução DML particionada.
Node.js
Use o método runPartitionedUpdate()
para executar uma instrução DML particionada.
PHP
Use o método executePartitionedUpdate()
para executar uma instrução DML particionada.
Python
Use o método execute_partitioned_dml()
para executar uma instrução DML particionada.
Ruby
Use o método execute_partitioned_update()
para executar uma instrução DML particionada.
O exemplo de código a seguir exclui linhas da tabela Singers
com base na coluna SingerId
.
C++
C#
Go
Java
Node.js
PHP
Python
Ruby
Como usar DML em lote
Caso precise evitar a latência extra incorrida de várias solicitações em série, use a DML em lote para enviar diversas instruções INSERT
, UPDATE
ou DELETE
em uma única transação:
C++
Use a função ExecuteBatchDml()
para executar uma lista de instruções DML.
C#
Use o método connection.CreateBatchDmlCommand()
para criar seu comando em lote. Use o método Add
para adicionar instruções DML. Execute as instruções com o método ExecuteNonQueryAsync()
.
Go
Use o método BatchUpdate()
para executar uma matriz de objetos Statement
DML.
Java
Use o método transaction.batchUpdate()
para executar um ArrayList
de vários objetos Statement
DML.
Node.js
Use transaction.batchUpdate()
para executar uma lista de instruções DML.
PHP
Use executeUpdateBatch()
para criar uma lista de instruções DML. Depois, use commit()
para executar as instruções.
Python
Use transaction.batch_update()
para executar várias strings de instrução DML.
Ruby
Use transaction.batch_update
para executar várias strings de instrução DML.