Riferimento alle proprietà delle entità

Questa API è supportata per runtime di prima generazione e può essere utilizzata quando eseguire l'upgrade ai runtime di seconda generazione corrispondenti. Se esegui l'aggiornamento al runtime App Engine Java 11/17, consulta la guida alla migrazione per scoprire di più sulle opzioni di migrazione per i servizi in bundle legacy.

Firestore in modalità Datastore (Datastore) supporta una serie di tipi di dati per i valori delle proprietà. Questi includono, tra gli altri:

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

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

Proprietà e tipi di valori

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.

Nota :le proprietà con più valori possono essere utili, ad esempio, quando si eseguono query con filtri di uguaglianza: un'entità soddisfa la query se uno qualsiasi dei suoi valori per una proprietà corrisponde al valore specificato nel filtro. Per ulteriori dettagli sulle proprietà con più valori, inclusi i problemi di cui devi essere a conoscenza, consulta la pagina Query Datastore.

Sono supportati i seguenti tipi di valori:

Tipo di valore	Tipo/i Java	Ordinamento	Note
Numero intero	short int long java.lang.Short java.lang.Integer java.lang.Long	Numerico	Memorizzato come numero intero lungo, poi convertito nel tipo di campo Valori fuori intervallo
Numero in virgola mobile	float double java.lang.Float java.lang.Double	Numerico	Doppia precisione 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 IllegalArgumentException
Stringa di testo (lunga)	com.google.appengine.api.datastore.Text	Nessuno	Fino a 1 megabyte Non indicizzato
Stringa di byte (breve)	com.google.appengine.api.datastore.ShortBlob	Ordine dei byte	Fino a 1500 byte I valori superiori a 1500 byte generano IllegalArgumentException
Stringa di byte (lunga)	com.google.appengine.api.datastore.Blob	Nessuno	Fino a 1 megabyte Non indicizzato
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 (tipo, identificatore, tipo, identificatore...)	Fino a 1500 byte I valori superiori a 1500 byte generano 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 della proprietà, perché include l'indirizzo email insieme all'ID univoco. Se un utente cambia il proprio indirizzo email e confronti il vecchio valore user.User memorizzato con il nuovo valore user.User, 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 ordinamenti.
• Le stringhe lunghe (fino a 1 megabyte) non vengono indicizzate e non possono essere utilizzate nei filtri delle query e negli ordinamenti.

Nota: il tipo di stringa di byte lunga è denominato Blob nell'API Datastore. Questo tipo non è correlato ai blob 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 in virgola fissa
   • Numeri interi
   • Date e ore
   • Valutazioni
3. Valori booleani
4. Sequenze di byte
   • Stringa di byte
   • Stringa Unicode
   • Chiavi Blobstore
5. Numeri in virgola mobile
6. Punti geografici
7. Utenti con account Google
8. Chiavi Datastore

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

Nota :i numeri interi e i numeri in virgola mobile sono considerati tipi separati in Datastore. Se un'entità utilizza un mix di numeri interi e numeri in virgola mobile per la stessa proprietà, tutti i numeri interi verranno ordinati prima di tutti i numeri in virgola mobile: ad esempio,

7 < 3.2

Proprietà ripetute

Puoi memorizzare più valori all'interno di una singola 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 di 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", "[e-mail]");

employee.setProperty("contactInfo", embeddedContactInfo);

Le proprietà di un'entità incorporata non vengono indicizzate e non possono essere utilizzate nelle query. Puoi, se vuoi, associare una chiave a un'entità incorporata, ma (a differenza di un'entità completa) 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

Storicamente, Datastore non aveva una rappresentazione per una proprietà che rappresentava un elenco vuoto. L'SDK Java ha risolto questo problema memorizzando le raccolte vuote come valori nulli, quindi non è possibile distinguere tra valori nulli 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 nullo viene letto come nullo da Datastore
• Una raccolta vuota viene letta come null.

Importante: una lettura, modifica e scrittura di un'entità con un elenco vuoto farà sì che l'elenco venga trasformato in un valore nullo.

Tuttavia, se modifichi il comportamento predefinito, l'SDK Java di Appengine Datastore supporterà l'archiviazione di elenchi vuoti. Ti consigliamo di valutare le implicazioni della modifica del comportamento predefinito della tua applicazione e poi di attivare il supporto per le liste vuote.

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

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

Se questa proprietà è impostata su true come mostrato sopra:

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

Importante: le tue query potrebbero essere interessate quando attivi il supporto per le liste vuote. I valori null vengono indicizzati in Datastore, ma gli elenchi vuoti no. Se memorizzavi elenchi vuoti come valori null e poi eseguivi query per trovare questi elenchi, il passaggio all'elenco vuoto farà sì che queste query non restituiscano risultati.