API App Engine Datastore para serviços legados em pacote

Neste documento, você verá a descrição do modelo de dados para os objetos armazenados no Cloud Datastore, como as consultas são estruturadas usando a API e como as transações são processadas. Para ver o conteúdo do pacote datastore, consulte as referências do pacote datastore.

Essa API é compatível com os ambientes de execução de primeira geração e pode ser usada ao fazer upgrade para os ambientes de execução de segunda geração correspondentes. Se você estiver atualizando para o ambiente de execução do Go 1.12+ do App Engine, consulte o guia de migração para saber mais sobre as opções de migração para serviços incluídos legados.

Entidades

Os objetos no Datastore são conhecidos comoentidades. Uma entidade tem uma ou mais propriedades nomeadas, que podem ter um ou mais valores. Os valores da propriedade pertencem a uma série de tipos de dados, como números inteiros, números de pontos flutuantes, strings, datas e dados binários, entre outros. Uma consulta em uma propriedade com múltiplos valores verifica se algum dos valores satisfaz os critérios de consulta. Isso torna essas propriedades úteis em testes de associação.

Observação: as entidades do Cloud Datastore são schemaless. Ao contrário dos bancos de dados relacionais tradicionais, o Cloud Datastore não requer que todas as entidades de um determinado tipo tenham as mesmas propriedades, ou que todos os valores de uma entidade sejam do mesmo tipo de dados para uma determinada propriedade. Caso seja necessário um esquema formal, o próprio aplicativo será responsável por garantir que as entidades estejam de acordo com ele.

Tipos, chaves e identificadores

Cada entidade do Datastore é de um tipo específico, que categoriza a entidade para fins de consultas. Por exemplo, um aplicativo de recursos humanos pode representar cada funcionário de uma empresa com uma entidade do tipo Employee. Além disso, cada entidade tem a própria chave para garantir a identificação de maneira exclusiva. A chave tem os seguintes componentes:

• Um tipo de entidade
• Um identificador, sendo ele um dos seguintes:
  • uma string de nome da chave;
  • Um código de número inteiro.
• Um caminho ancestral opcional que localiza a entidade na hierarquia do Datastore.

O identificador é atribuído quando a entidade é criada. Por ser parte da chave da entidade, ele é associado permanentemente à entidade e não pode ser alterado. Pode ser atribuído de duas formas:

• O aplicativo especifica a própria string de nome da chave para a entidade.
• O Datastore pode atribuir automaticamente um ID numérico inteiro à entidade.

Como atribuir identificadores

O servidor do ambiente de execução pode ser configurado para gerar códigos automaticamente usando duas políticas distintas de codificação automática:

• A política default gera uma sequência de IDs distribuídos de maneira aparentemente uniforme. Cada código tem até 16 dígitos.
• A política legacy cria uma sequência de IDs inteiros menores, não consecutivos.

Para exibir os IDs de entidade para o usuário e/ou depender da ordem deles, use a alocação manual.

Caminhos ancestrais

As entidades do Cloud Datastore formam um espaço hierarquicamente estruturado, semelhante à estrutura de diretórios de um sistema de arquivos. Ao criar uma entidade, é possível designar outra entidade como mãe e a nova como filha. Ao contrário do que ocorre em um sistema de arquivos, a entidade mãe não precisa existir de verdade. Uma entidade sem mãe é uma entidade raiz. A associação entre uma entidade e a mãe é permanente e não pode ser alterada depois que a entidade é criada. O Cloud Datastore nunca atribuirá o mesmo ID numérico a duas entidades com a mesma mãe ou a duas entidades raiz (sem mãe).

A mãe de uma entidade, a mãe da mãe, e assim por diante são ancestrais dela. A filha, a filha da filha, e assim por diante são descendentes dela. Uma entidade raiz e todos os descendentes pertencem ao mesmo grupo de entidades. A sequência de entidades começando com uma entidade raiz e prosseguindo de pai para filho, levando a uma determinada entidade, constitui o caminho do ancestral dessa entidade. A chave completa que identifica a entidade consiste em uma sequência de pares de identificadores de tipo que especifica o caminho ancestral e termina com os da própria entidade:

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

Para uma entidade raiz, o caminho ancestral está vazio, e a chave consiste unicamente no próprio tipo e identificador da entidade:

[Person:GreatGrandpa]

Esse conceito é ilustrado pelo seguinte diagrama:

Consultas e índices

Além de recuperar entidades do Datastore diretamente por meio das respectivas chaves, um aplicativo pode realizar uma consulta para recuperá-las pelos valores das suas propriedades. A consulta opera em entidades de um certo tipo. Ela especifica filtros nos valores de propriedades, chaves e ancestrais das entidades e retorna zero ou mais entidades como resultados Uma consulta também pode especificar ordens de classificação para colocar os resultados na sequência dos valores de propriedade. Os resultados incluem todas as entidades com pelo menos um valor para cada propriedade nomeada nos filtros e ordens de classificação, em que os valores de propriedade atendam a todos os critérios de filtro especificados. A consulta retorna entidades inteiras, entidades projetadas ou apenas chaves de entidades.

