Referencia de propiedad de la entidad

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.

Tipos de valores y propiedades

Los valores de datos asociados con una entidad constan de una o más propiedades. Cada propiedad tiene un nombre y uno o más valores. Una propiedad puede tener valores de más de un tipo, y dos entidades pueden tener valores de diferentes tipos para la misma propiedad. Las propiedades pueden o no estar indexadas (las consultas que ordenan o filtran en una propiedad P ignorarán las entidades en las que P no esté indexada). Una entidad puede tener como máximo 20,000 propiedades indexadas.

Se admiten los tipos de valor siguientes:

Tipo de valor Tipo(s) de Java Ordenar por Notas
Número entero short
int
long
java.lang.Short
java.lang.Integer
java.lang.Long
Numérico Se almacena como un número entero largo y, luego, se convierte al tipo de campo

Los valores fuera de rango se superponen
Número de punto flotante float
double
java.lang.Float
java.lang.Double
Numérico Precisión doble de 64 bits,
IEEE 754
Booleano boolean
java.lang.Boolean
false<true
String de texto (corta) java.lang.String Unicode Hasta 1,500 bytes

Valores superiores a 1,500 bytes IllegalArgumentException
String de texto (larga) com.google.appengine.api.datastore.Text Ninguna Hasta 1 megabyte

Sin indexar
String de bytes (corta) com.google.appengine.api.datastore.ShortBlob Orden de bytes Hasta 1,500 bytes

Valores más largos que 1,500 bytes IllegalArgumentException
String de bytes (larga) com.google.appengine.api.datastore.Blob Ninguna Hasta 1 megabyte

Sin indexar
Fecha y hora java.util.Date Cronológico
Punto geográfico com.google.appengine.api.datastore.GeoPt Por latitud,
luego por longitud
Dirección postal com.google.appengine.api.datastore.PostalAddress Unicode
Número de teléfono com.google.appengine.api.datastore.PhoneNumber Unicode
Dirección de correo electrónico com.google.appengine.api.datastore.Email Unicode
Usuario de Cuentas de Google com.google.appengine.api.users.User Dirección de correo electrónico
en orden Unicode
Controlador de mensajería instantánea com.google.appengine.api.datastore.IMHandle Unicode
Vínculo com.google.appengine.api.datastore.Link Unicode
Categoría com.google.appengine.api.datastore.Category Unicode
Calificación com.google.appengine.api.datastore.Rating Numérico
Clave de Datastore com.google.appengine.api.datastore.Key
o el objeto referenciado (como secundario)
Por elementos de ruta de acceso
(tipo, identificador,
tipo, identificador…)
Hasta 1,500 bytes

Valores más largos que 1,500 bytes IllegalArgumentException
Clave de Blobstore com.google.appengine.api.blobstore.BlobKey Orden de bytes
Entidad incorporada com.google.appengine.api.datastore.EmbeddedEntity Ninguna No indexada
Nulo null Ninguna

Importante: Se recomienda evitar almacenar users.User como valor de propiedad porque incluye la dirección de correo electrónico junto con el ID único. Si un usuario cambia su dirección de correo electrónico y la comparas su user.User anterior almacenado con el valor de user.User nuevo, no coincidirán. En su lugar, usa el valor de ID del usuario User como el identificador único estable del usuario.

Para strings de texto y datos binarios sin codificación (strings de bytes), Datastore es compatible con dos tipos de valores:

  • Las strings cortas (hasta 1,500 bytes) se indexan y pueden usarse en condiciones de filtros de consultas y para ordenar elementos.
  • Las strings largas (de hasta 1 megabyte) no se indexan ni pueden usarse en filtros de consultas ni para ordenar elementos.
Nota: El tipo de string de byte largo se denomina Blob en la API de Datastore. Este tipo no está relacionado con los BLOB, como se usa en la API de Blobstore.

Cuando una consulta incluye una propiedad con valores de varios tipos, Datastore usa un orden determinista basado en representaciones internas:

  1. Valores nulos
  2. Números de coma fija
    • Números enteros
    • Fechas y horas
    • Calificaciones
  3. Valores booleanos
  4. Secuencias de bytes
    • String de bytes
    • String de Unicode
    • Claves de Blobstore
  5. Números de coma flotante
  6. Puntos geográficos
  7. Usuarios de Cuentas de Google
  8. Claves de Datastore

