Observação: é altamente recomendável a desenvolvedores que criam novos aplicativos usar a biblioteca de cliente NDB, porque ela oferece diversos benefícios em comparação com esta biblioteca de cliente, como armazenamento em cache automático de entidades por meio da API Memcache. Se você estiver usando a antiga biblioteca de cliente DB, leia o Guia de migração de DB para NDB.
A classe Query
representa uma consulta para recuperar entidades do
App Engine Datastore. Consulte também a classe relacionada
GqlQuery
, que define as consultas usando GQL, uma linguagem de consulta semelhante a SQL.
Query
é definido no módulo google.appengine.ext.db
.
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.
Introdução
Um aplicativo cria um objeto de consulta para um determinado tipo de entidade ao
chamar o
construtor Query
diretamente
class Song(db.Model): title = db.StringProperty() composer = db.StringProperty() date = db.DateTimeProperty() q = db.Query(Song)
ou o método de classe
all()
da classe de modelo do tipo:
q = Song.all()
Sem mais modificações, a instância resultante da classe
Query
recupera todas as entidades existentes do tipo especificado.
As chamadas de método no objeto podem ser usadas para personalizar a consulta com
critérios de filtro adicionais, condições de ancestral e ordens de classificação:
q.filter('title =', 'Imagine') q.ancestor(ancestor_key) q.order('-date')
Por conveniência, todos esses métodos retornam o próprio objeto de consulta para que possam ser colocados em cascata em uma única instrução:
q.filter('title =', 'Imagine').ancestor(key).order('-date')
O aplicativo pode, então, executar a consulta e acessar os resultados de uma das seguintes maneiras:
-
Trate o objeto de consulta como iterável, para processar entidades correspondentes uma por vez:
for song in q: print song.title
Isso chama implicitamente o método
run()
da consulta para gerar as entidades correspondentes. Sendo assim, é equivalente afor song in q.run(): print song.title
é possível definir um limite para o número de resultados a serem processados com o argumento de palavra-chave
limit
:for song in q.run(limit=5): print song.title
A interface do iterador não armazena em cache os resultados. Portanto, criar um novo iterador a partir do objeto de consulta reitera a mesma consulta desde o início.
-
Chame o método
get()
da consulta para receber a primeira entidade correspondente encontrada no Datastore:song = q.get() print song.title
-
Chame o método
fetch()
da consulta para receber uma lista de todas as entidades correspondentes até um número especificado de resultados:results = q.fetch(limit=5) for song in results: print song.title
Assim como com
run()
, o objeto de consulta não armazena em cache os resultados. Portanto, chamarfetch()
uma segunda vez reedita a mesma consulta.Observação: raramente será necessário usar esse método. Em quase todas as ocasiões, é recomendável utilizar
run()
.
Construtor
O construtor da classe Query
é definido da seguinte maneira:
- class Query (model_class=None, model_class=False, model_class=None, model_class=None, model_class=None, model_class=False)
-
Cria uma instância da classe
Query
para recuperar entidades do App Engine Datastore.Sem modificação adicional, o objeto de consulta resultante recuperará todas as entidades existentes do tipo especificado por
model_class
. Os métodos de instânciafilter()
,ancestor(),
eorder()
podem ser usados para personalizar a consulta com critérios de filtro adicionais, condições de ancestral e ordens de classificação.Argumentos
- model_class
- A classe Model (ou Expando) que representa o tipo de entidade ao qual a consulta se aplica.
- keys_only Se
- true
true
, retornará apenas chaves em vez de entidades completas. As consultas somente de chaves são mais rápidas e mais baratas do que aquelas que retornam entidades completas. - cursor
- Posição do cursor de onde a consulta será retomada.
- namespace
- Namespace a ser usado para a consulta.
- projection
- Lista ou tupla de nomes de propriedades a serem retornados. Somente entidades com as propriedades especificadas serão retornadas. Se não especificado, entidades inteiras serão retornadas por padrão.
As consultas de projeção
são mais rápidas e mais baratas do que aquelas que retornam entidades completas.
Observação: especificar este parâmetro pode alterar os requisitos de índice da consulta.
- distinct
- No caso de Consultas de projeção, distinct=True especifica que somente resultados totalmente exclusivos serão retornados em um conjunto de resultados. Isso retornará apenas o primeiro resultado de entidades com os mesmos valores das propriedades projetadas.
- True
- Retorna somente o primeiro resultado para cada conjunto distinto de valor para propriedades na projeção.
- Falso
- Todos os resultados são retornados.
Métodos da instância
As instâncias de classe Query
têm os seguintes métodos:
- filter (property_operator, property_operator)
-
Adiciona um filtro de propriedade à consulta. A consulta retornará apenas entidades com propriedades que satisfazem a todos os filtros.
Argumentos
- property_operator
- String que consiste em um nome de propriedade e um operador de comparação
opcional (
=
,!=
,<
,<=
,>
,>=
,IN
), separados por um espaço: por exemplo,'age
>'
. Se apenas um nome de propriedade for especificado sem um operador de comparação, o filtro fará a comparação de igualdade (=
) por padrão. - value
- Valor a comparar com o valor da propriedade. Exemplo:
q.filter('height >', 42).filter('city =', 'Seattle') q.filter('user =', users.get_current_user())
O valor de comparação especificado precisa ser do mesmo tipo de valor que o da propriedade que está sendo comparada.
- ancestor (ancestor)
-
Adiciona um filtro ancestral à consulta. A consulta retornará apenas entidades com o ancestral especificado.
Argumento
- ancestor
- Entidade ou chave ancestral.
- order (property)
-
Adiciona uma ordem de classificação à consulta. Se mais de uma ordem de classificação for adicionada, elas serão aplicadas na ordem especificada.
Argumento
- property
- String que fornece o nome da propriedade na qual classificar, opcionalmente
precedido por um hífen (
-
) para especificar a ordem decrescente. Omitir o hífen especifica a ordem crescente por padrão. Exemplo:# Order alphabetically by last name: q.order('last_name') # Order by height, tallest to shortest: q.order('-height')
- projection ()
-
Retorna a tupla de propriedades na projeção ou
None
. - is_keys_only ()
-
Retorna um valor booleano indicando se a consulta é somente de chaves.
- run (read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY)
-
Retorna um iterável para loop nos resultados da consulta. Isso permite que você especifique a operação da consulta com configurações de parâmetro e acesse os resultados de maneira iterativa:
- Recupera e descarta o número de resultados especificado pelo argumento
offset
. - Recupera e retorna até o número máximo de resultados especificado pelo argumento
limit
.
O desempenho do loop, portanto, se ajusta à soma de
offset
+limit
. Se você souber quantos resultados quer recuperar, deverá sempre definir um valorlimit
explícito.Esse método usa pré-busca assíncrona para melhorar o desempenho. Por padrão, ele recupera seus resultados do Datastore em pequenos lotes, permitindo que o aplicativo interrompa a iteração e evite o recebimento de mais resultados do que o necessário.
Dica: para recuperar todos os resultados disponíveis quando o número é desconhecido, defina
batch_size
como um valor grande, por exemplo,1000
.Dica: se você não precisa alterar os valores de argumento padrão, basta usar o objeto de consulta diretamente como um iterável para controlar o loop. Isso implicitamente chama
run()
com argumentos padrão.Argumentos
- read_policy
- Política de leitura que especifica o nível desejado de consistência de dados:
- STRONG_CONSISTENCY
- Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
- EVENTUAL_CONSISTENCY
- Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.
Observação: consultas globais (não ancestrais) ignoram esse argumento.
- deadline
- Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, para retornar uma resposta mais rápida ao usuário, repita a operação, tente uma operação diferente ou adicione essa operação a uma fila de tarefas.
- offset
- Número de resultados a pular antes de retornar o primeiro.
- limit
- Número máximo de resultados a serem retornados.
Se omitido ou definido como
None
, todos os resultados disponíveis serão recuperados por padrão. - batch_size
- Número de resultados a tentar recuperar por lote. Se
limit
for definido, o padrão será o limite especificado. Caso contrário, o padrão será20
. - keys_only Se
- true
true
, retornará apenas chaves em vez de entidades completas. As consultas somente de chaves são mais rápidas e mais baratas do que aquelas que retornam entidades completas. - projection
- Lista ou tupla de nomes de propriedades a serem retornados. Somente entidades com as propriedades especificadas serão retornadas. Se não especificado, entidades inteiras serão retornadas por padrão.
As consultas de projeção
são mais rápidas e mais baratas do que aquelas que retornam entidades completas.
Observação: especificar este parâmetro pode alterar os requisitos de índice da consulta.
- start_cursor
- Posição do cursor em que a consulta será iniciada.
- end_cursor
- Posição do cursor em que a consulta será encerrada.
- Recupera e descarta o número de resultados especificado pelo argumento
- get (read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY)
-
Executa a consulta e retorna o primeiro resultado ou
None
, se nenhum resultado for encontrado.Argumentos
- read_policy
- Política de leitura que especifica o nível desejado de consistência de dados:
- STRONG_CONSISTENCY
- Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
- EVENTUAL_CONSISTENCY
- Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.
Observação: consultas globais (não ancestrais) ignoram esse argumento.
- deadline
- Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, para retornar uma resposta mais rápida ao usuário, repita a operação, tente uma operação diferente ou adicione essa operação a uma fila de tarefas.
- offset
- Número de resultados a pular antes de retornar o primeiro.
- keys_only Se
- true
true
, retornará apenas chaves em vez de entidades completas. As consultas somente de chaves são mais rápidas e mais baratas do que aquelas que retornam entidades completas. - projection
- Lista ou tupla de nomes de propriedades a serem retornados. Somente entidades com as propriedades especificadas serão retornadas. Se não especificado, entidades inteiras serão retornadas por padrão.
As consultas de projeção
são mais rápidas e mais baratas do que aquelas que retornam entidades completas.
Observação: especificar este parâmetro pode alterar os requisitos de índice da consulta.
- start_cursor
- Posição do cursor em que a consulta será iniciada.
- end_cursor
- Posição do cursor em que a consulta será encerrada.
- fetch (limit, read_policy=STRONG_CONSISTENCY, deadline=STRONG_CONSISTENCY, offset=STRONG_CONSISTENCY, keys_only=STRONG_CONSISTENCY, projection=STRONG_CONSISTENCY, start_cursor=STRONG_CONSISTENCY, end_cursor=STRONG_CONSISTENCY)
-
Executa a consulta e retorna uma lista (possivelmente vazia) de resultados:
- Recupera e descarta o número de resultados especificado pelo argumento
offset
. - Recupera e retorna até o número máximo de resultados especificado pelo argumento
limit
.
O desempenho do método, portanto, se ajusta à soma de
offset
+limit
.Observação: esse método é só um encapsulamento fino em torno do método
run()
. Ele é menos eficiente e consome muito mais memória quando comparado ao uso derun()
diretamente. Raramente é necessário usarfetch()
. Ele é fornecido principalmente por comodidade, nos casos em que é necessário recuperar da memória uma lista completa de resultados da consulta.Dica: o método
fetch()
foi desenvolvido para recuperar apenas o número de resultados especificado pelo argumentolimit
. Para recuperar todos os resultados disponíveis de uma consulta quando o número é desconhecido, userun()
com um tamanho grande de lote, comorun(batch_size=1000)
, em vez defetch()
.Argumentos
- limit
- Número máximo de resultados a serem retornados.
Se definido como
None
, todos os resultados disponíveis serão recuperados. - read_policy
- Política de leitura que especifica o nível desejado de consistência de dados:
- STRONG_CONSISTENCY
- Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
- EVENTUAL_CONSISTENCY
- Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.
Observação: consultas globais (não ancestrais) ignoram esse argumento.
- deadline
- Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, para retornar uma resposta mais rápida ao usuário, repita a operação, tente uma operação diferente ou adicione essa operação a uma fila de tarefas.
- offset
- Número de resultados a pular antes de retornar o primeiro.
- keys_only Se
- true
true
, retornará apenas chaves em vez de entidades completas. As consultas somente de chaves são mais rápidas e mais baratas do que aquelas que retornam entidades completas. - projection
- Lista ou tupla de nomes de propriedades a serem retornados. Somente entidades com as propriedades especificadas serão retornadas. Se não especificado, entidades inteiras serão retornadas por padrão.
As consultas de projeção
são mais rápidas e mais baratas do que aquelas que retornam entidades completas.
Observação: especificar este parâmetro pode alterar os requisitos de índice da consulta.
- start_cursor
- Posição do cursor em que a consulta será iniciada.
- end_cursor
- Posição do cursor em que a consulta será encerrada.
- Recupera e descarta o número de resultados especificado pelo argumento
- count (read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY, read_policy=STRONG_CONSISTENCY)
-
Retorna o número de resultados que correspondem à consulta. Isso é mais rápido por um fator constante do que realmente recuperar todos os resultados, mas o tempo de execução ainda se ajusta à soma de
offset
+limit
de modo linear. A menos que seja esperada uma contagem de resultados pequena, é melhor especificar um argumentolimit
. Caso contrário, o método continuará até terminar a contagem ou expirar.Argumentos
- read_policy
- Política de leitura que especifica o nível desejado de consistência de dados:
- STRONG_CONSISTENCY
- Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
- EVENTUAL_CONSISTENCY
- Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.
Observação: consultas globais (não ancestrais) ignoram esse argumento.
- deadline
- Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, para retornar uma resposta mais rápida ao usuário, repita a operação, tente uma operação diferente ou adicione essa operação a uma fila de tarefas.
- offset
- Número de resultados a pular antes de contar o primeiro.
- limit
- Número máximo de resultados a serem contados.
- start_cursor
- Posição do cursor em que a consulta será iniciada.
- end_cursor
- Posição do cursor em que a consulta será encerrada.
- index_list ()
-
Retorna uma lista de índices usados por uma consulta executada, incluindo índices principais, compostos, tipo e propriedade única.
Cuidado: invocar esse método em uma consulta que ainda não foi executada gerará uma exceção
AssertionError
.Observação: esse recurso não é totalmente compatível no servidor de desenvolvimento. Quando usado com o servidor de desenvolvimento, o resultado é a lista vazia ou uma lista que contém exatamente um índice composto.
Por exemplo, o código a seguir imprime várias informações sobre os índices usados por uma consulta:
# other imports ... import webapp2 from google.appengine.api import users from google.appengine.ext import db class Greeting(db.Model): author = db.StringProperty() content = db.StringProperty(multiline=True) date = db.DateTimeProperty(auto_now_add=True) class MainPage(webapp2.RequestHandler): def get(self): user = users.get_current_user() q = db.Query(Greeting) q.filter("author =", user.user_id()) q.order("-date") q.fetch(100) index_list = q.index_list() for ix in index_list: self.response.out.write("Kind: %s" % ix.kind()) self.response.out.write("<br />") self.response.out.write("Has ancestor? %s" % ix.has_ancestor()) self.response.out.write("<br />") for name, direction in ix.properties(): self.response.out.write("Property name: "+name) self.response.out.write("<br />") if direction == db.Index.DESCENDING: self.response.out.write("Sort direction: DESCENDING") else: self.response.out.write("Sort direction: ASCENDING") self.response.out.write("<br />")
Isso produz uma saída como esta para cada índice:
Kind: Greeting Has ancestor? False Property name: author Sort direction: ASCENDING Property name: date Sort direction: DESCENDING
- cursor ()
-
Retorna uma string de cursor codificada em base64 denotando a posição no conjunto de resultados da consulta após o último resultado recuperado. A string de cursor é segura para usar nos parâmetros HTTP
GET
ePOST
e também pode ser armazenada no Datastore ou no Memcache. Uma invocação futura da mesma consulta pode fornecer essa string por meio do parâmetrostart_cursor
ou do métodowith_cursor()
para retomar a recuperação dos resultados dessa posição.Cuidado: invocar esse método em uma consulta que ainda não foi executada gerará uma exceção
AssertionError
.Observação: nem todas as consultas são compatíveis com cursores. Para mais informações, confira a página Consultas do Datastore.
- with_cursor (start_cursor, start_cursor=None)
-
Especifica as posições inicial e final (opcional) no conjunto de resultados de uma consulta a partir da qual os resultados são recuperados. Para conseguir as strings de cursor referentes às posições inicial e final, chame
cursor()
após uma invocação anterior da consulta. A consulta atual precisa ser idêntica à chamada anterior, incluindo o tipo de entidade, filtros de propriedade, filtros de ancestral e ordens de classificação.Argumentos
- start_cursor
- String de cursor codificada em base64 que especifica o ponto de início da consulta.
- end_cursor
- String de cursor codificada em base64 que especifica o ponto de término da consulta.