API de Java Datastore

En este documento, se describe el modelo de datos de los objetos almacenados en Cloud Datastore, la forma en que se estructuran las consultas con la API y la manera en que se procesan las transacciones.

Entidades

En Cloud Datastore, los objetos se denominan entidades. Una entidad posee una o más propiedades con nombre, cada una de las cuales puede tener uno o más valores. Los valores de propiedad pueden pertenecer a diversos tipos de datos, como números enteros, números con coma flotante, strings, fechas y datos binarios, entre otros. Una consulta sobre una propiedad con distintos valores comprueba si alguno de estos cumple con los criterios de la consulta. Esto hace que tales propiedades sean útiles para las pruebas de membresía.

Tipos, identificadores y claves

Cada entidad de Cloud Datastore es de un tipo en particular, que permite clasificar a la entidad con el propósito de ejecutar consultas. Por ejemplo, una aplicación de recursos humanos podría representar a cada empleado de una empresa con una entidad de tipo Employee. Además, cada entidad tiene su propia clave, que la identifica de forma única. La clave consta de los siguientes componentes:

  • El tipo de la entidad
  • Un identificador, que puede ser de dos tipos:
    • una string de nombre de clave
    • un ID compuesto por números enteros
  • Una ruta principal opcional que ubica a la entidad dentro de la jerarquía de Cloud Datastore.

El identificador se asigna cuando se crea la entidad. Debido a que es parte de la clave de la entidad, el identificador se encuentra asociado de forma permanente con la entidad y no puede cambiarse. Puede asignarse de dos formas:

  • Tu aplicación puede especificar su propia string de nombre de clave para la entidad.
  • Puedes hacer que Cloud Datastore le asigne un ID compuesto por números enteros a la entidad de forma automática.

Rutas principales

Las entidades de Cloud Datastore conforman un espacio con estructura jerárquica similar a la estructura de directorios de un sistema de archivos. Cuando creas una entidad, tienes la opción de designar otra entidad como principal, en cuyo caso la entidad nueva sería secundaria de la entidad principal (ten en cuenta que, a diferencia de lo que ocurre en un sistema de archivos, no es necesario que la entidad principal exista realmente). Las entidades que no tienen una entidad principal se denominan entidades raíz. La asociación entre una entidad y su entidad superior es permanente y no se puede cambiar una vez que se crea la entidad. Cloud Datastore nunca asignará el mismo ID numérico a dos entidades con la misma entidad principal o a dos entidades raíz (que no tengan una principal).

La entidad principal de una entidad, la entidad superior a su principal, y así sucesivamente, son sus entidades principales. Las entidades secundarias, las secundarias de sus secundarias, y así sucesivamente, son sus descendientes. Una entidad raíz y todas sus descendientes pertenecen al mismo grupo de entidades. La secuencia de entidades que comienza con una entidad raíz y sigue de superior a secundario, hasta llegar a determinada entidad, constituye la ruta principal de esa entidad. La clave completa que identifica a una entidad consta de una secuencia de pares de tipo identificador que especifican su ruta principal y que finaliza con los de la entidad misma:

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

Para una entidad raíz, la ruta principal está vacía y la clave consta solo del tipo y del identificador de la entidad:

[Person:GreatGrandpa]

Este concepto se ilustra en el diagrama siguiente:

Grupo de entidad

Índices y consultas

Además de recuperar entidades de Cloud Datastore directamente con sus claves, una aplicación puede ejecutar una consulta para recuperarlas por los valores de sus propiedades. La consulta opera con entidades de un tipo determinado; puede especificar filtros para los valores de las propiedades, las claves y los principales de las entidades, así como no mostrar ninguna identidad o exhibir aún más como resultados. Una consulta también puede especificar órdenes de clasificación para secuenciar los resultados según los valores de sus propiedades. Los resultados incluyen todas las entidades que tienen al menos un valor (posiblemente nulo) por cada propiedad mencionada en los filtros y órdenes de clasificación, y cuyos valores de propiedad cumplen con todos los criterios de filtro especificados. La consulta puede mostrar entidades completas, entidades proyectadas o solo claves de entidad.

Una consulta típica incluye lo siguiente:

