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

Cloud 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é. Une propriété peut être indexée ou non indexée (les requêtes qui trient ou filtrent en fonction d'une propriété P ignoreront les entités où cette propriété P est non indexée). Une entité peut avoir 20 000 propriétés indexées au maximum.

Les types de valeurs suivants sont acceptés :

Type de valeur Type Java Ordre de tri Notes
Entier short
int
long
java.lang.Short
java.lang.Integer
java.lang.Long
Numérique Stocké en tant qu'entier long, puis converti en type de champ

Les valeurs hors plage provoquent un dépassement.
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

Les valeurs supérieures à 1 500 octets renvoient IllegalArgumentException.
Chaîne de texte (longue) com.google.appengine.api.datastore.Text Aucun Jusqu'à 1 mégaoctet

Pas indexé
Chaînes d'octets (courtes) com.google.appengine.api.datastore.ShortBlob Ordre des octets Jusqu'à 1 500 octets

Les valeurs supérieures à 1 500 octets renvoient IllegalArgumentException
Chaîne d'octets (longue) com.google.appengine.api.datastore.Blob Aucun Jusqu'à 1 mégaoctet

Pas indexé
Date et heure java.util.Date Chronologique
Point géographique com.google.appengine.api.datastore.GeoPt Par latitude,
puis par 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é Cloud Datastore com.google.appengine.api.datastore.Key
ou l'objet référencé (en tant qu'enfant)
Par éléments de chemin
(genre, identifiant,
genre, identifiant…)
Jusqu'à 1 500 octets

Les 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 Aucun Pas indexé
Vide null Aucun

Important : Nous vous recommandons vivement d'éviter de stocker users.User en tant que valeur de propriété, car cela inclut l'adresse e-mail ainsi que 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, vous verrez qu'elles ne correspondent pas. Envisagez plutôt d'utiliser la valeur d'ID 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), Cloud Datastore accepte 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 Cloud Datastore. Il n'a pas de rapport avec les blobs utilisés dans l'API Blobstore.

Lorsqu'une requête implique une propriété avec des valeurs de différents types, Cloud Datastore emploie 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 Cloud 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.

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

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

Java 8

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

Java 7

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 de faire cela :

Java 8

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

Java 7

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

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 :

Java 8

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

Java 7

// 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 :

Java 8

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

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

Java 7

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, Cloud 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 étant Null dans Cloud Datastore.
  • Les collections vides sont écrites comme étant Null dans Cloud Datastore.
  • Les valeurs Null sont lues comme étant Null à partir de Cloud Datastore.
  • Les collections vides sont lues comme étant 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 de manière à pouvoir 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 indiqué ci-dessus :

  • Les propriétés Null sont écrites comme étant Null dans Cloud Datastore.
  • Les collections vides sont écrites sous forme de liste vide dans Cloud Datastore
  • Les valeurs Null sont lues comme étant Null à partir de Cloud Datastore.
  • Lors de la lecture depuis Cloud Datastore, une liste vide est renvoyée sous forme de collection vide.
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Environnement standard App Engine pour Java 8