A API de armazenamento de dados representa as entidades como instâncias das classes de modelo. Os métodos de uma instância de modelo criam, atualizam e excluem a entidade. As entidades podem ser obtidas do armazenamento de dados como instâncias de modelo usando consultas ou chaves.
As instâncias das classes Model (e Expando) representam entidades do armazenamento de dados. Para criar uma nova entidade de um tipo específico, o aplicativo chama o construtor da classe de modelo correspondente ao tipo.
|
pet = Pet(name="Fluffy",
type="cat",
owner=users.get_current_user())
A nova entidade não é criada no armazenamento de dados até a instância ser "colocada" pela primeira vez, seja por meio de chamada ao método put() da instância ou passando a instância à função db.put().
pet.put() db.put(pet)
Se uma instância já foi armazenada antes, o método put() atualiza a entidade existente.
As consultas retornam resultados como instâncias de modelo. Estas instâncias podem ser modificadas e colocadas de volta no armazenamento de dados.
if users.get_current_user():
user_pets = db.GqlQuery("SELECT * FROM Pet WHERE owner = :1",
users.get_current_user())
for pet in user_pets:
pet.spayed_or_neutered = True
db.put(user_pets)
O armazenamento de dados pode executar consultas entre entidades de um determinado tipo. Uma consulta pode filtrar resultados utilizando condições que devem ser atendidas pelos valores de propriedade da entidade e retornar os resultados classificados segundo os valores de propriedade. Uma consulta também pode limitar o escopo a entidades com determinada condição ancestral; consulte Chaves e grupos de entidade.
Para obter uma descrição completa do funcionamento das consultas, incluindo diversas limitações das consultas, veja Consultas e índices.
A API de armazenamento de dados fornece duas interfaces para a execução de consultas em propriedades de entidade: Query, uma interface que prepara as consultas utilizando métodos em um objeto query, e GqlQuery, uma interface que utiliza GQL, uma linguagem de consulta semelhante a SQL.
O método all() de uma classe Model (ou Expando) retorna um objeto Query que representa uma consulta de todas as entidades do tipo correspondente. O aplicativo prepara a consulta chamando os métodos filter(), order() e ancestor() do objeto.
class Story(db.Model):
title = db.StringProperty()
date = db.DateTimeProperty()
query = Story.all()
query.filter('title =', 'Foo')
query.order('-date')
query.ancestor(key)
# These methods can be chained together on one line.
query.filter('title =', 'Foo').order('-date').ancestor(key)
O construtor da classe GqlQuery assume uma string de consulta GQL e vinculações de parâmetro opcionais. A string de consulta especifica o tipo e os filtros, ordens de classificação e condições precedentes. A string de consulta também pode incluir um limite e um deslocamento do resultado.
# Parameters can be bound with positional arguments.
query = db.GqlQuery("SELECT * FROM Story WHERE title = :1 "
"AND ANCESTOR IS :2 "
"ORDER BY date DESC",
'Foo', key)
# Or, parameters can be bound with keyword arguments.
query = db.GqlQuery("SELECT * FROM Story WHERE title = :title "
"AND ANCESTOR IS :parent "
"ORDER BY date DESC",
title='Foo', parent=key)
# String, number and Boolean values can be literal values in the string.
query = db.GqlQuery("SELECT * FROM Story WHERE title = 'Foo' "
"AND ANCESTOR IS :parent "
"ORDER BY date DESC",
parent=key)
O método da classe gql() de uma classe Model também prepara um objeto GqlQuery a partir de uma string. Esta é a string de consulta GQL omitindo-se SELECT * FROM Model, pois esta parte é implícita.
query = Story.gql("WHERE title = :title "
"AND ANCESTOR IS :parent "
"ORDER BY date DESC",
title='Foo', parent=key)
As vinculações de parâmetro podem ser revinculadas a novos valores utilizando o método bind(). Um aplicativo pode reutilizar um objeto GqlQuery por meio da revinculação de parâmetros e reexecução da consulta.
Os objetos Query e GqlQuery não executam a consulta até o aplicativo tentar acessar os resultados. Quando o aplicativo acessa os resultados, a consulta é executada e os resultados são carregados na memória como instâncias da classe de modelo da consulta. As duas classes da consulta fornecem duas maneiras de executar a consulta e acessar os resultados: o método fetch() e a interface do iterador.
O método fetch() assume um número máximo de resultados para obter (o limite) e um número de resultados opcional para pular (o deslocamento). O método executa a consulta e obtém os resultados até atingir o limite ou não existirem mais resultados. Depois de carregar os resultados na memória, ele pula o deslocamento, se houver um especificado, e retorna os resultados solicitados como uma lista de instâncias de modelo. A consulta completa é executada para cada chamada para fetch().
Observação: O deslocamento não afeta o número de resultados obtidos do armazenamento de dados. Todos os resultados até o limite são obtidos e armazenados na memória. O deslocamento afeta somente o que é retornado pelo método fetch().
results = query.fetch(10) for result in results: print "Title: " + result.title
O limite e o deslocamento fornecidos ao método fetch() substituem qualquer limite e deslocamento especificados em uma string de consulta GQL.
Se o objeto query for usado como um iterador, a consulta é executada sem limite ou deslocamento, os resultados são carregados na memória e o valor retornado é um iterador sobre os resultados. O iterador produz instâncias da classe de modelo.
for result in query: print "Title: " + result.title
Observação: O armazenamento de dados retorna um máximo de 1000 resultados em resposta a uma consulta, independente do limite e do deslocamento usados para obter os resultados. Os 1000 resultados incluem qualquer resultado pulado devido a um deslocamento. Assim, uma consulta com mais de 1000 resultados utilizando um deslocamento de 100 retornará 900 resultados.
Depois de armazenada no armazenamento de dados, a entidade tem uma chave exclusiva. Os valores das chaves são representados na API como instâncias da classe Key. O método put() de uma instância de modelo e a função db.put() retornam a chave da entidade armazenada. Após uma instância de modelo ser armazenada pela primeira vez, o seu método key() retorna a chave da instância.
entity.put() key = entity.key() # ... entity = db.get(key)
Um uso comum do valor de Key é armazená-lo como o valor de uma propriedade em outra entidade. A classe de propriedade de modelo ReferenceProperty fornece um meio automático de fazer e desfazer referência a instâncias de modelo como chaves. Uma instância de modelo pode ser atribuída diretamente a uma ReferenceProperty e o valor utilizado será sua chave.
class PetOwner(db.Model): name = db.StringProperty() class Pet(db.Model): name = db.StringProperty() owner = db.ReferenceProperty(PetOwner) owner = PetOwner(name="Albert") pet = Pet(name="Fluffy", owner=owner) # This is equivalent: pet = Pet(name="Fluffy", owner=owner.key())
De forma semelhante, o valor de ReferenceProperty acessado através de uma classe property funciona como sua instância. A entidade de dados é obtida automaticamente e apenas no momento em que será usada.
pets = db.GqlQuery("SELECT * FROM Pet WHERE name = :1", "Fluffy")
pet = pets.get()
owner_name = pet.owner.name
Os valores de chave armazenados sem o modelo ReferenceProperty, como no caso de uma propriedade dinâmica Expando ou um elemento ListProperty, não têm comportamento automático de desfazer a referência.
A função db.get() obtém uma entidade do armazenamento de dados para uma chave (ou lista de chaves).
As chaves podem ser codificadas como strings para serem passadas fora do aplicativo. Para converter uma chave codificada em string para um objeto Key novamente, o aplicativo passa a string para o construtor Key.
obj = MyModel(name="Foo")
self.response.write('<a href="/view?key=%s">%s</a>' % (str(obj.key()),
obj.name()))
# ...
key_name = self.request.get('key')
obj = db.get(db.Key(key_name))
Observação: A codificação de Key em uma string é opaca, mas não criptografada. Se seu aplicativo necessitar de chaves impossíveis de serem deduzidas, criptografe a chave codificada em string antes de enviá-la ao usuário.
Um aplicativo pode excluir uma entidade do armazenamento de dados utilizando uma instância de modelo ou uma chave. O método delete() da instância do modelo exclui a entidade correspondente do armazenamento de dados. A função delete() assume uma chave ou lista de chaves e exclui a entidade (ou entidades) do armazenamento de dados.
q = db.GqlQuery("SELECT * FROM Message WHERE create_date < :1", earliest_date)
results = q.fetch(10)
for result in results:
result.delete()
# or...
q = db.GqlQuery("SELECT * FROM Message WHERE create_date < :1", earliest_date)
results = q.fetch(10)
db.delete(results)
A exclusão de uma entidade não altera qualquer valor de chave no armazenamento de dados que faça referência à entidade. Ao tentar desfazer a referência de um valor de chave de uma entidade excluída, o aplicativo deve utilizar db.get() para fazê-lo e testar o valor retornado antes de acessar as propriedades.
A exclusão de uma entidade que é ancestral de outras entidades não afeta as outras entidades. Enquanto o aplicativo não depender da existência da entidade ancestral para construir chaves para as entidades descendentes, ele ainda poderá acessar as descendentes.