La clase Query

La clase Query es una interfaz de consulta de almacén de datos que utiliza objetos y métodos para preparar consultas.

La clase Query se proporciona a través del módulo google.appengine.ext.db.

• Introducción
• Query()
• Métodos de instancia:
  • filter()
  • order()
  • ancestor()
  • get()
  • fetch()
  • count()

Introducción

Una aplicación crea un objeto Query mediante la ejecución del constructor con la clase Model cuyas entidades se van a consultar, o mediante la ejecución del método de la clase all() de la clase.

class Song(db.Model):
  title = db.StringProperty()
  composer = db.StringProperty()
  date = db.DateTimeProperty()

query = db.Query(Song)

query = Song.all()

Sin modificación, el objeto representa una consulta para todas las entidades del tipo determinado. Las llamadas del método personalizan la consulta mediante condiciones de propiedad (filter()), condiciones de ancestros (ancestor()) y criterios de ordenación (order()). Para comodidad del usuario, estos métodos devuelven self, de modo que se pueden encadenar juntos en una única instrucción.

query.filter('title =', 'Imagine')
query.order('-date')
query.ancestor(key)

query.filter('title =', 'Imagine').order('-date').ancestor(key)

La aplicación ejecuta la consulta de una de las dos formas siguientes:

• mediante la ejecución del método fetch(). Al ejecutar este método, se realiza una llamada única al almacén de datos para extraer los resultados hasta alcanzar el número de resultados especificado. El objeto Query no almacena los resultados en la memoria caché; por lo tanto, si se ejecuta fetch() por segunda vez, la consulta volverá a ejecutarse.

  results = query.fetch(limit=5)
  for song in results:
    print song.title
  

• mediante el tratamiento del objeto Query como elemento iterable. El iterador recupera los resultados del almacén de datos en pequeños lotes, lo que permite a la aplicación dejar de iterar los resultados para no extraer más de los necesarios. La iteración se detiene una vez recuperados todos los resultados que coinciden con la consulta. Como ocurre con fetch(), la interfaz del iterador no almacena los resultados en la memoria caché, por lo que si se crea un nuevo iterador a partir del objeto Query, la consulta se ejecutará de nuevo.

  for song in query:
    print song.title
  

Consulta también GqlQuery, una clase de consulta que utiliza un lenguaje de consulta parecido a SQL.

Nota: los algoritmos y las estructuras de datos basados en índices que ejecutan las consultas del almacén de datos no admiten determinados tipos de consultas. Para obtener más información, ve a Consultas e índices: Restricciones aplicadas a las consultas.

Constructor

El constructor de la clase Query se define del siguiente modo:

class Query(model_class)

Una interfaz de consulta de almacén de datos que utiliza métodos y objetos para preparar las consultas.

La instancia Query devuelta por el constructor representa una consulta para todas las entidades de ese tipo. Los métodos de instancia filter(), order() y ancestor() aplican criterios a la consulta para filtrar y ordenar los resultados.

Argumentos:

model_class

La clase de Model (o Expando) que representa el tipo de entidad de almacén de datos de la consulta.

Métodos de instancia

Las instancias de la clase Query tienen los siguientes métodos:

filter(property_operator, value)

Añade un filtro de condición de propiedad a la consulta. La consulta sólo devolverá aquellas entidades con propiedades que cumplan todas las condiciones.

Argumentos:

property_operator

Una cadena que contiene el nombre de propiedad y un operador de comparación opcional. El nombre y el operador deben ir separados por un espacio, como en age >. Los operadores de comparación compatibles son: < <= = >= > != IN. Si el operador no aparece en la cadena (es decir, que el nombre de propiedad está formado sólo por el argumento), el filtro utiliza el operador =.

value

El valor que se utilizará en la comparación en el lado derecho de la expresión. Su tipo debe ser el tipo de datos de valor de la propiedad que se va a comparar. Consulta Tipos y clases de propiedades.

query.filter('height >', 42).filter('city = ', 'Seattle')

query.filter('user = ', users.get_current_user())

order(property)

Añade un criterio de ordenación para los resultados. Los resultados se ordenan comenzando por el primer criterio de ordenación añadido.

Argumentos:

property

Una cadena, el nombre de la propiedad que se va a ordenar. Para especificar que el orden debe ser descendente, coloca un guión (-) delante del nombre. Si no colocas el guión, el orden será ascendente.

# Order by last name, alphabetical:
query.order('last_name')

# Order tallest to shortest:
query.order('-height')

ancestor(ancestor)

Añade un filtro de condición de ancestro a la consulta. La consulta sólo devolverá aquellas entidades con la entidad determinada como ancestro (en cualquier parte de su ruta).

Argumentos:

ancestor

Una instancia Model o Key que representa el ancestro.

get()

Ejecuta la consulta y, a continuación, devuelve el primer resultado, o None si la consulta no devolvió ningún resultado.

get() implica un "límite" de 1. Se extrae como máximo un resultado del almacén de datos.

fetch(limit, offset=0)

Ejecuta la consulta y, a continuación, devuelve los resultados.

Los argumentos limit y offset controlan el número de resultados que se extraen del almacén de datos y el número de resultados que devuelve el método fetch():

• El almacén de datos extrae los resultados de offset + limit en la aplicación. El propio almacén de datos no omite los primeros resultados de offset.
• El método fetch() omite los primeros resultados de offset y, a continuación, devuelve el resto (resultados de limit).
• La consulta presenta características de rendimiento que se corresponden linealmente con la cantidad de desviación más el límite.

Nota: el método fetch() devuelve un máximo de 1.000 resultados. Si hay más de 1.000 entidades que coinciden con la consulta y no se ha especificado ningún límite o se utiliza un límite superior a 1.000, el método fetch() sólo devolverá los primeros 1.000 resultados.

Argumentos:

limit

El número de resultados que se van a devolver. Es posible que se devuelva un número de resultados inferior al límite si no hay suficientes resultados disponibles que cumplan los criterios.

El argumento limit es obligatorio. Para obtener todos los resultados de una consulta cuando no se conoce el número de resultados, utiliza el objeto Query como elemento iterable en lugar de utilizar el método fetch().

offset

El número de resultados que se van a omitir.

El valor de retorno es una lista de instancias de modelo, posiblemente una lista vacía.

count(limit)

Devuelve el número de resultados que extrae esta consulta.

El método count() resulta algo más rápido que la recuperación de todos los datos por un factor constante, pero el tiempo de ejecución sigue creciendo con el tamaño del conjunto de resultados. Se recomienda utilizar sólo el método count() en los casos en que se espere un recuento reducido o especificar un límite.

Nota: el método count() devuelve un valor máximo de 1.000. Si el número real de entidades que coinciden con los criterios de consulta supera el máximo, el método count() devuelve 1.000.

Argumentos:

limit

El número máximo de resultados que se van a contar.