Referencia de propiedades de entidades

Esta API es compatible con los tiempos de ejecución de primera generación y se puede usar al actualizar a los tiempos de ejecución de segunda generación correspondientes. Si vas a actualizar al tiempo de ejecución de Java 11/17 de App Engine, consulta la guía de migración para obtener información sobre las opciones de migración de los servicios empaquetados antiguos.

Firestore en el modo de Datastore (Datastore) admite varios tipos de datos para los valores de las propiedades. Entre ellos, se incluyen los siguientes:

• Números enteros
• Números de punto flotante
• Cadenas
• Fechas
• Datos binarios

Para ver una lista completa de los tipos, consulta Propiedades y tipos de valor.

Propiedades y tipos de valores

Los valores de datos asociados a una entidad constan de una o varias propiedades. Cada propiedad tiene un nombre y uno o varios valores. Una propiedad puede tener valores de más de un tipo, y dos entidades pueden tener valores de tipos diferentes para la misma propiedad. Las propiedades pueden estar indexadas o no (las consultas que ordenan o filtran por 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, al realizar consultas con filtros de igualdad: una entidad cumple la consulta si alguno de sus valores de una propiedad coincide con el valor especificado en el filtro. Para obtener más información sobre las propiedades de varios valores, incluidos los problemas que debes tener en cuenta, consulta la página Consultas de Datastore.

Se admiten los siguientes tipos de valores:

Tipo de valor	Tipo(s) de Java	Ordenar por	Notas
Entero	short int long java.lang.Short java.lang.Integer java.lang.Long	Numérico	Se almacena como un entero largo y, a continuación, se convierte al tipo de campo. Los valores fuera del intervalo provocan un desbordamiento.
Número de punto flotante	float double java.lang.Float java.lang.Double	Numérico	Doble precisión de 64 bits, IEEE 754
Booleano	boolean java.lang.Boolean	false<true
Cadena de texto (corta)	java.lang.String	Unicode	Hasta 1500 bytes Si el valor supera los 1500 bytes, se produce un error IllegalArgumentException
Cadena de texto (larga)	com.google.appengine.api.datastore.Text	Ninguno	Hasta 1 megabyte Sin indexar
cadena de bytes (corta)	com.google.appengine.api.datastore.ShortBlob	Orden de bytes	Hasta 1500 bytes Si los valores superan los 1500 bytes, se produce un error IllegalArgumentException
Cadena de bytes (larga)	com.google.appengine.api.datastore.Blob	Ninguno	Hasta 1 megabyte Sin indexar
Fecha y hora	java.util.Date	Cronológico
Punto geográfico	com.google.appengine.api.datastore.GeoPt	Por latitud, y 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
usuarios de Cuentas de Google	com.google.appengine.api.users.User	Dirección de correo electrónico en orden Unicode
Identificador de mensajería instantánea	com.google.appengine.api.datastore.IMHandle	Unicode
Enlace	com.google.appengine.api.datastore.Link	Unicode
Categoría	com.google.appengine.api.datastore.Category	Unicode
Valoración	com.google.appengine.api.datastore.Rating	Numérico
Clave de Datastore	com.google.appengine.api.datastore.Key o el objeto al que se hace referencia (como elemento secundario)	Por elementos de ruta (tipo, identificador, tipo, identificador...)	Hasta 1500 bytes Si los valores superan los 1500 bytes, se produce un error IllegalArgumentException
Clave de Blobstore	com.google.appengine.api.blobstore.BlobKey	Orden de bytes
Entidad insertada	com.google.appengine.api.datastore.EmbeddedEntity	Ninguno	No indexado
Nulo	null	Ninguno

Importante: Le recomendamos que no almacene un users.User como valor de propiedad, ya que incluye la dirección de correo electrónico junto con el ID único. Si un usuario cambia su dirección de correo y comparas el valor antiguo almacenado user.User con el nuevo user.User, no coincidirán. En su lugar, use el User valor del ID de usuario como identificador único estable del usuario.

En el caso de las cadenas de texto y los datos binarios sin codificar (cadenas de bytes), Datastore admite dos tipos de valores:

• Las cadenas cortas (de hasta 1500 bytes) se indexan y se pueden usar en condiciones de filtro de consultas y en criterios de ordenación.
• Las cadenas largas (de hasta 1 megabyte) no se indexan y no se pueden usar en filtros de consultas ni en criterios de ordenación.

Nota: El tipo de cadena de bytes larga se llama Blob en la API de Datastore. Este tipo no está relacionado con los blobs que se usan en la API Blobstore.

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

1. valores nulos
2. Números de coma fija
   • Números enteros
   • Fechas y horas
   • Valoraciones
3. valores booleanos
4. Secuencias de bytes
   • Cadena de bytes
   • Cadena Unicode
   • claves del almacén de blob
5. Números de punto flotante
6. Puntos geográficos
7. Usuarios de cuentas de Google
8. Claves de Datastore

Como no se indexan las cadenas de texto largas, las cadenas de bytes largas ni las entidades insertadas, no tienen ningún orden definido.

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

7 < 3.2

.

Propiedades repetidas

Puedes almacenar varios valores en 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 insertadas

A veces, puede que te resulte útil insertar una entidad como propiedad de otra. Esto puede ser útil, por ejemplo, para crear una estructura jerárquica de valores de propiedad en una entidad. La clase de Java EmbeddedEntity te permite hacer lo siguiente:

// 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 insertada no se indexan y no se pueden usar en consultas. Opcionalmente, puedes asociar una clave a una entidad insertada, pero (a diferencia de una entidad completa) la clave no es obligatoria y, aunque esté presente, no se puede usar para recuperar la entidad.

En lugar de rellenar las propiedades de la entidad insertada manualmente, puedes usar el método setPropertiesFrom() para copiarlas de una entidad que ya tengas:

// 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 a partir de la entidad insertada:

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

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

Usar una lista vacía

Históricamente, Datastore no tenía una representación de una propiedad que representara una lista vacía. El SDK de Java solucionó este problema almacenando colecciones vacías como valores nulos, por lo que no hay forma 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
• Datastore lee un valor nulo como nulo
• Una colección vacía se lee como nula.

Importante: Si se lee, modifica y escribe una entidad con una lista vacía, esa lista se convertirá en un valor nulo.

Sin embargo, si cambias el comportamiento predeterminado, el SDK de Java de Datastore de App Engine admitirá el almacenamiento de listas vacías. Te recomendamos que tengas en cuenta las implicaciones de cambiar el comportamiento predeterminado de tu aplicación y que actives la compatibilidad con listas vacías.

Para cambiar el comportamiento predeterminado y poder usar listas vacías, define la propiedad DATASTORE_EMPTY_LIST_SUPPORT durante la inicialización de la aplicación de la siguiente manera:

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

Si esta propiedad tiene el valor true, como se muestra arriba:

• Las propiedades nulas se escriben como nulas en Datastore
• Las colecciones vacías se escriben en Datastore como una lista vacía
• Datastore lee un valor nulo como nulo
• Cuando se lee de Datastore, se devuelve una lista vacía como una colección vacía.

Importante: Tus consultas pueden verse afectadas si activas la compatibilidad con listas vacías. Los valores nulos se indexan en Datastore, pero las listas vacías no. Si almacenabas listas vacías como valores nulos y, después, consultabas los valores nulos para encontrarlas, al cambiar a listas vacías, estas consultas no devolverán resultados.