Gravações

Esta página lista os tipos de solicitações de gravação que podem ser enviadas ao Bigtable e descreve quando você deve usá-las e quando não deve.

Com a API Bigtable Data e as bibliotecas de cliente, é possível gravar dados programaticamente nas tabelas. O Cloud Bigtable retorna uma resposta ou confirmação para cada gravação.

Cada biblioteca de cliente oferece a capacidade de enviar os seguintes tipos de solicitações de gravação:

Gravações simples
Incrementos e anexos
Gravações condicionais
Gravações em lote

As bibliotecas de cliente do Cloud Bigtable têm um recurso integrado de tentativas inteligentes para gravações simples e em lote, isto é, elas podem solucionar indisponibilidades temporárias sem interromper a tarefa. Por exemplo, se o aplicativo encontrar uma interrupção temporária ou um problema de rede enquanto tenta gravar dados, ele fará novas tentativas automaticamente até que a gravação seja confirmada ou que o prazo final da solicitação seja atingido. Essa resiliência funciona com instâncias de cluster único e replicadas, com roteamento de cluster único ou de vários clusters.

Para operações de gravação em lote e por streaming, use o [conector do Bigtable Beam. Para mais informações, consulte Gravações em lote.

Para saber mais sobre os limites que se aplicam às solicitações de gravação, consulte Cotas e limites.

Há exemplos de cada tipo de gravação disponíveis para cada biblioteca de cliente do Cloud Bigtable.

Para informações sobre como adicionar dados a células agregadas, consulte Valores agregados no momento da gravação (Visualização).

Tipos de gravações e quando usá-las

Todas as solicitações de gravação incluem os seguintes componentes básicos:

O nome da tabela para gravar.
Um código de perfil de aplicativo, que informa ao Cloud Bigtable como encaminhar o tráfego.
Uma ou mais mutações. Uma mutação é formada por quatro elementos:
- Nome do grupo de colunas
- Qualificador de coluna
- Carimbo de data/hora
- Valor que está sendo gravado na tabela

O carimbo de data/hora de uma mutação tem um valor padrão da data e hora atuais, medido como o tempo decorrido desde a época do Unix, 00:00:00 UTC em 1º de janeiro de 1970.

O carimbo de data/hora que você envia ao Bigtable precisa ser um valor em microssegundos com precisão de milissegundos no máximo. Um carimbo de data/hora com precisão de microssegundos, como 3023483279876543, é rejeitado. Neste exemplo, o valor aceitável do carimbo de data/hora é 3023483279876000.

Todas as mutações em uma única solicitação de gravação têm o mesmo carimbo, a menos que você os substitua. É possível definir o carimbo de data/hora de todas as mutações em uma solicitação de gravação para que sejam iguais ou diferentes entre si.

Gravações simples

Você pode gravar uma única linha no Bigtable com uma solicitação MutateRow que inclua o nome da tabela, o código de perfil do aplicativo que será usado, uma chave de linha e até 100.000 mutações para essa linha. para criar um anexo da VLAN de monitoramento. Uma gravação de linha única é atômica. Use esse tipo de gravação quando estiver fazendo várias mutações em uma única linha.

Para amostras de código que demonstram como enviar solicitações de gravação simples, consulte Como executar uma gravação simples.

Quando não usar gravações simples

As gravações simples não são o melhor modo para gravar dados nos seguintes casos de uso:

Ao gravar um lote de dados que terá chaves de linha contíguas . Nesse caso, você deve usar gravações em lote em vez de gravações simples consecutivas, já que é possível aplicar um lote contíguo em uma única chamada de back-end.
Se você quer alta capacidade (linhas por segundo ou bytes por segundo) e não exige baixa latência. As gravações em lote serão mais rápidas neste caso.

Incrementos e anexos

Em muitos casos, usar agregações (Visualização), que permitem atualizar um valor no momento da gravação, é a melhor opção para casos em que você quer aumentar ou incrementar um valor. No entanto, os agregados não oferecem suporte a operações de anexação. Para mais informações, consulte Valores agregados no momento da gravação.

Se você quiser anexar dados a um valor existente ou precisar incrementar um valor numérico existente e não for possível usar agregados, envie uma solicitação ReadModifyWriteRow. Essa solicitação inclui o nome da tabela, o ID do perfil de aplicativo que precisa ser usado, uma chave de linha e um conjunto de regras que serão usadas na gravação dos dados. Cada regra inclui o nome do grupo de colunas, o qualificador de coluna e um valor de anexo ou um valor de incremento.

As regras são aplicadas segundo a ordenação. Por exemplo, se sua solicitação incluir uma solicitação para incrementar o valor de uma coluna em dois, e uma regra posterior na mesma solicitação incrementar a mesma coluna em um, a coluna será incrementada em 3 nessa única gravação atômica. A regra posterior não substitui a regra anterior.

Um valor pode ser incrementado apenas se for codificado como um número inteiro com sinal big-endian de 64 bits. O Cloud Bigtable trata um incremento para um valor vazio ou inexistente como se o valor fosse zero. Solicitações ReadModifyWriteRow são atômicas. Elas não serão repetidas se falharem por qualquer motivo.

Para amostras de código que demonstram como anexar um valor em uma célula, consulte Como incrementar um valor existente.

Quando não usar `ReadModifyWriteRow`

Não envie solicitações ReadModifyWriteRow nas seguintes situações:

Seu caso de uso pode ser processado com agregações (Prévia).
Se você usa um perfil de aplicativo que tem roteamento de vários clusters.
Se você está usando vários perfis de aplicativo de cluster único e enviando gravações que podem entrar em conflito com dados gravados na mesma linha e coluna em outros clusters na instância. Com o roteamento de cluster único, uma solicitação de gravação é enviada para um único cluster e replicada posteriormente.
Se você depende do recurso de tentativas inteligentes fornecido pelas bibliotecas de cliente. Incrementos e anexos não podem ser tentados novamente.
Se você está gravando grandes quantidades de dados e precisa que as gravações sejam concluídas rapidamente. Uma solicitação que lê e, em seguida, modifica uma linha é mais lenta do que uma solicitação de gravação simples. Consequentemente, esse tipo de gravação muitas vezes não é a melhor abordagem em grande escala. Por exemplo, se você quiser contar algo que será numerado em milhões, como visualizações de página, use agregações para atualizar as contagens no momento da gravação. Considere também gravar cada visualização como uma gravação simples em vez de incrementar um valor e, em seguida, usar um job do Dataflow para agregar os dados.

Gravações condicionais

Se quiser verificar uma linha em relação a uma condição e, dependendo do resultado, gravar dados nessa linha, envie uma solicitação CheckAndMutateRow. Esse tipo de solicitação inclui uma chave de linha e um filtro de linha. Um filtro de linha é um conjunto de regras usadas para verificar o valor dos dados atuais. As mutações só serão confirmadas para colunas específicas na linha quando determinadas condições, verificadas pelo filtro, sejam atendidas. Esse processo de análise e gravação é concluído como uma única ação atômica.

Uma solicitação de filtro deve incluir um ou os dois tipos de mutações abaixo:

Mutações verdadeiras, isto é, as mutações que serão aplicadas se o filtro retornar um valor.
Mutações falsas, que são aplicadas se o filtro não retornar nada.

Você pode fornecer até 100.000 mutações de cada tipo, verdadeiras e falsas, em uma única gravação, e você deve enviar pelo menos uma. O Bigtable envia uma resposta quando todas as mutações são concluídas.

Para amostras de código que demonstram como enviar gravações condicionais, consulte Como gravar um valor condicionalmente.

Quando não usar gravações condicionais

Não é possível usar gravações condicionais nos seguintes caso de uso:

Se você está usando um perfil de aplicativo que tem roteamento de vários clusters.
Se você está usando vários perfis de aplicativo de cluster único e enviando gravações que podem entrar em conflito com dados gravados na mesma linha e coluna em outros clusters na instância. Com o roteamento de cluster único, uma solicitação de gravação é enviada para um único cluster e replicada posteriormente.

Gravações em lote

É possível gravar mais de uma linha com uma única chamada usando uma solicitação MutateRows. As solicitações MutateRows contêm um conjunto de até 100.000 entradas que são aplicadas atomicamente. Cada entrada consiste em uma chave de linha e pelo menos uma mutação a ser aplicada à linha. Uma solicitação de gravação em lote pode conter até 100.000 mutações distribuídas por todas as entradas. Por exemplo, uma gravação em lote pode incluir qualquer uma das seguintes permutações:

100.000 entradas com 1 mutação em cada entrada.
1 entrada com 100.000 mutações.
1.000 entradas com 100 mutações cada.

Cada entrada em uma solicitação MutateRows é atômica, mas a solicitação como um todo não é. Se necessário, o Bigtable tentará repetir todas as entradas no lote que não forem bem-sucedidas até que todas as gravações tenham êxito ou o prazo de solicitação seja atingido. Em seguida, ele retorna uma resposta que identifica cada gravação no lote e se a gravação foi bem-sucedida.

Para amostras de código que demonstram como enviar gravações em lote, consulte Como executar gravações em lote.

Quando não usar gravações em lote

Se você está gravando dados em massa em linhas que não são próximas umas das outras. O Bigtable armazena dados lexicograficamente por chave de linha, o equivalente binário à ordem alfabética. Por causa disso, quando as chaves de linha em uma solicitação não são semelhantes entre si, o Bigtable as trata de modo sequencial, e não em paralelo. A capacidade será alta, mas a latência também será alta. Para evitar essa alta latência, use MutateRows quando as chaves de linha forem semelhantes, e o Bigtable for escrever linhas próximas umas das outras. Use MutateRow, ou gravações simples, para linhas que não são próximas umas das outras.
Se você está solicitando várias mutações para a mesma linha. Nesse caso, você observará um desempenho melhor se todas as mutações forem executadas em uma única solicitação de gravação simples. Isso ocorre porque, em uma gravação simples, todas as alterações são confirmadas em uma única ação atômica, mas uma gravação em lote é forçada a serializar mutações para a mesma linha, causando latência.

Controle de fluxo de gravação em lote

Se você enviar as gravações em lote usando uma das opções a seguir, poderá ativar o controle de fluxo de gravação em lote no código.

Quando o controle de fluxo de gravação em lote está ativado para um job do Dataflow, o Bigtable faz automaticamente o seguinte:

Limite o tráfego para evitar sobrecarregar o cluster do Bigtable
Garante que o cluster esteja sob carga suficiente para acionar o escalonamento automático do Bigtable (se ativado), para que mais nós sejam adicionados automaticamente ao cluster quando necessário.

Essas ações combinadas evitam sobrecarga de cluster e falha de job, e você não precisa escalonar o cluster manualmente antes da execução da gravação em lote. Quando o controle de fluxo está ativado, o escalonamento de cluster ocorre durante o job do Dataflow, e não antes dele. Portanto, o job pode levar mais tempo para ser concluído do que se você escalonar o cluster manualmente.

Use um perfil de aplicativo configurado para roteamento de cluster único. A ativação do escalonamento automático do Bigtable para o cluster de destino não é um requisito, mas o escalonamento automático permite aproveitar ao máximo o controle do fluxo de gravação em lote. Use o escalonamento automático do Dataflow como faria com qualquer outro job.

Para saber mais sobre o escalonamento automático do Bigtable, consulte Escalonamento automático. Para entender as políticas de roteamento do perfil de aplicativo, consulte Visão geral dos perfis de aplicativo.

Para um exemplo de código que demonstra como ativar o controle de fluxo de gravação em lote usando o conector do HBase Beam do Bigtable, consulte Como gravar no Bigtable.

Gravar dados em uma visualização autorizada

Para gravar dados em uma visualização autorizada, use uma das seguintes opções:

CLI da gcloud
Cliente Bigtable para Java

As outras bibliotecas de cliente do Bigtable ainda não são compatíveis com o acesso de visualização autorizado.

Ao gravar dados em uma visualização autorizada, você fornece o ID da visualização autorizada, além do ID da tabela.

Todas as gravações em uma visualização autorizada são aplicadas diretamente à tabela subjacente.

Limitações da definição de visualização autorizada

Em uma visualização autorizada, as linhas ou colunas em que é possível gravar dados são limitadas pela definição da visualização autorizada. Em outras palavras, só é possível gravar em linhas e colunas que atendam aos mesmos critérios especificados para a visualização autorizada.

Por exemplo, se a visualização autorizada for definida pelo prefixo de chave de linha examplepetstore1, não será possível gravar dados usando uma chave de linha de examplepetstore2. O início do valor da chave de linha precisa incluir toda a string examplepetstore1.

Da mesma forma, se a visualização autorizada for definida pelo prefixo do qualificador de coluna order-phone, será possível gravar dados usando o qualificador de coluna order-phone123, mas não será possível usar o qualificador de coluna order-tablet.

A solicitação de gravação também não pode referenciar dados que estão fora da visualização autorizada, como quando você está verificando um valor em uma solicitação de gravação condicional.

Para qualquer solicitação que grava ou faz referência a dados fora da visualização autorizada, uma mensagem de erro PERMISSION_DENIED é retornada.

Replicação

Quando um cluster de uma instância de vários clusters recebe uma gravação, essa gravação é imediatamente replicada para os outros clusters na instância.

Atomicidade

Cada solicitação MutateRows enviada a uma instância de vários clusters é confirmada como uma única ação atômica no cluster para onde a solicitação é roteada. Quando a gravação é replicada para os outros clusters na instância, eles também recebem a gravação como uma operação atômica. Os clusters não recebem mutações parciais. uma mutação é bem-sucedida ou falha atomicamente para todas as células que modifica.

Consistência

O tempo necessário para que os dados gravados estejam disponíveis para leituras depende de vários fatores, incluindo o número de clusters em sua instância e o tipo de roteamento usado pelo perfil de aplicativo. Com uma instância de cluster único, os dados podem ser lidos imediatamente, mas se a instância tiver mais de um cluster, o que significa que está usando a replicação, o Bigtable tem consistência eventual. Você pode atingir consistência na leitura das gravações ao rotear solicitações para o mesmo cluster.

É possível criar e usar um token de consistência e chamar CheckConsistency no modo StandardReadRemoteWrites depois de enviar solicitações de gravação. O token verifica a consistência da replicação. Em geral, você cria um token de consistência após o envio de um lote de gravações ou de um determinado intervalo, como uma hora. Em seguida, você pode entregar o token para ser usado por outro processo, como um módulo que faz uma solicitação de leitura, que usa o token para verificar se todos os dados foram replicados antes da tentativa de leitura.

Se você usar um token logo após sua criação, ele pode demorar alguns minutos para verificar a consistência em sua primeira utilização. Essa demora ocorre porque cada cluster verifica todos os outros clusters para garantir que não há mais dados chegando. Depois do uso inicial, ou se você esperar vários minutos para usar o token pela primeira vez, o token será bem-sucedido imediatamente sempre que for usado.

Resolução de conflitos

Cada valor de célula em uma tabela do Bigtable é identificado exclusivamente por quatro tuplas (chave de linha, grupo de colunas, qualificador de coluna, carimbo de data/hora). Consulte Modelo de armazenamento do Bigtable para mais detalhes sobre esses identificadores. No caso raro em que duas gravações com as mesmas quatro tuplas são enviadas para dois clusters diferentes, o Bigtable resolve automaticamente o conflito usando um algoritmo interno de última gravação ganha com base no tempo do lado do servidor. A implementação "última gravação ganha" do Bigtable é determinista e, quando a replicação alcança, todos os clusters têm o mesmo valor para as quatro tuplas.