Una query di Datastore recupera le entità da Cloud Datastore che soddisfano un insieme specificato di condizioni.
Una query tipica include quanto segue:
- Un tipo di entità a cui si applica la query
- Filtri facoltativi in base a valori, chiavi e predecessori delle proprietà delle entità
- Ordini facoltativi per mettere in sequenza i risultati
Questa pagina descrive la struttura e i tipi di query utilizzati in App Engine per recuperare i dati da Cloud Datastore.
Filtri
I filtri di una query impostano vincoli per le proprietà, le chiavi e i predecessori delle entità da recuperare.
Filtri proprietà
Un filtro proprietà specifica
- Il nome di una proprietà
- Un operatore di confronto
- Un valore proprietà
Il valore della proprietà deve essere fornito dall'applicazione; non può fare riferimento ad altre proprietà né può essere calcolato. Un'entità soddisfa il filtro se ha una proprietà del nome specificato il cui valore viene confrontato con quello specificato nel filtro nel modo descritto dall'operatore di confronto.
L'operatore di confronto può essere uno dei seguenti (definiti come costanti enumerate nella classe nidificata
Query.FilterOperator
):
Operatore | Significato |
---|---|
EQUAL |
Uguale a |
LESS_THAN |
Minore di |
LESS_THAN_OR_EQUAL |
Minore o uguale a |
GREATER_THAN |
Maggiore di |
GREATER_THAN_OR_EQUAL |
Maggiore o uguale a |
NOT_EQUAL |
Diverso da |
IN |
Membro di (uguale a uno qualsiasi dei valori in un elenco specificato) |
L'operatore
NOT_EQUAL
in realtà esegue due query: una in cui tutti gli altri filtri sono
invariati e il
NOT_EQUAL
filtro viene sostituito con un
LESS_THAN
filtro e l'altro in cui viene sostituito con un
GREATER_THAN
filtro. I risultati vengono poi uniti, in ordine. Una query non può avere più di un
NOT_EQUAL
filtro, mentre una query che ne contiene uno non può avere altri filtri di disuguaglianza.
L'operatore IN
esegue inoltre più
query: una per ogni elemento nell'elenco specificato, con tutti gli altri filtri
invariati e il filtro IN
sostituito con un
EQUAL
filtro. I risultati vengono uniti in ordine di elementi nell'elenco. Se una query ha più di un filtro IN
, viene eseguita come più query, una per ogni possibile combinazione di valori negli elenchi IN
.
Una singola query contenente
NOT_EQUAL
o operatori IN
è limitata a un massimo di 30 sottoquery.
Per saperne di più su come le query NOT_EQUAL
e IN
si traducono in più query in un framework JDO/JPA, consulta l'articolo
Query con filtri != e IN.
Filtri principali
Per filtrare in base al valore della chiave di un'entità, utilizza la proprietà speciale Entity.KEY_RESERVED_PROPERTY
:
Sono supportati anche gli ordinamenti crescenti in Entity.KEY_RESERVED_PROPERTY
.
Quando si confronta la disuguaglianza, le chiavi vengono ordinate in base ai seguenti criteri:
- Percorso predecessore
- Tipo di entità
- Identificatore (nome chiave o ID numerico)
Gli elementi del percorso predecessore vengono confrontati in modo simile: per tipo (stringa), poi per nome chiave o ID numerico. I tipi e i nomi delle chiavi sono stringhe e sono ordinati per valore byte; gli ID numerici sono numeri interi in ordine numerico. Se le entità con lo stesso tipo e l'elemento principale utilizzano una combinazione di stringhe di nomi chiave e ID numerici, quelle con ID numerici le antepongono ai nomi delle chiavi.
Le query sulle chiavi utilizzano gli indici proprio come le query sulle proprietà e, negli stessi casi, richiedono indici personalizzati, con un paio di eccezioni: i filtri di disuguaglianza o un ordinamento crescente nella chiave non richiedono un indice personalizzato, ma è necessario un ordinamento decrescente nella chiave. Come per tutte le query, il server web di sviluppo crea voci appropriate nel file di configurazione indice quando viene testata una query che richiede un indice personalizzato.
Filtri predecessori
Puoi filtrare le query Datastore in base a un ancestor specificato, in modo che i risultati restituiti includano solo le entità discendenti da quel predecessore:
Tipi di query speciali
Alcuni tipi specifici di query meritano una menzione speciale:
Query senza carattere
Una query senza tipo e senza filtro predecesso recupera tutte le entità di un'applicazione da Datastore. Sono incluse le entità create e gestite da altre funzionalità di App Engine, ad esempio entità statistiche ed entità di metadati Blobstore (se presenti). Queste query gentili non possono includere filtri o ordinare ordini in base ai valori delle proprietà. Tuttavia, possono filtrare in base alle chiavi di entità specificando Entity.KEY_RESERVED_PROPERTY
come nome della proprietà:
Query sui predecessori
Una query con un filtro predecessore limita i risultati all'entità specificata e ai relativi discendenti:
Query sui predecessori Kindless
Una query senza tipo che include un filtro dei predecessori recupererà il predecessore specificato e tutti i suoi discendenti, indipendentemente dal tipo. Questo tipo di query non richiede indici personalizzati. Come tutte le query senza tipo, non può includere filtri o ordinare ordini in base ai valori delle proprietà, ma può filtrare in base alla chiave dell'entità:
L'esempio seguente illustra come recuperare tutte le entità discendenti da un determinato predecessore:
Query basate solo su chiavi
Una query solo con chiavi restituisce solo le chiavi delle entità risultati anziché le entità stesse, con una latenza e un costo inferiori rispetto al recupero di intere entità:
Spesso è più economico eseguire prima una query basata solo su chiavi e poi recuperare un sottoinsieme di entità dai risultati, anziché eseguire una query generale che potrebbe recuperare più entità di quelle di cui hai effettivamente bisogno.
Query di proiezione
A volte, tutto ciò di cui hai bisogno dai risultati di una query sono i valori di alcune proprietà specifiche. In questi casi, puoi utilizzare una query di proiezione per recuperare solo le proprietà che ti interessano, con una latenza e un costo inferiori rispetto al recupero dell'intera entità. Per i dettagli, consulta la pagina Query di proiezione.
Ordinare gli ordini
Un ordinamento delle query specifica
- Il nome di una proprietà
- Una direzione di ordinamento (ordine crescente o decrescente)
Ad esempio:
Se una query include più ordini, questi vengono applicati nella sequenza specificata. L'esempio seguente ordina prima in base al cognome crescente e poi in base all'altezza decrescente:
Se non vengono specificati ordini di ordinamento, i risultati vengono restituiti nell'ordine in cui sono stati recuperati da Datastore.
Nota: a causa del modo in cui Datastore esegue le query, se una query specifica filtri di disuguaglianza su una proprietà e ordina ordini su altre proprietà, la proprietà utilizzata nei filtri di disuguaglianza deve essere ordinata prima delle altre.
Indici
Ogni query di Datastore calcola i risultati utilizzando uno o più indici,che contengono chiavi di entità in una sequenza specificata dalle proprietà dell'indice e, facoltativamente, dai predecessori dell'entità. Gli indici vengono aggiornati in modo incrementale per riflettere eventuali modifiche apportate dall'applicazione alle sue entità, in modo che siano disponibili i risultati corretti di tutte le query senza bisogno di ulteriori calcoli.
App Engine predefinisce un indice semplice su ciascuna proprietà di un'entità.
Un'applicazione App Engine può definire ulteriori indici personalizzati in un file di configurazione degli indici denominato datastore-indexes.xml
, che viene generato nella directory /war/WEB-INF/appengine-generated
dell'applicazione. Il server di sviluppo aggiunge automaticamente suggerimenti a questo file quando rileva query che non possono essere eseguite con gli indici esistenti.
Puoi ottimizzare gli indici manualmente modificando il file prima di caricare l'applicazione.
Esempio di interfaccia di query
L'API Java Datastore di basso livello fornisce la classe Query
per la creazione di query e l'interfaccia PreparedQuery
per recuperare le entità da Datastore:
Osserva l'uso di FilterPredicate
e CompositeFilter
per creare i filtri. Se imposti un solo filtro per query, puoi utilizzare FilterPredicate
da solo:
Tuttavia, se vuoi impostare più di un filtro per una query, devi utilizzare CompositeFilter
, che richiede almeno due filtri. L'esempio riportato sopra utilizza l'helper delle scorciatoie CompositeFilterOperator.and
; l'esempio seguente mostra un modo per creare un filtro OR composito:
Che cosa succede dopo?
- Scopri come specificare cosa viene restituito da una query e controllare ulteriormente i risultati delle query.
- Scopri le limitazioni comuni per le query su Cloud Datastore.
- Scopri di più sui cursori di query, che consentono a un'applicazione di recuperare i risultati di una query in pratici batch.
- Comprendi la coerenza dei dati e come funziona la coerenza dei dati con diversi tipi di query su Cloud Datastore.