Índices de Cloud Datastore

Nota: A los desarrolladores que compilan aplicaciones nuevas se les recomienda enfáticamente usar la Biblioteca cliente de NDB, que tiene muchos beneficios en comparación con esta biblioteca cliente, como el almacenamiento automático de entidades en caché a través de la API de Memcache. Si actualmente usas la biblioteca cliente de DB antigua, lee la guía de migración de DB a NDB.

App Engine define previamente un índice simple sobre cada propiedad de una entidad. Una aplicación de App Engine puede definir otros índices personalizados en un archivo de configuración de índices llamado index.yaml. El servidor de desarrollo agrega sugerencias a este archivo automáticamente cuando encuentra consultas que no pueden ejecutarse con los índices existentes. Para ajustar los índices de manera manual, edita el archivo antes de subir la aplicación.

Nota: El mecanismo de consulta basado en índices admite una amplia gama de consultas y es adecuado para la mayoría de las aplicaciones. Sin embargo, este mecanismo no admite algunos tipos de consulta que son comunes en otras tecnologías de base de datos. En particular, el motor de consultas de Cloud Datastore no admite las operaciones de unión o agregación. Para conocer las limitaciones de las consultas de Cloud Datastore, visita esta página.

Estructura y definición de los índices

Un índice se define en una lista de propiedades de un tipo de entidad determinado, con un orden correspondiente (ascendente o descendente) para cada propiedad. El índice también puede incluir los principales de la entidad para usarlos en las consultas principales.

Una tabla de índice contiene una columna por cada propiedad que figura en la definición del índice. Cada fila de la tabla representa una entidad de Cloud Datastore que es un resultado potencial de las consultas basadas en el índice. Una entidad solo se incluye en el índice si tiene un valor indexado configurado para cada propiedad usada en el índice; si la definición del índice hace referencia a una propiedad cuya entidad no tiene ningún valor, esa entidad no aparecerá en el índice y nunca se mostrará como resultado de ninguna búsqueda basada en el índice.

Nota: Cloud Datastore distingue entre una entidad que no posee una propiedad y una que posee la propiedad con un valor nulo (None). Si asignas un valor nulo a una propiedad de una entidad de manera explícita, es posible que se incluya esa entidad en los resultados de una consulta que haga referencia a esa propiedad.

Nota: Cada una de las propiedades individuales de los índices compuestos por varias propiedades no deben configurarse en no indexada.

Las filas de una tabla de índice se ordenan primero por entidad principal y, luego, por valor de las propiedades, en el orden especificado en la definición del índice. El índice perfecto de una consulta, que permite que esta se ejecute de manera más eficiente, se define según las siguientes propiedades y en este orden:

  1. Propiedades usadas en filtros de igualdad
  2. Propiedad usada en un filtro de desigualdad (no puede haber más de uno)
  3. Propiedades usadas en órdenes de clasificación

Esto garantiza que todos los resultados para cada ejecución posible de la consulta aparezcan en filas consecutivas de la tabla. Cloud Datastore ejecuta una consulta con el índice perfecto mediante estos pasos:

  1. Identifica el índice correspondiente al tipo, las propiedades de filtro, los operadores de filtro y los órdenes de clasificación de la consulta.
  2. Busca desde el principio del índice hasta la primera entidad que cumple con todas las condiciones de filtro de la consulta.
  3. Continúa la búsqueda del índice y muestra cada entidad a la vez hasta que:
    • Encuentra una entidad que no cumple con las condiciones del filtro.
    • Llega al final del índice.
    • Recopila la cantidad máxima de resultados solicitados por la consulta.

Por ejemplo, considera la siguiente consulta (expresada en GQL):

SELECT * FROM Person WHERE last_name = "Smith"
                       AND height < 72
                  ORDER BY height DESC

El índice perfecto de esta consulta es una tabla de claves para las entidades del tipo Person, con columnas para los valores de las propiedades last_name y height. El índice se ordena primero de manera ascendente por last_name y, luego, de manera descendente por height.

Dos consultas del mismo tipo pero con valores de filtro diferentes usan el mismo índice. Por ejemplo, la siguiente consulta usa el mismo índice que la consulta anterior:

SELECT * FROM Person WHERE last_name = "Jones"
                       AND height < 63
                     ORDER BY height DESC

Las dos consultas siguientes también usan el mismo índice, a pesar de tener formas diferentes:

SELECT * FROM Person WHERE last_name = "Friedkin"
                       AND first_name = "Damian"
                     ORDER BY height ASC

y

SELECT * FROM Person WHERE last_name = "Blair"
                  ORDER BY first_name, height ASC

Configuración de índices

Según la configuración predeterminada, Cloud Datastore predefine automáticamente un índice para cada propiedad de cada tipo de entidad. Estos índices predefinidos son suficientes para realizar varias consultas sencillas, como consultas solo de igualdad y consultas de desigualdad simples. Para todas las demás consultas, la aplicación debe definir los índices que necesita en un archivo de configuración de índices llamado index.yaml. Si la aplicación intenta realizar una consulta que no puede ejecutarse con los índices disponibles (ya sean predefinidos o especificados en el archivo de configuración de índices), la consulta fallará y mostrará una excepción NeedIndexError.

