Entità, proprietà e chiavi

Gli oggetti di dati in Datastore sono noti come entità. Un'entità ha una o più proprietà denominate, ognuna delle quali può avere uno o più valori. Le entità dello stesso tipo non devono avere le stesse proprietà e i valori di un'entità per una determinata proprietà non devono necessariamente essere dello stesso tipo di dati. Se necessario, un'applicazione può stabilire e applicare queste limitazioni nel proprio modello di dati.

Datastore supporta diversi tipi di dati per i valori delle proprietà. tra cui, a titolo esemplificativo:

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

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

Ogni entità in Datastore ha una chiave che la identifica in modo univoco. La chiave è costituita dai seguenti componenti:

  • Lo spazio dei nomi dell'entità, che consente la multitenancy
  • Il kind dell'entità, che la classifica per le query Datastore
  • Un identificatore per la singola entità, che può essere:
    • una stringa del nome della chiave
    • un ID numerico intero
  • Un percorso predecessore facoltativo che individua l'entità all'interno della gerarchia di Datastore

Un'applicazione può recuperare una singola entità da Datastore utilizzando la relativa chiave oppure può recuperare una o più entità emettendo una query in base alle chiavi o ai valori delle proprietà delle entità.

L'SDK Java App Engine include un'API semplice, fornita nel pacchetto com.google.appengine.api.datastore, che supporta direttamente le funzionalità di Datastore. Tutti gli esempi in questo documento si basano su questa API di basso livello; puoi scegliere di utilizzarla direttamente nella tua applicazione o come base su cui creare il tuo livello di gestione dei dati.

Datastore stesso non applica alcuna restrizione sulla struttura delle entità, ad esempio sul fatto che una determinata proprietà abbia un valore di un determinato tipo. questa attività viene lasciata all'applicazione.

Tipi e identificatori

Ogni entità di Datastore è di un determinato tipo, che la classifica ai fini delle query: ad esempio, un'applicazione per le risorse umane potrebbe rappresentare ogni dipendente di un'azienda con un'entità di tipo Employee. Nell'API Datastore Java, specifichi il tipo di un'entità quando la crei, come argomento del costruttore Entity(). Tutti i nomi dei tipi che iniziano con due trattini bassi (__) sono riservati e non possono essere utilizzati.

L'esempio seguente crea un'entità di tipo Employee, compila i valori delle proprietà e la salva in Datastore:

Entity employee = new Entity("Employee", "asalieri");
employee.setProperty("firstName", "Antonio");
employee.setProperty("lastName", "Salieri");
employee.setProperty("hireDate", new Date());
employee.setProperty("attendedHrTraining", true);

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
datastore.put(employee);

Oltre a un tipo, ogni entità ha un identificatore, assegnato al momento della creazione. Poiché fa parte della chiave dell'entità, l'identificatore è associato in modo permanente all'entità e non può essere modificato. Può essere assegnato in due modi:

  • L'applicazione può specificare la propria stringa nome chiave per l'entità.
  • Puoi chiedere a Datastore di assegnare automaticamente all'entità un ID numerico intero.

Per assegnare a un'entità un nome chiave, fornisci il nome come secondo argomento al costruttore quando crei l'entità:

Entity employee = new Entity("Employee", "asalieri");

Per fare in modo che Datastore assegni automaticamente un ID numerico, ometti questo argomento:

Entity employee = new Entity("Employee");

Assegnazione degli identificatori

Datastore può essere configurato per generare ID automatici utilizzando due diversi criteri di ID automatico:

  • Il criterio default genera una sequenza casuale di ID inutilizzati distribuiti approssimativamente in modo uniforme. Ogni ID può contenere fino a 16 cifre decimali.
  • Il criterio legacy crea una sequenza di ID interi più piccoli non consecutivi.

Se vuoi mostrare all'utente gli ID entità e/o dipendere dal loro ordine, ti consigliamo di utilizzare l'allocazione manuale.