Cuando se ejecuta una consulta, esta recupera todas las entidades de ese tipo que satisfacen todos los filtros indicados, en el orden que se especificó. Las consultas se ejecutan en modo de solo lectura.

Nota: Para conservar la memoria y mejorar el rendimiento, las consultas deben especificar, siempre que sea posible, un límite en la cantidad de resultados que se muestran.

Una consulta también puede incluir un filtro de principal que limita los resultados solo al grupo de entidad que desciende de una entidad principal específica. Esa consulta se denomina consulta principal. De forma predeterminada, las consultas principales muestran resultados con coherencia sólida, por lo que está garantizado que la información obtenida está actualizada con los cambios más recientes de los datos. En contraposición, las consultas no principales pueden abarcar la totalidad de Cloud Datastore en lugar de un solo grupo de entidad, pero tienen coherencia eventual, por lo que pueden mostrar resultados obsoletos. Si la coherencia sólida es importante para tu aplicación, es posible que debas tener esto en cuenta cuando estructures tus datos: coloca las entidades relacionadas en el mismo grupo para que puedan recuperarse con una consulta principal, en lugar de una consulta no principal. Consulta Cómo estructurar los datos para lograr una coherencia sólida si deseas obtener más información.

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 datastore-indexes.xml, que se genera en el directorio /war/WEB-INF/appengine-generated de tu aplicación. 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 algunas categorías de consulta que son comunes en otras tecnologías de base de datos. En particular, el motor de consultas de Cloud Datastore no admite uniones ni consultas de agregación. Para conocer las limitaciones de las consultas de Cloud Datastore, visita esta página.

Transacciones

Cada intento de insertar, actualizar o borrar una entidad ocurre en el contexto de una transacción. Una sola transacción puede incluir una cantidad indeterminada de las operaciones mencionadas. Para mantener la coherencia de los datos, la transacción garantiza que todas las operaciones que contiene se apliquen a Cloud Datastore como una unidad o que, si alguna de las operaciones falla, no se aplique ninguna de ellas.

Puedes realizar varias acciones en una entidad con una sola transacción. Por ejemplo, para incrementar un campo de contador en un objeto, tienes que leer el valor del contador, calcular el valor nuevo y, luego, almacenarlo. Sin una transacción, es posible que otro proceso aumente el contador entre el tiempo de lectura del valor y el tiempo de actualización, lo que genera que la aplicación reemplace el valor actualizado. Realizar la lectura, el cálculo y la escritura en una sola transacción garantiza que ningún otro proceso pueda interferir en el incremento.

Transacciones y grupos de entidad

Solo se permiten consultas principales en una transacción. Esto quiere decir que cada consulta transaccional debe limitarse a un solo grupo de entidad. La transacción en sí puede aplicarse a varias entidades, las cuales pueden pertenecer a un solo grupo o (en el caso de una transacción entre grupos) a un máximo de veinticinco grupos de entidad distintos.

Cloud Datastore utiliza la simultaneidad optimista para administrar las transacciones. Cuando dos transacciones o más intentan cambiar el mismo grupo de entidad a la vez (ya sea para actualizar las entidades existentes o crear otras nuevas), la primera transacción que se confirme se hará correctamente y ninguna de las otras podrá confirmarse. Estas otras transacciones se pueden intentar con los datos actualizados. Ten en cuenta que esto limita la cantidad de escrituras simultáneas que pueden aplicarse a una entidad de un grupo determinado.

Transacciones entre grupos

Una transacción de entidades perteneciente a diferentes grupos se denomina transacción entre grupos (XG). La transacción se puede aplicar en un máximo de veinticinco grupos de entidad y se aplicará correctamente siempre que ninguna transacción simultánea afecte a alguno de los grupos de entidades a los que se aplica. Esto te brinda más flexibilidad para organizar tus datos, ya que no estás obligado a colocar distintos tipos de datos en la misma entidad principal solo para realizar escrituras atómicas en ellos.

Al igual que en una transacción de un solo grupo, no puedes ejecutar una consulta no principal en una transacción XG. Sin embargo, puedes realizar consultas principales en grupos de entidad separados. Las consultas no transaccionales (no principales) pueden ver todos, algunos o ninguno de los resultados de una transacción previamente confirmada. Para obtener más información sobre este tema, consulta Escrituras y visibilidad de los datos en Cloud Datastore. Sin embargo, es más probable que esas consultas no transaccionales vean los resultados de una transacción XG parcialmente confirmada que las de una transacción de un solo grupo parcialmente confirmada.