Datastore compila índices automáticos para consultas de los siguientes tipos:

  • Consultas sin categoría que usan solo filtros principales y de clave
  • Consultas solo con filtros principales y de igualdad
  • Consultas que usan solo filtros de desigualdad (los que están limitados a una propiedad única)
  • Consultas que usan solo filtros principales, filtros de igualdad en propiedades y filtros de desigualdad en claves
  • Consultas sin filtros y con un solo orden de clasificación en una propiedad, ya sea ascendente o descendente

Otros tipos de consulta requieren que se especifiquen sus índices en el archivo de configuración de índices. Estas incluyen las siguientes:

  • Consultas con filtros principales y de desigualdad
  • Consultas con uno o más filtros de desigualdad en una propiedad y uno o más filtros de igualdad en otras propiedades
  • Consultas con un orden de clasificación por claves descendente
  • Consultas con varios órdenes de clasificación

Índices y propiedades

A continuación, se detallan algunas consideraciones especiales sobre los índices y cómo se relacionan con las propiedades de las entidades de Cloud Datastore.

Propiedades con tipos de valores mixtos

Cuando dos entidades tienen propiedades con el mismo nombre pero diferentes tipos de valor, un índice de la propiedad clasifica las entidades primero por tipo de valor y, luego, por un orden secundario apropiado para cada tipo. Por ejemplo, si dos entidades tienen una propiedad llamada age, una con un valor entero y la otra con un valor de string, la entidad con el valor entero siempre precede a la que tiene el valor de string cuando se las ordena por la propiedad age, sin importar el valor mismo de las propiedades.

Esto es muy importante en el caso de los números enteros y los de coma flotante, que Cloud Datastore trata como tipos separados. Dado que todos los números enteros se ordenan antes que los números flotantes, una propiedad con el valor de número entero 38 aparece antes que una con el valor de número flotante 37.5.

Propiedades no indexadas

Si sabes que nunca tendrás que ordenar o filtrar una propiedad en particular, puedes indicar que la propiedad es no indexada para que Cloud Datastore no mantenga las entradas de índice de esa propiedad. Esto reduce el costo de ejecución de la aplicación, ya que disminuye la cantidad de operaciones de escritura que Cloud Datastore debe realizar. Una entidad con una propiedad no indexada se comporta como si la propiedad no estuviera configurada: las consultas con un filtro o un orden de clasificación en la propiedad no indexada nunca mostrarán esa entidad.

Nota: Si una propiedad figura en un índice compuesto por varias propiedades, configurarla como no indexada evitará que se indexe en el índice compuesto.

Por ejemplo, supongamos que una entidad tiene las propiedades a y b, y que quieres crear un índice que logre cumplir con consultas como WHERE a ="bike" and b="red". También supongamos que no te interesan las consultas WHERE a="bike" y WHERE b="red". Si configuras a como no indexado y creas un índice para a y b, Cloud Datastore no creará entradas para el índice de a y b y, por lo tanto, la consulta WHERE a="bike" and b="red" no funcionará. Con el fin de que Cloud Datastore cree entradas para los índices a y b, tanto a como b deben estar indexadas.

Para indicar que una propiedad es no indexada, se debe configurar indexed=False en el constructor de propiedad:

class Person(db.Model):
  name = db.StringProperty()
  age = db.IntegerProperty(indexed=False)

Más adelante, puedes volver a colocarla como indexada si llamas nuevamente al constructor de propiedad con indexed=True:

class Person(db.Model):
  name = db.StringProperty()
  age = db.IntegerProperty(indexed=True)

Sin embargo, ten en cuenta que cambiar una propiedad de no indexada a indexada no afecta ninguna entidad existente que se haya creado antes del cambio. Las consultas que filtren según la propiedad no mostrarán esas entidades existentes, ya que las entidades no estaban escritas en el índice de la consulta cuando se crearon. Para que las consultas futuras puedan acceder a las entidades, debes volver a escribirlas en Cloud Datastore para que se ingresen en los índices adecuados. Es decir, debes hacer lo siguiente para cada una de esas entidades:

  1. Recuperar (get) la entidad de Cloud Datastore.
  2. Ingresar (put) la entidad de nuevo en Cloud Datastore.

De manera similar, cambiar una propiedad de indexada a no indexada solo afecta las entidades escritas posteriormente en Cloud Datastore. Las entradas de índice de cualquier entidad actual con esa propiedad existirán hasta que se actualicen o borren las entidades. Para evitar resultados no deseados, debes quitar todas las consultas del código que filtran o clasifican según la propiedad (ahora no indexada).

Límites de índice

Datastore impone límites al número y tamaño general de las entradas de índice que se pueden asociar con una sola entidad. Estos límites son grandes y no afectan a la mayoría de las aplicaciones. Sin embargo, hay circunstancias en las que puedes encontrarte con estos límites.

