Datastore fornisce accesso programmatico ad alcuni metadati per supportare la metaprogrammazione, l'implementazione di funzioni amministrative di backend, la semplificazione della memorizzazione nella cache coerente e scopi simili. Puoi utilizzarlo, ad esempio, per creare un visualizzatore Datastore personalizzato per la tua applicazione. I metadati disponibili includono informazioni su gruppi di entità, spazi dei nomi, tipi di entità e proprietà utilizzati dall'applicazione, nonché le rappresentazioni delle proprietà per ogni proprietà.
La dashboard Datastore nella console Google Cloud fornisce alcuni metadati sull'applicazione, ma i dati visualizzati differiscono per alcuni aspetti importanti da quelli restituiti da queste funzioni.
- Aggiornamento. La lettura dei metadati tramite l'API ottiene i dati attuali, mentre i dati nella dashboard vengono aggiornati solo una volta al giorno.
- Sommario. Alcuni metadati nella dashboard non sono disponibili tramite le API; è vero anche il contrario.
- Velocità. I recuperi e le query dei metadati vengono fatturati nello stesso modo Datastore e delle operazioni di BigQuery. Query dei metadati che recuperano informazioni su spazi dei nomi, tipi e proprietà sono generalmente lente da eseguire. Come regola generale, una query sui metadati che restituisce N entità richiede all'incirca lo stesso tempo di N query ordinarie, ciascuna che restituisce una singola entità. Inoltre, le query di rappresentazione delle proprietà (query di proprietà non basate solo su chiavi) sono più lente rispetto alle query di proprietà che utilizzano solo chiavi. Il recupero dei metadati dei gruppi di entità è un po' più rapido rispetto al recupero di un'entità normale.
Metadati dei gruppi di entità
Cloud Datastore fornisce l'accesso alla "versione" di un gruppo di entità, un numero rigorosamente positivo che è garantito in aumento a ogni modifica al gruppo di entità.
Le versioni dei gruppi di entità sono ottenute chiamando get()
su una pseudo-entità speciale
che contiene una proprietà __version__
strettamente positiva. La chiave della pseudo-entità può essere creata utilizzando il metodo Entities.createEntityGroupKey()
:
Comportamento precedente
Nel comportamento della versione precedente del gruppo di entità, la versione del gruppo di entità aumenta solo in caso di modifiche al gruppo di entità. Il comportamento dei metadati del gruppo di entità legacy può essere utilizzato, ad esempio, per mantenere una cache coerente di una query da predecessore complessa su un gruppo di entità.
In questo esempio vengono memorizzati nella cache i risultati delle query (un conteggio dei risultati corrispondenti) e utilizza il comportamento legacy delle versioni dei gruppi di entità per utilizzare il valore memorizzato nella cache se corrente:
Le entità __entity_group__
potrebbero non esistere per gruppi di entità in cui
non sono mai stati scritti.
Query dei metadati
La classe Java Entities
, definita nel pacchetto com.google.appengine.api.datastore
, fornisce tre tipi di entità speciali riservati alle query sui metadati. Sono indicate da costanti statiche della classe Entities
:
Costante statica | Tipo di entità |
---|---|
Entities.NAMESPACE_METADATA_KIND |
__namespace__ |
Entities.KIND_METADATA_KIND |
__kind__ |
Entities.PROPERTY_METADATA_KIND |
__property__ |
Questi tipi non saranno in conflitto con altri con gli stessi nomi già esistenti nell'applicazione. Eseguendo una query su questi tipi speciali, puoi recuperare le entità contenenti i metadati desiderati.
Le entità restituite dalle query sui metadati vengono generate in modo dinamico, in base allo stato attuale di Datastore. Sebbene sia possibile creare oggetti Entity
locali di tipo __namespace__
, __kind__
o __property__
, qualsiasi tentativo di archiviarli in Datastore non riuscirà con un IllegalArgumentException
.
Il modo più semplice per eseguire query sui metadati è utilizzare l'API Datastore di basso livello. Nell'esempio seguente vengono visualizzati i nomi di tutti gli spazi dei nomi di un'applicazione:
Query dello spazio dei nomi
Se la tua applicazione utilizza l'API Namespaces, puoi utilizzare una query dello spazio dei nomi per trovare tutti gli spazi dei nomi utilizzati nelle entità dell'applicazione. Ciò consente di eseguire attività come funzioni amministrative in più spazi dei nomi.
Le query dello spazio dei nomi restituiscono entità del tipo speciale __namespace__
il cui nome chiave è il nome di uno spazio dei nomi. (Fa eccezione lo spazio dei nomi predefinito indicato dalla stringa vuota ""
: poiché la stringa vuota non è un nome chiave valido, questo spazio dei nomi è invece inserito con l'ID numerico 1
.) Le query di questo tipo supportano il filtro solo per gli intervalli nella pseudoproprietà speciale __key__
, il cui valore è la chiave dell'entità. I risultati possono essere ordinati in base al valore __key__
crescente (ma non decrescente). Poiché le entità __namespace__
non hanno proprietà, sia le query solo chiavi che quelle non solo chiavi restituiscono le stesse informazioni.
L'esempio seguente restituisce un elenco degli spazi dei nomi di un'applicazione nell'intervallo tra due nomi specificati, start
e end
:
Query gentili
Le query tipo restituiscono entità di tipo __kind__
il cui nome chiave è il nome di un tipo di entità. Le query di questo tipo sono implicitamente limitate allo spazio dei nomi attuale e supportano l'applicazione di filtri solo per gli intervalli sopra la pseudoproprietà __key__
. I risultati possono essere ordinati in base al valore __key__
crescente (ma non decrescente). Poiché le entità __kind__
non hanno proprietà, le query solo chiavi
e non solo chiavi restituiscono le stesse informazioni.
Nell'esempio seguente vengono stampati tutti i tipi i cui nomi iniziano con una lettera minuscola:
Query sulla proprietà
Le query sulla proprietà restituiscono entità di tipo __property__
che indicano le
proprietà associate a un tipo di entità. L'entità che rappresenta la proprietà P di tipo K si crea come segue:
- La chiave dell'entità è di tipo
__property__
e nome della chiave P. - La chiave dell'entità padre ha il tipo
__kind__
e il nome della chiave K.
Il comportamento di una query sulla proprietà dipende dal tipo di query, che può essere keys-only o non solo chiavi (rappresentazione di proprietà), come descritto nelle sottosezioni riportate di seguito.
Query sulle proprietà: solo chiavi
Le query di proprietà solo per chiavi restituiscono una chiave per ogni proprietà indicizzata di un tipo di entità specificato. Le proprietà non indicizzate non sono incluse. L'esempio seguente mostra i nomi di tutti i tipi di entità di un'applicazione e le proprietà associate:
Le query di questo tipo sono implicitamente limitate allo spazio dei nomi corrente e supportano il filtro solo per gli intervalli nella pseudoproprietà __key__
, dove le chiavi indicano le entità __kind__
o __property__
. I risultati possono essere ordinati in base al valore __key__
crescente (ma non decrescente). Il filtro viene applicato alle coppie tipo-proprietà, ordinate prima per tipo e la seconda per proprietà: ad esempio, supponiamo che tu abbia un'entità con le seguenti proprietà:
- tipo
Account
con proprietàbalance
company
- tipo
Employee
con proprietàname
ssn
- tipo
Invoice
con proprietàdate
amount
- tipo
Manager
con proprietàname
title
- tipo
Product
con proprietàdescription
price
La query per restituire i dati della proprietà avrebbe il seguente aspetto:
La query precedente restituirà quanto segue:
Employee: ssn
Invoice: date
Invoice: amount
Manager: name
Tieni presente che i risultati non includono la proprietà name
di tipo Employee
e la proprietà title
di tipo Manager
, né proprietà di tipo Account
e Product
, perché non rientrano nell'intervallo specificato per la query.
Le query sulle proprietà supportano anche i filtri dei predecessori su una chiave __kind__
o __property__
, per limitare i risultati a un singolo tipo o proprietà. Puoi utilizzarlo, ad esempio, per ottenere le proprietà associate a un determinato tipo di entità, come nell'esempio seguente:
Query delle proprietà: solo chiavi (rappresentazione delle proprietà)
Le query di proprietà non basate solo su chiavi, note come query di rappresentazione della proprietà,
restituiscono informazioni aggiuntive sulle rappresentazioni utilizzate da ogni coppia
di proprietà-tipo. Le proprietà non indicizzate non sono incluse. L'entità restituita per la proprietà P di tipo K ha la stessa chiave di una query solo per le chiavi corrispondente, insieme a un'ulteriore proprietà property_representation
che restituisce le rappresentazioni della proprietà. Il valore di questa proprietà è un'istanza di classe
java.util.Collection<String>
contenente una stringa per ogni rappresentazione della
proprietà P trovata in qualsiasi entità di tipo K.
Tieni presente che le rappresentazioni non corrispondono alle classi di proprietà;
più classi di proprietà possono essere mappate alla stessa rappresentazione. Ad esempio, java.lang.String
e com.google.appengine.api.datastore.PhoneNumber
utilizzano entrambi la rappresentazione STRING
.
La tabella seguente mappa le classi di proprietà alle relative rappresentazioni:
Classe proprietà | Rappresentazione |
---|---|
java.lang.Byte |
INT64 |
java.lang.Short |
INT64 |
java.lang.Integer |
INT64 |
java.lang.Long |
INT64 |
java.lang.Float |
DOUBLE |
java.lang.Double |
DOUBLE |
java.lang.Boolean |
BOOLEAN |
java.lang.String |
STRING |
com.google.appengine.api.datastore.ShortBlob |
STRING |
java.util.Date |
INT64 |
com.google.appengine.api.datastore.GeoPt |
POINT |
com.google.appengine.api.datastore.PostalAddress |
STRING |
com.google.appengine.api.datastore.PhoneNumber |
STRING |
com.google.appengine.api.datastore.Email |
STRING |
com.google.appengine.api.users.User |
USER |
com.google.appengine.api.datastore.IMHandle |
STRING |
com.google.appengine.api.datastore.Link |
STRING |
com.google.appengine.api.datastore.Category |
STRING |
com.google.appengine.api.datastore.Rating |
INT64 |
com.google.appengine.api.datastore.Key |
REFERENCE |
com.google.appengine.api.blobstore.BlobKey |
STRING |
java.util.Collection<T> |
Rappresentazione di T |
L'esempio seguente trova tutte le rappresentazioni di una proprietà specificata per un determinato tipo di entità: