Riferimento alle proprietà delle entità

Firestore in modalità Datastore (Datastore) supporta diversi tipi di dati per i valori delle proprietà. tra cui:

  • Numeri interi
  • Numeri in virgola mobile
  • Stringhe
  • Date
  • Dati binari

Per un elenco completo dei tipi, consulta Proprietà e tipi di valori.

Proprietà e tipi di valore

I valori dei dati associati a un'entità sono costituiti da una o più proprietà. Ogni proprietà ha un nome e uno o più valori. Una proprietà può avere valori di più di un tipo e due entità possono avere valori di tipi diversi per la stessa proprietà. Le proprietà possono essere indicizzate o non indicizzate (le query che ordinano o filtrano in base a una proprietà P ignorano le entità in cui P non è indicizzata). Un'entità può avere al massimo 20.000 proprietà indicizzate.

Sono supportati i seguenti tipi di valori:

Tipo di valore Tipi Java Ordinamento Note
Numero intero short
int
long
java.lang.Short
java.lang.Integer
java.lang.Long
Numerico Memorizzato come numero intero lungo, quindi convertito nel tipo di campo

Overflow dei valori fuori intervallo
Numero in virgola mobile float
double
java.lang.Float
java.lang.Double
Numerico Precisione doppia a 64 bit,
IEEE 754
Booleano boolean
java.lang.Boolean
false<true
Stringa di testo (breve) java.lang.String Unicode Fino a 1500 byte

I valori superiori a 1500 byte generano un errore IllegalArgumentException
Stringa di testo (lunga) com.google.appengine.api.datastore.Text Nessuno Fino a 1 megabyte

Non indicizzate
Stringa di byte (breve) com.google.appengine.api.datastore.ShortBlob Ordine dei byte Fino a 1500 byte

I valori più lunghi di 1500 byte generano un errore IllegalArgumentException
Stringa di byte (lunga) com.google.appengine.api.datastore.Blob Nessuno Fino a 1 megabyte

Non indicizzate
Data e ora java.util.Date Cronologica
Punto geografico com.google.appengine.api.datastore.GeoPt Per latitudine,
poi per longitudine
Indirizzo postale com.google.appengine.api.datastore.PostalAddress Unicode
Numero di telefono com.google.appengine.api.datastore.PhoneNumber Unicode
Indirizzo email com.google.appengine.api.datastore.Email Unicode
Utente Account Google com.google.appengine.api.users.User Indirizzo email
in ordine Unicode
Handle di messaggistica istantanea com.google.appengine.api.datastore.IMHandle Unicode
Link com.google.appengine.api.datastore.Link Unicode
Categoria com.google.appengine.api.datastore.Category Unicode
Valutazione com.google.appengine.api.datastore.Rating Numerico
Chiave Datastore com.google.appengine.api.datastore.Key
o l'oggetto a cui viene fatto riferimento (come elemento secondario)
Per elementi del percorso
(kind, identifier,
kind, identifier...)
Fino a 1500 byte

I valori più lunghi di 1500 byte generano un errore IllegalArgumentException
Chiave Blobstore com.google.appengine.api.blobstore.BlobKey Ordine dei byte
Entità incorporata com.google.appengine.api.datastore.EmbeddedEntity Nessuno Non indicizzato
Null null Nessuno

Importante:ti consigliamo vivamente di evitare di memorizzare un users.User come valore di proprietà, perché include l'indirizzo email insieme all'ID univoco. Se un utente cambia il proprio indirizzo email e confronti il vecchio user.User memorizzato con il nuovo valore user.User, i valori non corrisponderanno. Utilizza invece il User valore dell'ID utente come identificatore univoco stabile dell'utente.

Per le stringhe di testo e i dati binari non codificati (stringhe di byte), Datastore supporta due tipi di valori:

  • Le stringhe brevi (fino a 1500 byte) vengono indicizzate e possono essere utilizzate nelle condizioni di filtro delle query e negli ordini di ordinamento.
  • Le stringhe lunghe (fino a 1 megabyte) non vengono indicizzate e non possono essere utilizzate nei filtri delle query e negli ordini di ordinamento.
Nota: il tipo di stringa di byte lunga si chiama Blob nell'API Datastore. Questo tipo non è correlato ai BLOB come utilizzati nell'API Blobstore.

Quando una query coinvolge una proprietà con valori di tipi misti, Datastore utilizza un ordinamento deterministico basato sulle rappresentazioni interne:

  1. Valori null
  2. Numeri a virgola fissa
    • Numeri interi
    • Date e ore
    • Valutazioni
  3. Valori booleani
  4. Sequenze di byte
    • Stringa di byte
    • Stringa Unicode
    • Chiavi dell'archivio BLOB
  5. Numeri in virgola mobile
  6. Punti geografici
  7. Utenti con account Google
  8. Chiavi del datastore

Poiché le stringhe di testo lunghe, le stringhe di byte lunghe e le entità incorporate non sono indicizzate, non hanno un ordine definito.

Proprietà ripetute

Puoi memorizzare più valori in un'unica proprietà.

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à incorporate

A volte può essere utile incorporare un'entità come proprietà di un'altra entità. Ciò può essere utile, ad esempio, per creare una struttura gerarchica dei valori delle proprietà all'interno di un'entità. La classe Java EmbeddedEntity ti consente di:

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

Le proprietà di un'entità incorporata non sono indicizzate e non possono essere utilizzate nelle query. Se vuoi, puoi associare una chiave a un'entità incorporata, ma (a differenza di un'entità a tutti gli effetti) la chiave non è obbligatoria e, anche se presente, non può essere utilizzata per recuperare l'entità.

Anziché compilare manualmente le proprietà dell'entità incorporata, puoi utilizzare il metodo setPropertiesFrom() per copiarle da un'entità esistente:

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

In un secondo momento, puoi utilizzare lo stesso metodo per recuperare l'entità originale dall'entità incorporata:

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

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

Utilizzo di un elenco vuoto

In passato, Datastore non aveva una rappresentazione per una proprietà che rappresenta un elenco vuoto. L'SDK Java ha risolto il problema memorizzando le raccolte vuote come valori null, quindi non è possibile distinguere tra valori null e elenchi vuoti. Per mantenere la compatibilità con le versioni precedenti, questo rimane il comportamento predefinito, riassunto come segue:

  • Le proprietà null vengono scritte come null in Datastore
  • Le raccolte vuote vengono scritte come null in Datastore
  • Un valore null viene letto come null da Datastore
  • Una raccolta vuota viene letta come null.

Tuttavia, se modifichi il comportamento predefinito, l'SDK Java di App Engine Datastore supporterà lo stoccaggio degli elenchi vuoti. Ti consigliamo di valutare le implicazioni della modifica del comportamento predefinito della tua applicazione e di attivare il supporto per gli elenchi vuoti.

Per modificare il comportamento predefinito in modo da poter utilizzare gli elenchi vuoti, imposta la proprietà DATASTORE_EMPTY_LIST_SUPPORT durante l'inizializzazione dell'app come segue:

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

Con questa proprietà impostata su true come mostrato sopra:

  • Le proprietà null vengono scritte come null in Datastore
  • Le raccolte vuote vengono scritte in Datastore come elenco vuoto
  • Un valore null viene letto come null da Datastore
  • Quando si legge da Datastore, un elenco vuoto viene restituito come raccolta vuota.