Uma consulta típica inclui o seguinte:

• um tipo de entidade ao qual a consulta é aplicada;
• zero ou mais filtros com base nos valores de propriedade, chaves e ancestrais das entidades;
• zero ou mais ordens de classificação para colocar os resultados em sequência.

Quando executada, a consulta recupera todas as entidades do tipo determinado que satisfaçam a todos os filtros fornecidos, classificadas na ordem especificada. As consultas são executadas no modo de somente leitura.

Observação: para economizar memória e melhorar o desempenho, uma consulta deve especificar sempre que possível um limite para o número de resultados retornados.

Uma consulta também pode incluir um filtro de ancestral, que limita os resultados apenas ao grupo de entidades descendentes de um ancestral especificado. Essa consulta é conhecida como consulta de ancestral Por padrão, ela retorna resultados com consistência forte e garantia de atualização, de acordo com as alterações mais recentes dos dados. Por outro lado, as consultas que não são de ancestral podem abranger todo o Datastore, em vez de um único grupo de entidades, mas têm apenas consistência eventual e podem retornar resultados desatualizados. Caso a consistência forte seja importante para o aplicativo, leve isso em conta ao estruturar os dados. Coloque entidades relacionadas no mesmo grupo, assim elas serão recuperadas com uma consulta de ancestral em vez de não ancestral, para receber mais informações.

O App Engine predefine um índice simples em cada propriedade de uma entidade. Um aplicativo do App Engine pode definir outros índices personalizados em um arquivo de configuração de índice chamado index.yaml. O servidor de desenvolvimento adiciona sugestões a esse arquivo automaticamente quando encontra consultas não executáveis com os índices atuais. É possível ajustar os índices manualmente editando o arquivo antes de fazer upload do aplicativo.

Observação: o mecanismo de consulta baseado em índice é compatível com uma grande variedade de consultas e adequado à maioria dos aplicativos. No entanto, ele não aceita alguns tipos de consulta comuns em outras tecnologias de banco de dados. Especificamente, mesclagens e consultas agregadas não são compatíveis com o mecanismo de consulta do Datastore. Para conhecer as limitações das consultas do Datastore, consulte a página Consultas do Datastore.

Transações

Toda tentativa de inserir, atualizar ou excluir uma entidade ocorre no contexto de uma transação. Uma única transação pode incluir qualquer número dessas operações. Para manter a consistência dos dados, a transação assegura que todas as operações que ela contém sejam aplicadas ao Datastore como uma unidade ou, se alguma das operações falhar, que nenhuma delas seja aplicada.

É possível executar diversas ações em uma entidade dentro de uma única transação. Por exemplo, para incrementar um campo de contador em um objeto, é preciso ler o valor do contador, calcular o novo valor e armazená-lo novamente. Sem uma transação, é possível que outro processo incremente o contador entre o momento em que o valor é lido e o momento em que ele é atualizado, fazendo com que o aplicativo acabe substituindo o valor atualizado. Fazer leitura, cálculo e gravação em uma única transação garante que nenhum outro processo interfira no incremento.

Transações e grupos de entidades

Somente consultas de ancestrais são permitidas dentro de uma transação, ou seja, cada consulta transacional é limitada a um único grupo de entidades. A própria transação é aplicada a várias entidades pertencentes a um único grupo ou, no caso de uma transação entre grupos, a até 25 grupos diferentes de entidades.

O Datastore usa simultaneidade otimista para gerenciar transações. Quando duas ou mais transações tentam alterar o mesmo grupo de entidades ao mesmo tempo, seja atualizando entidades existentes ou criando novas, a primeira transação a ser confirmada será bem-sucedida e as demais falharão. Em seguida, essas outras transações poderão ser repetidas nos dados atualizados. Observe que isso limita o número de gravações simultâneas a serem feitas em qualquer entidade em um determinado grupo.

Transações entre grupos

Uma transação em entidades que pertençam a diferentes grupos é chamada de transação entre grupos (XG, na sigla em inglês). A transação pode ser aplicada no máximo em 25 grupos de entidades e será bem-sucedida desde que nenhuma transação simultânea interfira em qualquer um dos grupos de entidades aos quais ela se aplica. Isso torna a organização de dados mais flexível, porque você não tem obrigação de colocar dados diferentes no mesmo ancestral apenas para executar gravações atômicas neles.

Assim como em uma transação de um único grupo, não é possível executar uma consulta não ancestral em uma transação XG. No entanto, é possível realizar consultas ancestrais em grupos de entidades distintos. As consultas não transacionais (não ancestrais) poderão ver todos, alguns ou nenhum resultado de uma transação confirmada anteriormente. Para mais informações sobre esse problema, consulte Gravações do Datastore e visibilidade de dados. No entanto, as chances de essas consultas não transacionais retornarem os resultados de uma transação XG parcialmente confirmada são maiores do que as de uma transação parcialmente confirmada de um único grupo.

Observação: a primeira leitura de um grupo de entidades em uma transação XG pode informar um erro caso haja um conflito com outras transações que acessam o mesmo grupo. Isso significa que até uma transação XG que executa somente leituras pode falhar com uma exceção de simultaneidade.