Datastore genera una sequenza casuale di ID inutilizzati distribuiti in modo approssimativamente uniforme. Ogni ID può essere composto da un massimo di 16 cifre decimali.

Percorsi predecessori

Le entità in Cloud Datastore formano uno spazio strutturato gerarchicamente simile la struttura di directory di un file system. Quando crei un'entità, puoi optionally designare un'altra entità come principale; la nuova entità è secondaria dell'entità principale (tieni presente che, a differenza di un file system, l'entità principale non deve necessariamente esistere). Un'entità senza un elemento principale è un'entità radice. L'associazione tra un'entità e la relativa entità è permanente e non può essere modificato dopo la creazione dell'entità. Cloud Datastore non assegnerà mai lo stesso ID numerico a due entità con lo stesso elemento principale o a due entità principali (quelle senza un elemento principale).

L'entità principale, l'entità principale dell'entità principale e così via in modo ricorsivo sono i suoi antenati; le sue entità figlio, le entità figlio delle entità figlio e così via sono i suoi discendenti. Un'entità principale e tutti i suoi discendenti appartengono allo stesso gruppo di entità. La sequenza di entità che inizia con un'entità principale e procede da una entità principale a una secondaria, fino a una determinata entità, costituisce il percorso degli antenati di quell'entità. La chiave completa che identifica l'entità è composta da una sequenza di coppie tipo-identificatore che specifica predecessore e termina con quelli dell'entità stessa:

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

Per un'entità principale, il percorso dell'antenato è vuoto e la chiave è costituita unicamente dal tipo e dall'identificatore dell'entità:

[Person:GreatGrandpa]

Questo concetto è illustrato dal seguente diagramma:

Mostra la relazione tra entità base e quella secondaria entità nel gruppo di entità

Per designare l'elemento principale di un'entità, fornisci la chiave dell'entità padre come argomento alle Entity() durante la creazione dell'entità figlio. Puoi ottenere la chiave chiamando il metodo getKey() dell'entità principale:

Entity employee = new Entity("Employee");
datastore.put(employee);

Entity address = new Entity("Address", employee.getKey());
datastore.put(address);

Se la nuova entità ha anche un nome della chiave, fornisci il nome della chiave come secondo argomento per il costruttore Entity() e la chiave dell'entità padre come terzo argomento:

Entity address = new Entity("Address", "addr1", employee.getKey());

Transazioni e gruppi di entità

Ogni tentativo di creare, aggiornare o eliminare un'entità avviene nel contesto di una transazione. Una singola transazione può includere un numero illimitato di operazioni di questo tipo. Per mantenere dei dati, la transazione garantisce che tutte le operazioni vengono applicati a Datastore come unità oppure, se uno dei delle operazioni non riesce, nessuna di queste viene applicata. Inoltre, tutte le letture fortemente coerenti (query o get di antenati) eseguite all'interno della stessa transazione osservano un'istantanea coerente dei dati.

Come accennato sopra, un gruppo di entità è un insieme di entità collegate tramite l'ascendenza a un elemento principale comune. L'organizzazione dei dati in gruppi di entità può limitare le transazioni che possono essere eseguite:

  • Tutti i dati a cui accede una transazione devono essere contenuti in massimo 25 gruppi di entità.
  • Se vuoi utilizzare le query all'interno di una transazione, i dati devono essere organizzati in gruppi di entità in modo da poter specificare filtri di antenato che corrispondano ai dati corretti.
  • Esiste un limite di velocità effettiva di scrittura di circa una transazione al secondo all'interno di un singolo gruppo di entità. Questa limitazione esiste perché Datastore esegue la replica sincrona masterless di ciascun gruppo di entità su un'ampia area geografica per fornire affidabilità e tolleranza di errore elevate.

