Documentation sur les propriétés d'entité

Cette API est compatible avec les environnements d'exécution de première génération et peut être utilisée lors de la mise à niveau vers des environnements d'exécution de deuxième génération correspondants. Si vous effectuez une mise à jour vers l'environnement d'exécution Java 11/17 d'App Engine, consultez le guide de migration pour en savoir plus sur les options de migration des anciens services groupés.

Firestore en mode Datastore (Datastore) est compatible avec divers types de données pour les valeurs de propriété, parmi lesquels :

• Entiers
• Nombres à virgule flottante
• Chaînes
• Dates
• Données binaires

Pour obtenir la liste complète des types, consultez la section Propriétés et types de valeurs.

Propriétés et types de valeurs

Les valeurs de données associées à une entité consistent en une ou plusieurs propriétés. Chaque propriété a un nom, et une ou plusieurs valeurs. Une propriété peut avoir des valeurs de plus d'un type, et deux entités peuvent avoir des valeurs de types différents pour la même propriété. Les propriétés peuvent être indexées ou non indexées (les requêtes qui ordonnent ou filtrent une propriété P ignorent les entités pour lesquelles P n'est pas indexée.) Une entité peut avoir 20 000 propriétés indexées au maximum.

Remarque : Les propriétés comportant plusieurs valeurs peuvent être utiles. Par exemple lors de l'exécution de requêtes avec des filtres d'égalité, une entité satisfait à la requête si l'une de ses valeurs de propriété correspond à la valeur spécifiée dans le filtre. Pour en savoir plus sur les propriétés à valeurs multiples, y compris sur les problèmes dont vous devez avoir connaissance, consultez la page Requêtes Datastore.

Les types de valeurs suivants sont acceptés :

Type de valeur	Type Java	Ordre de tri	Remarques
Entier	short int long java.lang.Short java.lang.Integer java.lang.Long	Numérique	Stocké sous forme d'entier long, puis converti au type de champ Dépassement des valeurs hors plage
Nombre à virgule flottante	float double java.lang.Float java.lang.Double	Numérique	Double précision 64 bits, IEEE 754.
Booléen	boolean java.lang.Boolean	false<true
Chaîne de texte (courte)	java.lang.String	Unicode	Jusqu'à 1 500 octets Valeurs supérieures à 1 500 octets renvoient IllegalArgumentException
Chaîne de texte (longue)	com.google.appengine.api.datastore.Text	Aucune	Jusqu'à 1 mégaoctet Non indexé
Chaînes d'octets (courtes)	com.google.appengine.api.datastore.ShortBlob	Ordre des octets	Jusqu'à 1 500 octets Valeurs supérieures à 1 500 octets renvoient IllegalArgumentException
Chaîne d'octets (longue)	com.google.appengine.api.datastore.Blob	Aucune	Jusqu'à 1 mégaoctet Non indexé
Date et heure	java.util.Date	Chronologique
Point géographique	com.google.appengine.api.datastore.GeoPt	En fonction de la latitude, puis de la longitude
Adresse postale	com.google.appengine.api.datastore.PostalAddress	Unicode
Numéro de téléphone	com.google.appengine.api.datastore.PhoneNumber	Unicode
Adresse e-mail	com.google.appengine.api.datastore.Email	Unicode
Utilisateur de Google Accounts	com.google.appengine.api.users.User	Adresse e-mail dans l'ordre Unicode
Descripteur de messagerie instantanée	com.google.appengine.api.datastore.IMHandle	Unicode
Lien	com.google.appengine.api.datastore.Link	Unicode
Catégorie	com.google.appengine.api.datastore.Category	Unicode
Note	com.google.appengine.api.datastore.Rating	Numérique
Clé Datastore	com.google.appengine.api.datastore.Key ou l'objet référencé (en tant qu'enfant)	Par éléments de chemin d'accès (genre, identifiant, genre, identifiant, etc.)	Jusqu'à 1 500 octets Valeurs supérieures à 1 500 octets renvoient IllegalArgumentException
Clé Blobstore	com.google.appengine.api.blobstore.BlobKey	Ordre des octets
Entité intégrée	com.google.appengine.api.datastore.EmbeddedEntity	Aucune	Pas indexé
Vide	null	Aucune

Important : Nous vous recommandons vivement de ne pas enregistrer de valeur de propriété users.User, car elle inclut l'adresse e-mail et l'ID unique. Si un utilisateur change d'adresse e-mail et que vous comparez l'ancienne valeur user.User stockée à la nouvelle valeur user.User, elles ne correspondront pas. Envisagez plutôt d'utiliser la valeur d'ID d'utilisateur User comme identifiant unique stable de l'utilisateur.