Uma transação XG que interfira em um único grupo de entidades tem exatamente o mesmo desempenho e custo de uma transação não XG de um único grupo. Em uma transação XG que interfira em diversos grupos de entidades, as operações têm o mesmo custo de uma transação não XG, mas podem sofrer maior latência.

Gravações no Datastore e visibilidade de dados

Os dados são gravados no Datastore em duas fases:

1. Na fase de Commit, o registro dos dados da entidade é feito nos registros de transação da maioria das réplicas. As réplicas em que o registro não foi feito são marcadas como não tendo registros atualizados.
2. Na fase de Apply, que ocorre de maneira independente em cada réplica, duas ações são realizadas em paralelo:
   • Os dados da entidade são gravados nessa réplica.
   • As linhas de índice para a entidade são gravadas nessa réplica. Isso pode levar mais tempo do que para gravar os dados propriamente ditos.

A operação de gravação retorna imediatamente após a fase de Commit e a fase de Apply ocorre de maneira assíncrona, possivelmente tanto em momentos diferentes em cada réplica quanto com atrasos de algumas centenas de milissegundos ou mais, após a conclusão da fase de Commit. Se ocorrer uma falha durante a fase de confirmação, novas tentativas automáticas serão realizadas. Se as falhas persistirem, o Datastore retornará uma mensagem de erro que o aplicativo receberá como uma exceção. Quando há êxito na fase de Commit e falha na fase de Apply em uma determinada réplica, a Apply é enviada para conclusão dessa réplica em uma das situações abaixo:

• As varreduras periódicas do Datastore verificam se há jobs de confirmação incompletos e os aplicam.
• Determinadas operações, como get, put, delete e consultas de ancestrais, que usam o grupo de entidades afetadas, fazem com que as alterações do commit que ainda não tiverem sido aplicadas sejam concluídas na réplica em que estão sendo executadas antes de prosseguir com a nova operação.

Este comportamento de gravação tem várias implicações sobre como e quando os dados estarão visíveis para o aplicativo em diferentes partes das fases de Commit e Apply:

• Caso uma operação de gravação relate um erro de tempo limite, não será possível determinar o sucesso ou a falha da operação sem tentar ler os dados.
• Como a função get e as consultas de ancestrais do Datastore aplicam modificações pendentes à réplica em que estão sendo executadas, essas operações sempre têm uma visão consistente de todas as transações anteriores bem-sucedidas. Isso significa que uma operação get que procura uma entidade atualizada pela chave correspondente tem a garantia de ver a versão mais recente dessa entidade.
• As consultas não ancestrais retornam resultados desatualizados porque podem estar em execução em uma réplica em que as transações mais recentes ainda não foram aplicadas. Isso ocorre mesmo que tenha sido realizada uma operação com garantia de aplicação das transações pendentes, porque a consulta pode estar em execução em uma réplica diferente da operação anterior.
• O tempo das alterações simultâneas afeta os resultados das consultas não ancestrais. Se a princípio uma entidade satisfaz uma consulta, mas depois é alterada para que não satisfaça mais, ela ainda estará incluída no conjunto de resultados da consulta caso as alterações não tenham sido aplicadas aos índices na réplica em que a consulta foi executada.=

Estatísticas do Datastore

O Datastore mantém estatísticas sobre os dados armazenados de um aplicativo, como o número de determinados tipos de entidades existentes ou o espaço usado por certos tipos de valores de propriedade. É possível ver essas estatísticas na página Painel do Datastore do console do Google Cloud. Também é possível usar a API Datastore para acessar esses valores de maneira programática a partir do aplicativo consultando entidades especialmente nomeadas. Consulte Estatísticas do Datastore no Go 1.11 para saber mais.

Exemplo do Datastore em Go 1.11

No Go, as entidades do Datastore são criadas a partir de valores struct. Os campos da estrutura tornam-se as propriedades da entidade. Para criar uma nova entidade, configure o valor que você quer armazenar, crie uma chave e transmita ambos para datastore.Put(). Para atualizar uma entidade existente é só realizar outro Put() usando a mesma chave. Para recuperar uma entidade do Datastore, primeiro configure um valor dentro do qual a entidade será desempacotada. Depois, transmita uma chave e um ponteiro desse valor para datastore.Get().

Este exemplo armazena e recupera alguns dados do Datastore:

import (
	"fmt"
	"net/http"
	"time"

	"google.golang.org/appengine"
	"google.golang.org/appengine/datastore"
	"google.golang.org/appengine/user"
)

type Employee struct {
	Name     string
	Role     string
	HireDate time.Time
	Account  string
}

func handle(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)

	e1 := Employee{
		Name:     "Joe Citizen",
		Role:     "Manager",
		HireDate: time.Now(),
		Account:  user.Current(ctx).String(),
	}

	key, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "employee", nil), &e1)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	var e2 Employee
	if err = datastore.Get(ctx, key, &e2); err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	fmt.Fprintf(w, "Stored and retrieved the Employee named %q", e2.Name)
}

Consulte a Referência do Cloud Datastore para mais detalhes.