Entidades, propiedades y claves

Go Java PHP Python

Los objetos de datos en Datastore se conocen como entidades. Una entidad posee una o más propiedades con nombre, que pueden tener uno o más valores. No es necesario que las entidades del mismo tipo tengan las mismas propiedades, ni que los valores de una entidad para una propiedad determinada correspondan al mismo tipo de datos. (Si fuera necesario, una aplicación puede establecer y aplicar estas restricciones en su propio modelo de datos).

Datastore es compatible con una variedad de tipos de datos para valores de propiedad. Se incluyen, entre otros:

• Números enteros
• Números de coma flotante
• Strings
• Fechas
• Datos binarios

Para obtener una lista completa de los tipos, consulta Tipos de valores y propiedades.

Cada entidad en Datastore tiene una clave que la identifica de manera única. La clave consta de los siguientes componentes:

• El espacio de nombres de la entidad, que permite la función de multiusuario
• El tipo de entidad, que la clasifica para realizar consultas de Datastore
• Un identificador de la entidad individual, que puede ser de alguna de las clases siguientes:
  • una string de nombre de clave
  • un ID numérico entero
• Una ruta principal opcional que ubica la entidad dentro de la jerarquía de Datastore

No asignes el nombre “clave” para una propiedad. Este nombre se reserva para una propiedad especial que se usa a fin de almacenar la clave Model. Aunque pueda funcionar de manera local, la existencia de una propiedad llamada “clave” impedirá la implementación en App Engine.

Una aplicación puede recuperar una entidad individual de Datastore mediante la clave de la entidad, o una o más entidades si emite una consulta basada en los valores de propiedad o las claves de las entidades.

El SDK de App Engine para Java incluye una API simple, proporcionada en el paquete com.google.appengine.api.datastore, que admite las funciones de Datastore. Todos los ejemplos de este documento se basan en esta API de bajo nivel; puedes elegir usarla directamente en tu aplicación o como la base sobre la que crear tu propia capa de administración de datos.

Datastore no aplica ninguna restricción en las estructuras de las entidades. Por ejemplo, si una propiedad posee un valor de un tipo en particular, esta tarea le corresponde a la aplicación.

Identificadores y tipos

Cada entidad de Datastore es de un tipo en particular que clasifica la entidad para realizar consultas; por ejemplo, una aplicación de recursos humanos podría representar a cada empleado de una empresa mediante una entidad de tipo Employee. En la API de Datastore para Java, debes especificar un tipo de entidad cuando la crees, como un argumento en el constructor Entity(). Todos los nombres de tipos que comienzan con dos guiones bajos (__) están reservados y no se pueden usar.

En el siguiente ejemplo, se crea una entidad de categoría Employee, se propagan sus valores de propiedad y se la guarda en Datastore:

Entity employee = new Entity("Employee", "asalieri");
employee.setProperty("firstName", "Antonio");
employee.setProperty("lastName", "Salieri");
employee.setProperty("hireDate", new Date());
employee.setProperty("attendedHrTraining", true);

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
datastore.put(employee);

Además de un tipo, cada entidad posee un identificador, que se le 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 a la entidad y no se puede cambiar. Se puede asignar de dos maneras:

• Tu aplicación puede especificar su propia string de nombre de clave para la entidad.
• Puedes hacer que Datastore asigne de forma automática un ID de número entero a la entidad.

Si quieres asignarle un nombre de clave a la entidad, proporciona el nombre como el segundo argumento para el constructor cuando crees la entidad:

Entity employee = new Entity("Employee", "asalieri");

Para que Datastore asigne un ID numérico de forma automática, omite el siguiente argumento:

Entity employee = new Entity("Employee");

Asigna identificadores

Datastore se puede configurar para generar IDs de forma automática mediante dos políticas de identificación automática diferentes:

• La política default genera una secuencia aleatoria de IDs sin usar con una distribución bastante uniforme. Cada ID puede tener hasta 16 dígitos decimales.
• La política legacy crea una secuencia de IDs de números enteros no consecutivos más breves.

Si quieres mostrar al usuario los IDs de la entidad o depender de su pedido, lo mejor que puedes hacer es usar la asignación manual.

Nota: En lugar de usar strings de nombre de clave o generar IDs numéricos de forma automática, en las aplicaciones avanzadas, tal vez resulte más conveniente asignar IDs numéricos propios de forma manual a las entidades creadas. Sin embargo, ten en cuenta que nada impide que Datastore asigne uno de tus IDs numéricos manuales a otra entidad. La única forma de impedir ese conflicto es pedir a la aplicación que obtenga un bloque de varios IDs con los métodos DatastoreService.allocateIds() o la función AsyncDatastoreService.allocateIds() . El generador automático de ID de Datastore llevará un registro de los IDs asignados con estos métodos evitará volver a usarlos para otra entidad; de esta manera, podrás usarlos sin que se generen conflictos.

Datastore genera una secuencia aleatoria de IDs sin usar con una distribución bastante uniforme. Cada ID puede tener hasta 16 dígitos decimales.

Rutas de 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 superior, en cuyo caso la nueva entidad es secundaria respecto de la entidad superior (ten en cuenta que, a diferencia de lo que ocurre en un sistema de archivos, no es necesario que efectivamente exista una entidad superior). Las entidades que no tienen una principal se denominan entidades raíz. La asociación entre una entidad secundaria y la entidad superior es permanente, y no puede cambiarse una vez creada la entidad. Cloud Datastore nunca asignará el mismo ID numérico a dos entidades asociadas a la misma entidad superior ni a dos entidades raíz (no asociadas a una entidad superior).

La entidad superior de una entidad determinada, la superior de la superior y así sucesivamente son sus principales. Las entidades secundarias respecto de una entidad determinada, las secundarias de las secundarias 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 principal a secundaria, hasta llegar a una entidad determinada, constituye la ruta de principal de esa entidad. La clave completa que identifica una entidad consta de una secuencia de pares de tipo-identificador que especifican la ruta de principales y terminan con el tipo y el identificador de la propia entidad:

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

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

[Person:GreatGrandpa]

Este concepto se ilustra en el diagrama siguiente:

Para designar la entidad principal respecto de una secundaria, proporciona la clave de la entidad principal como argumento al constructor Entity() cuando creas la entidad secundaria. Para obtener la clave, llama al método getKey() de la entidad principal:

Entity employee = new Entity("Employee");
datastore.put(employee);

Entity address = new Entity("Address", employee.getKey());
datastore.put(address);

Si la entidad nueva también tiene un nombre de clave, proporciona el nombre de clave como el segundo argumento al constructor Entity() y la clave de la entidad principal como tercer argumento:

Entity address = new Entity("Address", "addr1", employee.getKey());

Transacciones y grupos de entidades

Cada intento de crear, 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 conservar la coherencia de los datos, la transacción garantiza que todas las operaciones que contiene se apliquen a Datastore como una unidad o, si alguna de ellas falla, que no se aplique ninguna. Además, todas las operaciones de lectura de coherencia sólida (consultas principales o get) que se realizan dentro de la misma transacción ven una sola instantánea coherente de los datos.

Nota: Si la aplicación recibe una de

Recomendamos usar la biblioteca cliente de NDB para Datastore, que tiene varios beneficios en comparación con esta biblioteca cliente, como el almacenamiento en caché automático de entidades con la API de Memcache. Si actualmente usas la biblioteca cliente de DB anterior, ve la guía de migración de DB a NDB.