Referencia de propiedad de la entidad

Esta API es compatible con entornos de ejecución de primera generación y se puede usar en actualizaciones a los entornos de ejecución de segunda generación correspondientes. Si actualizas al entorno de ejecución de Java 11/17 de App Engine, consulta la guía de migración para obtener información acerca de tus opciones de migración para servicios agrupados en paquetes heredados.

Firestore en modo Datastore (Datastore) admite una variedad de tipos de datos para valores de propiedad. Se incluyen, entre otros:

• Números enteros
• números de punto 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.

Nota: Las propiedades con varios valores pueden ser útiles, por ejemplo, cuando se realizan consultas con filtros de igualdad; una entidad satisface la consulta si algún valor de una propiedad coincide con el valor especificado en el filtro. Para obtener más detalles sobre las propiedades con varios valores, incluidos algunos problemas que debes tener en cuenta, consulta la página Consultas de Datastore.

Se admiten los tipos de valor siguientes:

Tipo de valor	Tipo(s) de Java	Orden	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
Null	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 bytes larga 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.

Nota: Los números enteros y los números de punto flotante se consideran tipos separados en Datastore. Si una entidad usa una combinación de números enteros y de números de punto flotante para la misma propiedad, todos los enteros se ordenarán antes de los de coma flotante: por ejemplo,

7 < 3.2

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", "[e-mail]");

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);

Más adelante, puedes usar 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.

Importante: Una escritura de modificación de lectura de una entidad con una lista vacía causará que la lista se convierta en un valor nulo.

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.

Importante: Tus consultas podrían verse afectadas cuando actives la asistencia para listas vacías. Los valores nulos se indexan en Datastore, pero no las listas vacías. Si almacenaste listas vacías como nulas y, luego, realizaste consultas de valores nulos para encontrarlas, cambiar a lista vacía hará que esas consultas no muestren resultados.