Nesta página, descrevemos como fazer leituras no Cloud Spanner fora do contexto de transações somente leitura e de leitura e gravação. Isso significa que se uma das seguintes condições se aplicar, leia a página Transações em vez desta:
Se você precisa gravar, dependendo do valor de uma ou mais leituras, precisa executar a leitura como parte de uma transação de leitura e gravação. Leia mais sobre transações de leitura e gravação.
Se você estiver fazendo várias chamadas de leitura que exigem uma visão consistente dos dados, precisará executar as leituras como parte de uma transação somente leitura. Leia mais sobre transações somente leitura.
Se você precisar fazer uma única chamada de leitura ou ler dados em paralelo, e não precisar gravar, continue lendo esta página.
Tipos de leitura
O Cloud Spanner permite determinar o nível de atualização dos dados quando lidos por meio dos dois tipos de leitura oferecidos:
- Uma leitura forte é uma leitura em um carimbo de data/hora atual. Esse tipo de leitura garante que todos os dados que foram confirmados até o início dela serão vistos. O padrão do Cloud Spanner é usar leituras fortes para atender a solicitações de leitura.
- Uma leitura desatualizada é uma leitura em um carimbo de data/hora no passado. Se o aplicativo for sensível à latência, mas tolerante a dados desatualizados, as leituras desatualizadas representarão benefícios no desempenho.
Como escolher limites de carimbos de data/hora
Para escolher o tipo de leitura que você quer, defina um limite de carimbo de data/hora na solicitação de leitura. Use as seguintes práticas recomendadas ao escolher um limite de carimbo de data/hora:
Escolha leituras fortes sempre que possível. Esse é o limite de carimbo de data/hora padrão para as leituras do Cloud Spanner, inclusive de transações somente leitura. As leituras fortes têm garantia de visualização dos efeitos de todas as transações que tenham sido confirmadas antes do início da operação, independentemente de qual réplica receba a leitura. Por causa disso, as leituras fortes tornam os aplicativos mais confiáveis e simplificam o código deles. Saiba mais sobre as propriedades de consistência do Cloud Spanner em TrueTime e consistência externa.
Se a latência tornar as leituras fortes inviáveis em algumas situações, use leituras desatualizadas (inatividade limitada ou inatividade exata) para melhorar o desempenho em locais em que não é necessário que as leituras sejam as mais recentes possíveis. Como descrito na página sobre replicação no Cloud Spanner, 15 segundos é um valor de inatividade razoável para ter um bom desempenho.
Métodos de leitura única
O Cloud Spanner é compatível com métodos de leitura única (ou seja, uma leitura fora do contexto de uma transação) em um banco de dados para:
- executar a leitura como uma declaração de consulta SQL ou usar a API de leitura do Cloud Spanner;
- realizar uma leitura forte de uma única linha ou de várias linhas em uma tabela;
- realizar uma leitura desatualizada de uma única linha ou várias linhas em uma tabela;
- ler uma única linha ou várias linhas em um índice secundário.
As seções abaixo descrevem como usar métodos de leitura usando as Bibliotecas de Cliente do Cloud para a API Cloud Spanner.
Executar uma consulta
Veja a seguir como executar uma instrução de consulta SQL em um banco de dados.
C++
Use ExecuteQuery()
para executar uma instrução de consulta SQL em um banco de dados.
C#
Use ExecuteReaderAsync()
para consultar o banco de dados.
Go
Use Client.Single().Query
para consultar o banco de dados.
Java
Use ReadContext.executeQuery
para consultar o banco de dados.
Node.js
Use Database.run
para consultar o banco de dados.
PHP
Use Database::execute
para consultar o banco de dados.
Python
Use Database.execute_sql
para consultar o banco de dados.
Ruby
Use Client#execute
para consultar o banco de dados.
No SQL, consulte as referências Sintaxe de consulta e Funções e operadores ao criar uma instrução SQL.
Executar uma leitura forte
O exemplo a seguir mostra como executar uma leitura forte de zero ou mais linhas de um banco de dados.
C++
O código para ler dados é o mesmo do exemplo anterior para consultar o Cloud Spanner por meio da execução de uma consulta SQL.
C#
O código para ler dados é o mesmo do exemplo anterior para consultar o Cloud Spanner por meio da execução de uma consulta SQL.
Go
Use Client.Single().Read
para ler as linhas do banco de dados.
O exemplo usa AllKeys
para definir um conjunto de chaves ou intervalos de chaves a serem lidos.
Java
Use ReadContext.read
para ler as linhas do banco de dados.
O exemplo usa KeySet
para definir um conjunto de chaves ou intervalos de chaves a serem lidos.
Node.js
Use Table.read
para ler as linhas do banco de dados.
O exemplo usa keySet
para definir um conjunto de chaves ou intervalos de chaves a serem lidos.
PHP
Use Database::read
para ler as linhas do banco de dados.
O exemplo usa keySet
para definir um conjunto de chaves ou intervalos de chaves a serem lidos.
Python
Use Database.read
para ler as linhas do banco de dados.
O exemplo usa KeySet
para definir um conjunto de chaves ou intervalos de chaves a serem lidos.
Ruby
Use Client#read
para ler as linhas do banco de dados.
Executar uma leitura desatualizada
No código de amostra a seguir, explicamos como executar uma leitura desatualizada de zero ou mais linhas de um banco de dados usando um limite de carimbo de data/hora inatividade exata. Para receber instruções de como executar uma leitura desatualizada usando um limite de carimbo de data/hora de inatividade limitada, veja a observação após o código de amostra. Consulte Limites de carimbo de data/hora para mais informações sobre os diferentes tipos de limites de carimbos de data/hora disponíveis.
C++
Use ExecuteQuery()
com MakeReadOnlyTransaction()
e Transaction::ReadOnlyOptions()
para executar uma leitura desatualizada.
C#
Use o método BeginReadOnlyTransactionAsync
em um connection
com um valor TimestampBound.OfExactStaleness()
especificado para consultar o banco de dados.
Go
Use Client.ReadOnlyTransaction().WithTimestampBound()
e especifique um valor ExactStaleness
para executar uma leitura de linhas do banco de dados usando um limite de carimbo de data e hora de exatidão.
O exemplo usa AllKeys
para definir um conjunto de chaves ou intervalos de chaves a serem lidos.
Java
Use o método read
de um ReadContext
que tenha um TimestampBound.ofExactStaleness()
especificado para executar uma leitura de linhas do banco de dados usando um limite de carimbo de data e hora com inatividade exata.
O exemplo usa KeySet
para definir um conjunto de chaves ou intervalos de chaves a serem lidos.
Node.js
Use Table.read
com a opção exactStaleness
para executar uma leitura de linhas do banco de dados usando um limite de carimbo de data e hora de inatividade exata.
O exemplo usa keySet
para definir um conjunto de chaves ou intervalos de chaves a serem lidos.
PHP
Use Database::read
com um valor exactStaleness
especificado para executar uma leitura de linhas do banco de dados usando um limite de carimbo de data e hora de inatividade exata.
O exemplo usa keySet
para definir um conjunto de chaves ou intervalos de chaves a serem lidos.
Python
Use o método read
de um Database
snapshot
que tenha um exact_staleness
especificado para executar uma leitura de linhas do banco de dados usando um limite de carimbo de data e hora com inatividade exata.
O exemplo usa KeySet
para definir um conjunto de chaves ou intervalos de chaves a serem lidos.
Ruby
Use o método read
de um de snapshot Client
que tenha um valor de staleness
especificado (em segundos) para executar uma leitura de linhas do banco de dados usando um limite de carimbo de data/hora de inatividade exata.
Executar uma leitura usando um índice
Veja a seguir como ler zero ou mais linhas de um banco de dados usando um índice.
C++
Use a função Read()
para realizar uma leitura usando um índice.
C#
Execute uma consulta que especifica explicitamente um índice a ser usado para fazer leituras de dados:
Go
Use Client.Single().ReadUsingIndex
para ler linhas do banco de dados usando um índice.
Java
Use ReadContext.readUsingIndex
para ler linhas do banco de dados usando um índice.
Node.js
Use Table.read
e especifique o índice na consulta para ler linhas do banco de dados usando um índice.
PHP
Use Database::read
e especifique o índice para ler linhas do banco de dados usando um índice.
Python
Use Database.read
e especifique o índice para ler linhas do banco de dados usando um índice.
Ruby
Use Client#read
e especifique o índice para ler linhas do banco de dados usando um índice.
Ler dados em paralelo
Ao ler ou consultar grandes volumes de dados do Cloud Spanner, pode ser útil dividir a consulta em partes menores ou partições e usar várias máquinas para buscar as partições em paralelo.
Realize qualquer operação da API de leitura em paralelo usando as bibliotecas de cliente do Cloud Spanner. No entanto, é possível particionar apenas consultas SQL em que o primeiro operador no plano de execução da consulta seja distributed union. Para visualizar o plano de execução da consulta de uma consulta SQL específica, siga as instruções em Práticas recomendadas de SQL.
Depois de receber o plano de execução da consulta, verifique se o primeiro operador é distributed union.
C++
Este exemplo busca partições de uma consulta SQL da tabela Singers
e
executa a consulta sobre cada partição por meio das seguintes etapas:
- Criar uma transação em lote do Cloud Spanner.
- Gerar partições da consulta. Dessa maneira, as partições podem ser distribuídas para vários trabalhadores.
- Recuperar os resultados da consulta para cada partição.
C#
Este exemplo busca partições de uma consulta SQL da tabela Singers
e
executa a consulta sobre cada partição por meio das seguintes etapas:
- Criar uma transação em lote do Cloud Spanner.
- Gerar partições da consulta. Dessa maneira, as partições podem ser distribuídas para vários trabalhadores.
- Recuperar os resultados da consulta para cada partição.
Go
Este exemplo busca partições de uma consulta SQL da tabela Singers
e
executa a consulta sobre cada partição por meio das seguintes etapas:
- Criar um cliente do Cloud Spanner e uma transação.
- Gerar partições da consulta. Dessa maneira, as partições podem ser distribuídas para vários trabalhadores.
- Recuperar os resultados da consulta para cada partição.
Java
Este exemplo busca partições de uma consulta SQL da tabela Singers
e
executa a consulta sobre cada partição por meio das seguintes etapas:
- Criar um cliente de lote do Cloud Spanner e uma transação.
- Gerar partições da consulta. Dessa maneira, as partições podem ser distribuídas para vários trabalhadores.
- Recuperar os resultados da consulta para cada partição.
Node.js
Este exemplo mostra como buscar partições de uma consulta SQL da tabela Singers
e, em seguida, executar a consulta em cada partição.
Esta parte do código gera partições:
Em seguida, esta parte do código executa a consulta em cada partição:
PHP
Este exemplo busca partições de uma consulta SQL da tabela Singers
e
executa a consulta sobre cada partição por meio das seguintes etapas:
- Criar um cliente do Cloud Spanner e um lote.
- Gerar partições da consulta. Dessa maneira, as partições podem ser distribuídas para vários trabalhadores.
- Recuperar os resultados da consulta para cada partição.
Python
Este exemplo busca partições de uma consulta SQL da tabela Singers
e
executa a consulta sobre cada partição por meio das seguintes etapas:
- Criar um cliente do Cloud Spanner e uma transação em lote.
- Gerar partições da consulta. Dessa maneira, as partições podem ser distribuídas para vários trabalhadores.
- Recuperar os resultados da consulta para cada partição.
Ruby
Este exemplo busca partições de uma consulta SQL da tabela Singers
e
executa a consulta sobre cada partição por meio das seguintes etapas:
- Criar um cliente em lote do Cloud Spanner.
- Criar partições da consulta. Dessa maneira, as partições podem ser distribuídas para vários trabalhadores.
- Recuperar os resultados da consulta para cada partição.