Pour les chaînes de texte et les données binaires non codées (chaînes d'octets), Datastore prend en charge deux types de valeurs :

• Les chaînes courtes (jusqu'à 1 500 octets) sont indexées et peuvent être utilisées dans les conditions de filtre de requêtes et les ordres de tri.
• Les chaînes longues (jusqu'à 1 Mo) ne sont pas indexées et ne peuvent pas être utilisées dans les filtres de requête et les ordres de tri.

Remarque : Le type d'une chaîne d'octets longue est appelé Blob dans l'API Datastore. Ce type n'est pas lié aux objets blob utilisés dans l'API Blobstore.

Lorsqu'une requête implique une propriété avec des valeurs de types mixtes, Datastore utilise un ordre déterministe basé sur les représentations internes :

1. Valeurs Null
2. Nombres à virgule fixe
   • Entiers
   • Dates et heures
   • Notes
3. Valeurs booléennes
4. Séquences d'octets
   • Chaîne d'octets
   • Chaîne Unicode
   • Clés Blobstore
5. Nombres à virgule flottante
6. Points géographiques
7. Utilisateurs disposant d'un compte Google
8. Clés Datastore

Aucun ordre n'est défini pour les chaînes de texte longues et les chaînes d'octets longues, car elles ne sont pas indexées.

Remarque : Les entiers et les nombres à virgule flottante sont considérés comme des types distincts dans Datastore. Si une entité emploie un mélange d'entiers et de nombres à virgule flottante pour la même propriété, les entiers sont triés avant les nombres à virgule flottante. Exemple :

7 < 3.2

Propriétés répétées

Vous pouvez stocker plusieurs valeurs dans une même propriété.

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

Entités intégrées

Il peut parfois être utile d'intégrer une entité en tant que propriété d'une autre entité. Cela peut être utile, par exemple, pour créer une structure hiérarchique de valeurs de propriété au sein d'une entité. La classe Java EmbeddedEntity vous permet d'effectuer les opérations suivantes :

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

Les propriétés d'une entité intégrée ne sont pas indexées et ne peuvent pas être utilisées dans les requêtes. Si vous le souhaitez, vous pouvez associer une clé à une entité intégrée, mais contrairement à une entité complète, la clé n'est pas obligatoire. De plus, même si elle est présente, elle ne peut pas être utilisée pour récupérer l'entité.

Au lieu de renseigner manuellement les propriétés de l'entité intégrée, vous pouvez utiliser la méthode setPropertiesFrom() pour les copier à partir d'une entité existante :

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

Vous pouvez utiliser ultérieurement la même méthode pour récupérer l'entité d'origine à partir de l'entité intégrée :

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

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

Utiliser une liste vide

Auparavant, Datastore n'avait pas de représentation pour une propriété représentant une liste vide. Le SDK Java a résolu ce problème en stockant les collections vides en tant que valeurs Null. Il n'y a donc aucun moyen de distinguer les valeurs Null des listes vides. Pour assurer la rétrocompatibilité, ce comportement par défaut s'applique toujours, comme résumé ci-dessous :

• Les propriétés Null sont écrites comme nulles dans Datastore.
• Les collections vides sont écrites comme nulles dans Datastore.
• Une valeur Null est lue comme étant nulle à partir de Datastore.
• Les collections vides sont lues comme étant Null.

Important : Une opération de lecture-modification-écriture d'une entité avec une liste vide entraînera la transformation de cette liste en valeur Null.

Toutefois, si vous modifiez le comportement par défaut, le SDK Java Appengine Datastore prendra en charge le stockage de listes vides. Nous vous recommandons de prendre en compte les conséquences de la modification du comportement par défaut de votre application, puis d'activer la prise en charge des listes vides.

Pour modifier le comportement par défaut afin d'utiliser des listes vides, définissez la propriété DATASTORE_EMPTY_LIST_SUPPORT lors de l'initialisation de votre application comme suit :

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

Avec cette propriété définie sur true, comme illustré ci-dessus :

• Les propriétés Null sont écrites comme nulles dans Datastore.
• Les collections vides sont écrites sous forme de liste vide dans Datastore.
• Une valeur Null est lue comme étant nulle à partir de Datastore.
• Lors de la lecture depuis Datastore, une liste vide est renvoyée sous forme de collection vide.

Important : Vos requêtes peuvent être affectées lorsque vous activez la compatibilité des listes vides. Les valeurs Null sont indexées dans Datastore, mais pas les listes vides. Si vous stockiez des listes vides en tant que listes Null et si vous lanciez des requêtes Null pour les trouver, ces requêtes ne retourneraient plus de résultats si vous transformiez ces listes en listes vides.