In molte applicazioni, è accettabile utilizzare la coerenza eventuale (ovvero una query non principale che abbraccia più gruppi di entità, che a volte può restituire dati leggermente obsoleti) per ottenere una visione ampia di dati non correlati e poi utilizzare la coerenza forte (una query principale o un get di una singola entità) per visualizzare o modificare un singolo insieme di dati altamente correlati. In queste applicazioni, in genere è consigliabile utilizzare un gruppo di entità distinto per ogni insieme di dati altamente correlati. Per ulteriori informazioni, consulta la sezione Strutturare i dati per una coerenza elevata.

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ù tipi 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 con 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 restituiscono IllegalArgumentException
Stringa di testo (lunga) com.google.appengine.api.datastore.Text Nessuno Fino a 1 megabyte

Non indicizzato
Stringa byte (breve) com.google.appengine.api.datastore.ShortBlob Ordine 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 indicizzato
Data e ora java.util.Date Cronologica
Punto geografico com.google.appengine.api.datastore.GeoPt Per latitudine,
poi 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)		 In base agli elementi del percorso
(kind, identificatore,
kind, identificatore...)		 Fino a 1500 byte

I valori superiori a 1500 byte restituiscono IllegalArgumentException
Chiave archivio BLOB com.google.appengine.api.blobstore.BlobKey Ordine byte
Entità incorporata com.google.appengine.api.datastore.EmbeddedEntity Nessuno Non indicizzato
Null null Nessuno

Importante: consigliamo vivamente di evitare di archiviare users.User come valore della proprietà, poiché include l'indirizzo email e l'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 Uservalore 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 ordinamento.
  • Le stringhe lunghe (fino a 1 megabyte) non vengono indicizzate e non possono essere utilizzate nei filtri di query e negli ordinamenti.
Nota: il tipo di stringa a byte lunghi è 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 a virgola fissa
    • Numeri interi
    • Date e ore
    • Valutazioni
  3. Valori booleani
  4. Sequenze byte
    • Stringa byte
    • Stringa Unicode
    • Chiavi dell'archivio BLOB
  5. Numeri con virgola mobile
  6. Punti geografici
  7. Utenti con account Google
  8. Chiavi del datastore

Poiché stringhe di testo lunghe, stringhe di byte lunghi ed entità incorporate non sono indicizzate, non è stato definito un ordinamento.

Utilizzo delle entità

Le applicazioni possono utilizzare l'API Datastore per creare, recuperare, aggiornare ed eliminare entità. Se l'applicazione conosce la chiave completa di un'entità (o può deriverla dalla chiave, dal tipo e dall'identificatore principali), può utilizzarla per operare direttamente sull'entità. Un'applicazione può inoltre ottenere la chiave di un'entità come risultato di una query Datastore; consulta la pagina Query Datastore per ulteriori informazioni.

L'API Datastore Java utilizza i metodi dell'interfaccia DatastoreService per operare sulle entità. Puoi ottenere un oggetto DatastoreService chiamando il metodo statico DatastoreServiceFactory.getDatastoreService():

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();

Creazione di un'entità

Puoi creare una nuova entità creando un'istanza della classe Entity, fornendo il tipo di entità come argomento al costruttore Entity().

Dopo aver compilato le proprietà dell'entità, se necessario, salvala nel datastore passandola come argomento al metodo DatastoreService.put(). Puoi specificare il nome della chiave dell'entità passandolo come secondo argomento al costruttore:

Entity employee = new Entity("Employee", "asalieri");
// Set the entity properties.
// ...
datastore.put(employee);

Se non fornisci un nome della chiave, Datastore genererà automaticamente un ID numerico per la chiave dell'entità:

Entity employee = new Entity("Employee");
// Set the entity properties.
// ...
datastore.put(employee);

Recupero di un'entità

Per recuperare un'entità identificata da una determinata chiave, passa Key al metodo DatastoreService.get():

// Key employeeKey = ...;
Entity employee = datastore.get(employeeKey);

Aggiornamento di un'entità

Per aggiornare un'entità esistente, modifica gli attributi dell'oggetto Entity, quindi passalo al metodo DatastoreService.put(). I dati dell'oggetto sovrascrivono l'entità esistente. L'intero oggetto viene inviato a Datastore con ogni chiamata a put().

Eliminazione di un'entità

