API de Datastore para Java 8

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.

Similares, claves e identificadores

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

  • El grupo de similares 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 de acceso principal opcional que ubica a la entidad dentro de la jerarquía de Cloud Datastore

El identificador se asigna cuando se crea la entidad. Ya que es parte de la clave de la entidad, el identificador se encuentra asociado de forma permanente con la entidad y no puede cambiarse. Se puede asignar 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 su superior, en cuyo caso la nueva entidad es 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 un superior se denominan entidades raíz. La asociación entre una entidad y su superior es permanente y no puede cambiarse una vez creada la entidad. Cloud Datastore nunca asignará el mismo ID numérico a dos entidades con el mismo superior ni a dos entidades raíz (que no tienen un superior).

El superior de una entidad, el superior de su superior y así sucesivamente son sus principales. Sus secundarios, los secundarios de sus secundarios y así sucesivamente son sus descendientes. Una entidad raíz y todos sus descendientes pertenecen al mismo grupo de entidad. 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 de principales de esa entidad. La clave completa que identifica a una entidad consta de una secuencia de pares de grupo de similares-identificador que especifican su ruta de principales y terminan con la entidad en sí:

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

En el caso de una entidad raíz, la ruta principal está vacía, y la clave consta solo del grupo de similares y del identificador de la entidad:

[Person:GreatGrandpa]

Este concepto se ilustra en el siguiente diagrama:

Muestra la relación de la entidad raíz con las entidades secundarias del grupo de entidad

Índices y consultas

Además de recuperar entidades de Cloud Datastore directamente según sus claves, una aplicación puede realizar una consulta para recuperarlas según los valores de sus propiedades. La consulta opera en entidades de un tipo determinado; puede especificar filtros en los valores de la propiedad, claves y principales de las entidades, y puede mostrar cero o más entidades como resultado. 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 entidades.

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 limite los resultados solo al grupo de entidad que desciende de un principal específico. Una consulta de este tipo se denomina consulta principal. De forma predeterminada, las consultas principales muestran resultados con coherencia sólida, los que se garantiza que estarán actualizados con los últimos cambios en 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 inactivos. 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 Estructura los datos para lograr una coherencia sólida si deseas obtener más información.

App Engine predefine un índice simple en cada propiedad de una entidad. Una aplicación de App Engine puede definir otros índices personalizados en un archivo de configuración de índices denominado 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 de forma automática cuando encuentra consultas que no pueden ejecutarse con los índices existentes. Para ajustar los índices de forma manual, edita el archivo antes de subir la aplicación.

Para obtener un análisis más profundo de los índices y las consultas, accede a Selección de índices y búsqueda avanzada.

Nota: El mecanismo de consulta basado en índices admite un rango amplio de consultas y es apto 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.

Transacciones

Cada intento de insertar, actualizar o borrar una entidad ocurre en el contexto de una transacción. Una transacción puede incluir una cantidad indeterminada de las operaciones mencionadas. Para mantener la coherencia de los datos, la transacción se asegura de que todas las operaciones que contiene se apliquen a Cloud Datastore en bloque (esto implica que, si alguna de las operaciones falla, ninguna de ellas se aplica).

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. Si no se hace todo en una transacción, es posible que otro proceso aumente el valor del contador entre el momento en que tú lo lees y el momento en que lo actualizas, lo que haría que tu aplicación sobrescriba 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 dentro de una transacción. Esto quiere decir que cada consulta transaccional debe limitarse a un solo grupo de entidad. La transacción puede aplicarse a varias entidades, que pueden pertenecer a un mismo grupo o, en el caso de una transacción entre grupos, a un máximo de veinticinco grupos de entidad distintos.

Cloud Datastore usa la simultaneidad optimista para administrar las transacciones. Cuando dos o más transacciones 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 tendrá éxito y ninguna de las otras podrá confirmarse. Estas otras transacciones se pueden volver a intentar con los datos actualizados. Ten en cuenta que esto limita la cantidad de escrituras simultáneas que pueden aplicarse a una entidad específica de un grupo determinado.

Transacciones entre grupos

Cuando una transacción afecta a entidades pertenecientes a diferentes grupos, se la denomina transacción entre grupos (XG). La transacción se puede aplicar en un máximo de veinticinco grupos de entidad y tendrá éxito 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 debajo del mismo principal solo para realizar escrituras atómicas en ellos.

Al igual que en una transacción de un solo grupo, no puedes realizar 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 los resultados de una transacción previamente confirmada, algunos de estos o ninguno. 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 confirmada de forma parcial.

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 escribir los datos en sí.

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 devuelve un mensaje de error que tu aplicación recibe como excepción. Si la fase de confirmación tiene éxito, pero la de aplicación falla en una réplica en particular, la aplicación se avanza hasta su finalización en esa réplica cuando ocurre alguna de las siguientes situaciones:

  • Los barridos periódicos de Cloud Datastore revisan si hay trabajos de confirmación incompletos y los aplican.
  • Ciertas operaciones (get, put, delete y las consultas principales) que utilizan el grupo entidad afectado hacen que se completen los cambios confirmados, pero aún no aplicados 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 operaciones get y las consultas principales 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 exitosas 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 aún 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 satisface inicialmente una consulta, pero luego se modifica de modo tal que ya no la satisfaga, 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 para una aplicación, como la cantidad de entidades de un grupo de similares determinado 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 las estadísticas de Datastore en Java 8.

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

Enviar comentarios sobre...

Entorno estándar de App Engine para Java 8