Como criar, recuperar, atualizar e excluir entidades

Os objetos de dados no Datastore são conhecidos como entidades. Cada uma é categorizada como um tipo específico para fins de consultas. Por exemplo, se você estiver programando um aplicativo de recursos humanos, poderá representar cada funcionário com uma entidade do tipo Employee. Observe que os valores de dados de entidade estão na forma de propriedades. Para mais informações sobre entidades, consulte a documentação sobre caminhos ancestrais e transações.

Como criar entidades e definir propriedades

Você cria uma entidade e define as propriedades chamando o método construtor referente à classe de modelo. Consulte Como criar e usar classes de modelo de entidade para informações sobre como criar uma classe de modelo de entidade.

No exemplo a seguir, veja como invocar um construtor de classe de modelo com argumentos de palavra-chave:

sandy = Account(
    username='Sandy', userid=123, email='sandy@example.com')

Esse código cria um objeto na memória principal do programa. No entanto, a entidade desaparece quando o processo termina. Assim, você também precisa manter a entidade no Datastore chamando put() da seguinte maneira:

sandy_key = sandy.put()

Observe que isso retorna uma chave que você pode usar para recuperar a entidade do Datastore mais tarde.

Defina as propriedades usando uma das seguintes opções:

  • Especifique as propriedades da entidade para o construtor com argumentos de palavra-chave: 
    sandy = Account(
    username='Sandy', userid=123, email='sandy@example.com')
  • Defina propriedades manualmente após a criação da entidade: 
    sandy = Account()
sandy.username = 'Sandy'
sandy.userid = 123
sandy.email = 'sandy@example.com'
  • Use o método de conveniência populate() para definir várias propriedades em uma operação:
    sandy = Account()
sandy.populate(
    username='Sandy',
    userid=123,
    email='sandy@gmail.com')

No entanto, se você optar por definir as propriedades da entidade, os tipos de propriedade (nesse caso, StringProperty e IntegerProperty) aplicarão a verificação de tipo.

Exemplo:

bad = Account(
    username='Sandy', userid='not integer')  # raises an exception
... 
sandy.username = 42  # raises an exception

Como recuperar entidades de chaves

Se você tiver a chave de uma entidade, poderá recuperar a entidade do Datastore:

sandy = sandy_key.get()

Os métodos de chave kind() e id() recuperam o tipo e o identificador da entidade da chave:

kind_string = sandy_key.kind()  # returns 'Account'
ident = sandy_key.id()  # returns '2'

Você também pode usar a chave de uma entidade para receber uma string codificada adequada para incorporação em um URL:

url_string = sandy_key.urlsafe()

Isso produz um resultado como agVoZWxsb3IPCxIHQWNjb3VudBiZiwIM, que pode ser usado posteriormente para reconstruir a chave e recuperar a entidade original:

sandy_key = ndb.Key(urlsafe=url_string)
sandy = sandy_key.get()

Observe que a string segura para URL parece criptográfica, mas não é criptografada. Ela pode ser facilmente decodificada para recuperar o tipo e o identificador da entidade original:

key = Key(urlsafe=url_string)
kind_string = key.kind()
ident = key.id()

Se você usar essas chaves seguras para URL, não use dados confidenciais (por ex., endereços de e-mail) como identificadores de entidade. Uma possível solução seria usar um hash dos dados confidenciais como identificador. Isso impede que terceiros, que podem ver as chaves criptografadas, usem-nas para coletar endereços de e-mail. Porém, isso não os impede de gerar o próprio hash de um endereço de e-mail conhecido e verificar se esse endereço está presente no Datastore.

Como atualizar entidades

Para atualizar uma entidade, recupere-a do Datastore, modifique as propriedades dela e armazene-a novamente:

sandy = key.get()
sandy.email = 'sandy@example.co.uk'
sandy.put()

É possível ignorar o valor retornado por put() neste caso, já que uma chave de entidade não é alterada quando você a atualiza.

Como excluir entidades

Quando uma entidade não for mais necessária, remova-a do Datastore com o método delete() da chave:

sandy.key.delete()

Observe que essa operação ocorre na chave, não na entidade. Ela sempre retorna None.

Como excluir entidades em massa

Se você precisar excluir um grande número de entidades, recomendamos usar o Dataflow para excluir entidades em massa.

Como usar operações em lote

Você pode processar uma coleção de entidades ou chaves em uma única chamada em vez de individualmente em chamadas separadas, por exemplo, dentro de um loop. Isso gera uma única chamada de procedimento remoto (RPC, na sigla em inglês) para o lote, em vez de uma chamada RPC separada para cada entidade.

No código a seguir, mostramos como fazer isso:

list_of_keys = ndb.put_multi(list_of_entities)
list_of_entities = ndb.get_multi(list_of_keys)
ndb.delete_multi(list_of_keys)

No código acima, você passa uma lista de objetos de chave para ndb.get_multi para buscar várias entidades em um lote. ndb.get_multi retorna uma lista de objetos de entidade, com valores None para chaves que não têm uma entidade correspondente no Datastore. Receber as entidades dessa maneira gera menos chamadas ao Datastore para todo o lote. O número de chamadas por lote depende das configurações de tamanho do lote.