Una transacción XG que solo afecta a un único grupo de entidad tiene exactamente el mismo rendimiento y costo que una transacción de un solo grupo, no XG. En una transacción XG que alcanza a varios grupos de entidad, las operaciones cuestan lo mismo que si se realizaran en una transacción que no es XG; pero pueden experimentar una latencia mayor.

Escritura y visibilidad de datos en Cloud Datastore

Los datos se escriben en Cloud Datastore en dos fases:

  1. En la fase de Confirmación, los datos de la entidad se agregan a los registros de transacciones de la mayoría de las réplicas y se agrega una marca a las otras réplicas para indicar que sus registros no están actualizados.
  2. La fase de Aplicación se produce de forma independiente en cada réplica y consta de dos acciones realizadas en paralelo:
    • Los datos de la entidad se escriben en esa réplica.
    • Las filas del índice de la entidad se escriben en esa réplica. (Ten en cuenta que esto puede llevar más tiempo que la escritura de los datos).

La operación de escritura se muestra inmediatamente después de la fase de Confirmación y la fase de Aplicación se realiza de forma asíncrona, posiblemente en diferentes momentos en cada réplica y con retrasos de unos pocos cientos de milisegundos o más tras la finalización de la fase de confirmación. Si ocurre un error durante la fase de Confirmación, se hacen reintentos automáticos; pero si los errores continúan, Cloud Datastore muestra un mensaje de error que tu aplicación recibe como excepción. Si la fase de Confirmación es correcta, pero la de Aplicación falla en una réplica en particular, la Aplicación avanza hasta su finalización en esa réplica cuando ocurre alguna de las siguientes situaciones:

  • Los barridos periódicos de Cloud Datastore verifican si hay trabajos de confirmación incompletos y los aplican.
  • Ciertas operaciones (get, put, delete y las consultas principales) que utilizan el grupo de entidad afectado hacen que se completen los cambios confirmados, pero que todavía no se aplicaron en la réplica en la que se están ejecutando antes de proceder con la nueva operación.

Este comportamiento de escritura puede tener varias implicaciones sobre cómo y cuándo los datos son visibles para tu aplicación en diferentes partes de las fases de Confirmación y Aplicación:

  • Si una operación de escritura informa un error de tiempo de espera, no se puede determinar (sin intentar leer los datos) si la operación se realizó correctamente o no.
  • Debido a que las consultas principales y las operaciones get de Cloud Datastore aplican cualquier modificación pendiente en la réplica en la que se ejecutan, estas operaciones siempre tienen una vista coherente de todas las transacciones satisfactorias anteriores. Por lo tanto, está garantizado que una operación get (que busca una entidad actualizada por su clave) verá la versión más reciente de esa entidad.
  • Las consultas no principales pueden mostrar resultados obsoletos, ya que pueden estar ejecutándose en una réplica en la que todavía no se han aplicado las transacciones más recientes. Esto puede ocurrir incluso si ya se realizó una operación que garantiza la aplicación de las transacciones pendientes, ya que la consulta puede ejecutarse en una réplica diferente de la que se usó en la operación anterior.
  • El momento en que se hacen los cambios simultáneos puede afectar los resultados de las consultas no principales. Si una entidad cumple inicialmente con una consulta, pero luego se modifica de modo tal que ya no cumple, la entidad puede incluirse de todos modos en el conjunto de resultados si todavía no se aplicaron los cambios a los índices de la réplica en la que se ejecutó la consulta.=

Estadísticas de Cloud Datastore

Cloud Datastore lleva estadísticas sobre los datos almacenados en una aplicación, como la cantidad de entidades de determinado tipo o el espacio que utilizan los valores de una propiedad de cierto tipo. Puedes ver estas estadísticas en GCP Console en la página del panel de Cloud Datastore. También puedes usar la API de Cloud Datastore para acceder a estos valores de manera programática desde la aplicación mediante consultas sobre entidades con nombres especiales. Para obtener más información, consulta Estadísticas de Datastore en Java.

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

Enviar comentarios sobre...

Entorno estándar de App Engine para Java