Data la chiave di un'entità, puoi eliminare l'entità con il metodo DatastoreService.delete():

// Key employeeKey = ...;
datastore.delete(employeeKey);

Proprietà ripetute

Puoi archiviare 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à. Questo 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 fare questo:

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

Quando un'entità incorporata è inclusa negli indici, puoi eseguire query sulle proprietà secondarie. Se escludi un'entità incorporata dall'indicizzazione, tutte le proprietà secondarie vengono escluse dall'indicizzazione. Facoltativamente, puoi associare una chiave a un ma (a differenza di un'entità a tutti gli effetti) la chiave non è obbligatoria e, anche se esistente, non può essere utilizzato 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);

Operazioni batch

I metodi DatastoreService put(), get() e delete() (e le relative controparti di AsyncDatastoreService) hanno versioni batch che accettano un oggetto iterable (della classe Entity per put(), Key per get() e delete()) e lo utilizzano per operare su più entità in una singola chiamata a Datastore:

Entity employee1 = new Entity("Employee");
Entity employee2 = new Entity("Employee");
Entity employee3 = new Entity("Employee");
// ...

List<Entity> employees = Arrays.asList(employee1, employee2, employee3);
datastore.put(employees);

Queste operazioni batch raggruppano tutte le entità o le chiavi per gruppo di entità, quindi eseguono l'operazione richiesta su ciascun gruppo di entità in parallelo. Queste chiamate batch sono più veloci rispetto all'esecuzione di chiamate separate per ogni singola entità, perché comportano l'overhead per una sola chiamata di servizio. Se sono coinvolti più gruppi di entità, il lavoro per tutti i gruppi viene eseguito in parallelo sul lato server.

Generazione delle chiavi

Le applicazioni possono utilizzare la classe KeyFactory per creare un oggetto Key per un'entità da componenti noti, come il tipo e l'identificatore dell'entità. Per un'entità senza padre, passa il tipo e l'identificatore (una stringa del nome della chiave o un ID numerico) al metodo statico KeyFactory.createKey() per creare la chiave. Gli esempi seguenti creano una chiave per un'entità di tipo Person con nome chiave "GreatGrandpa" o ID numerico 74219:

Key k1 = KeyFactory.createKey("Person", "GreatGrandpa");
Key k2 = KeyFactory.createKey("Person", 74219);

Se la chiave include un componente del percorso, puoi utilizzare la classe helper KeyFactory.Builder per creare il percorso. Il metodo addChild di questa classe aggiunge una singola entità al percorso e restituisce il builder stesso, in modo da poter concatenare una serie di chiamate, a partire dall'entità principale, per creare il percorso un'entità alla volta. Dopo aver creato il percorso completo, chiama getKey per recuperare la chiave risultante:

Key k =
    new KeyFactory.Builder("Person", "GreatGrandpa")
        .addChild("Person", "Grandpa")
        .addChild("Person", "Dad")
        .addChild("Person", "Me")
        .getKey();

La classe KeyFactory include anche i metodi statici keyToString e stringToKey per la conversione tra le chiavi e le relative rappresentazioni di stringa:

String personKeyStr = KeyFactory.keyToString(k);

// Some time later (for example, after using personKeyStr in a link).
Key personKey = KeyFactory.stringToKey(personKeyStr);
Entity person = datastore.get(personKey);

La rappresentazione in formato stringa di una chiave è "sicura per il web": non contiene caratteri considerati speciali nel codice HTML o negli URL.

Utilizzo di un elenco vuoto

In passato, Datastore non aveva una rappresentazione per una proprietà che rappresentasse 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, brevemente descritto di seguito:

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

Tuttavia, se modifichi il comportamento predefinito, l'SDK per Java supporterà di elenchi vuoti. Ti consigliamo di considerare le implicazioni modificando il comportamento predefinito dell'applicazione e attivando 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 come elenco vuoto in Datastore
  • Un null viene letto come null da Datastore
  • Durante la lettura da Datastore, un elenco vuoto viene restituito come Raccolta vuota.