Como se describió anteriormente, Cloud Datastore crea una entrada en un índice predefinido para cada propiedad de cada entidad, excepto las strings de texto largas (Text), las strings de bytes largas (Blob) y las que hayas declarado explícitamente como no indexadas. La propiedad también puede estar incluida en índices personalizados adicionales declarados en tu archivo de configuración index.yaml. Siempre que una entidad no tenga propiedades de lista, tendrá a lo sumo una entrada en cada uno de estos índices personalizados (para índices no principales) o uno para cada una de las principales de la entidad (para índices principales). Cada una de estas entradas de índice debe actualizarse cada vez que cambie el valor de la propiedad.

En el caso de una propiedad que tiene un valor único para cada entidad, cada valor posible debe almacenarse solo una vez por entidad en el índice predefinido de la propiedad. Pese a ello, es posible que una entidad con un gran número de estas propiedades de valor único supere el límite de entradas o de tamaño del índice. De manera similar, una entidad que puede tener varios valores para la misma propiedad requiere una entrada de índice distinta para cada valor. De la misma forma, si el número de valores posibles es grande, esta entidad puede superar el límite de entradas.

La situación empeora en el caso de las entidades con varias propiedades, cada una de las cuales puede asumir diversos valores. A fin de alojar una entidad de ese tipo, el índice debe incluir una entrada para cada combinación posible de valores de propiedad. Los índices personalizados que hacen referencia a varias propiedades, cada una con varios valores, son susceptibles a un “alto crecimiento” combinatorio y pueden requerir un gran número de entradas para una entidad con una cantidad relativamente pequeña de valores de propiedad posibles. Estos índices con alto crecimiento pueden aumentar en gran medida el costo de escribir una entidad en Cloud Datastore, debido la cantidad alta de entradas de índice que deben actualizarse, y también pueden hacer que la entidad supere el límite de entradas o de tamaño del índice.

Tomemos la consulta

SELECT * FROM Widget WHERE x=1 AND y=2 ORDER BY date

que hace que el SDK sugiera el siguiente índice:

indexes:
- kind: Widget
  properties:
  - name: x
  - name: y
  - name: date
Este índice requerirá un total de |x| * |y| * |date| entradas para cada entidad (donde |x| denota la cantidad de valores asociados con la entidad para la propiedad x). Por ejemplo, el siguiente código
class Widget(db.Expando):
  pass

e2 = Widget()
e2.x = [1, 2, 3, 4]
e2.y = ['red', 'green', 'blue']
e2.date = datetime.datetime.now()
e2.put()

crea una entidad con cuatro valores para la propiedad x, tres valores para la propiedad y y date definida como la fecha actual. Esto requerirá 12 entradas de índice, una para cada combinación posible de valores de propiedad:

(1, "red", <now>) (1, "green", <now>) (1, "blue", <now>)

(2, "red", <now>) (2, "green", <now>) (2, "blue", <now>)

(3, "red", <now>) (3, "green", <now>) (3, "blue", <now>)

(4, "red", <now>) (4, "green", <now>) (4, "blue", <now>)

Cuando la misma propiedad se repite varias veces, Cloud Datastore puede detectar índices con alto crecimiento y sugerir un índice alternativo. Sin embargo, en todas las demás circunstancias (como la consulta definida en este ejemplo), Cloud Datastore generará un índice con alto crecimiento. En este caso, puedes evitar el índice con alto crecimiento si configuras de forma manual un índice en el archivo de configuración de índices:

indexes:
- kind: Widget
  properties:
  - name: x
  - name: date
- kind: Widget
  properties:
  - name: y
  - name: date
Esto reduce el número de entradas necesarias para (|x| * |date| + |y| * |date|) o 7 entradas en lugar de 12:

(1, <now>) (2, <now>) (3, <now>) (4, <now>)

("red", <now>) ("green", <now>) ("blue", <now>)

Todas las operaciones put que hagan que un índice supere los límites de entradas o de tamaño fallarán con una excepción BadRequestError. En el texto de la excepción, se describe qué límite se superó ("Too many indexed properties" o "Index entries too large") y qué índice personalizado generó la excepción. Si creas un índice nuevo que podría superar los límites de cualquier entidad, las consultas sobre ese índice fallarán y el índice aparecerá con el estado Error en GCP Console. Para resolver los índices en el estado Error, realiza los siguientes pasos:

  1. Quita el índice con estado Error de tu archivo index.yaml.

  2. Ejecuta el siguiente comando desde un directorio donde esté ubicado el archivo index.yaml para quitar ese índice de Cloud Datastore.

    gcloud datastore cleanup-indexes index.yaml
    
  3. Resuelve la causa del error. Por ejemplo:

    • Vuelve a definir el índice y las consultas correspondientes.
    • Quita las entidades que generan el alto crecimiento del índice.
  4. Agrega el índice de nuevo a tu archivo index.yaml.

  5. Ejecuta el siguiente comando desde un directorio donde esté ubicado el archivo index.yaml para crear ese índice en Cloud Datastore:

    gcloud datastore create-indexes index.yaml
    

Puedes evitar los índices con alto crecimiento si evitas las consultas que requieren un índice personalizado con una propiedad de lista. Como se describió antes, esto incluye consultas con varios órdenes de clasificación o con una mezcla de filtros de igualdad y desigualdad.

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Entorno estándar de App Engine para Python