Debido a que las strings de texto largas, las strings de bytes largas y las entidades incorporadas no se indexan, no tienen orden definido.

Propiedades repetidas

Puedes almacenar varios valores dentro de una sola propiedad.

Entity employee = new Entity("Employee");
ArrayList<String> favoriteFruit = new ArrayList<String>();
favoriteFruit.add("Pear");
favoriteFruit.add("Apple");
employee.setProperty("favoriteFruit", favoriteFruit);
datastore.put(employee);

// Sometime later
employee = datastore.get(employee.getKey());
@SuppressWarnings("unchecked") // Cast can't verify generic type.
    ArrayList<String> retrievedFruits = (ArrayList<String>) employee
    .getProperty("favoriteFruit");

Entidades incorporadas

A veces puede resultar práctico incorporar una entidad como una propiedad de otra entidad. Esto puede ser útil, por ejemplo, para crear una estructura jerárquica de valores de propiedad dentro de una entidad. La clase EmbeddedEntity de Java te permite realizar las siguientes acciones:

// Entity employee = ...;
EmbeddedEntity embeddedContactInfo = new EmbeddedEntity();

embeddedContactInfo.setProperty("homeAddress", "123 Fake St, Made, UP 45678");
embeddedContactInfo.setProperty("phoneNumber", "555-555-5555");
embeddedContactInfo.setProperty("emailAddress", "test@example.com");

employee.setProperty("contactInfo", embeddedContactInfo);

Las propiedades de una entidad incorporada no se indexan y no se pueden usar en consultas. De forma opcional, puedes asociar una clave con una entidad incorporada, pero, a diferencia de una entidad completa, no es necesaria la clave y, aunque exista, no se puede usar para recuperar la entidad.

En lugar de propagar las propiedades de la entidad incorporada, puedes usar el método setPropertiesFrom() para copiarlas desde una entidad existente:

// Entity employee = ...;
// Entity contactInfo = ...;
EmbeddedEntity embeddedContactInfo = new EmbeddedEntity();

embeddedContactInfo.setKey(contactInfo.getKey()); // Optional, used so we can recover original.
embeddedContactInfo.setPropertiesFrom(contactInfo);

employee.setProperty("contactInfo", embeddedContactInfo);

Puedes usar más adelante el mismo método para recuperar la entidad original de la entidad incorporada:

Entity employee = datastore.get(employeeKey);
EmbeddedEntity embeddedContactInfo = (EmbeddedEntity) employee.getProperty("contactInfo");

Key infoKey = embeddedContactInfo.getKey();
Entity contactInfo = new Entity(infoKey);
contactInfo.setPropertiesFrom(embeddedContactInfo);

Usa una lista vacía

Históricamente, Datastore no tenía una representación para una propiedad que represente una lista vacía. El SDK de Java solucionó esto almacenando colecciones vacías como valores nulos, por lo que no hay manera de distinguir entre valores nulos y listas vacías. Para mantener la retrocompatibilidad, este sigue siendo el comportamiento predeterminado, que se resume de la siguiente manera:

  • Las propiedades nulas se escriben como nulas en Datastore.
  • Las colecciones vacías se escriben como nulas en Datastore.
  • Un nulo se lee como nulo desde Datastore.
  • Una colección vacía se lee como nula.

Sin embargo, si modificas el comportamiento predeterminado, el SDK para Java de Appengine Datastore será compatible con el almacenamiento de listas vacías. Recomendamos que consideres las consecuencias de modificar el comportamiento predeterminado de tu aplicación y, luego, actives la asistencia para listas vacías.

Para cambiar el comportamiento predeterminado a fin de que puedas usar listas vacías, configura la propiedad DATASTORE_EMPTY_LIST_SUPPORT durante la inicialización de tu app, de la siguiente manera:

System.setProperty(DatastoreServiceConfig.DATASTORE_EMPTY_LIST_SUPPORT, Boolean.TRUE.toString());

Con esta propiedad configurada en true como se muestra arriba, ocurre lo siguiente:

  • Las propiedades nulas se escriben como nulas en Datastore.
  • Las colecciones vacías se escriben como lista vacía en Datastore.
  • Un nulo se lee como nulo desde Datastore.
  • Cuando se lee desde Datastore, se muestra una lista vacía como una Colección vacía.