GQL è un linguaggio di tipo SQL per il recupero di entità e chiavi. La sintassi per le query GQL è in modo simile a SQL. Questa pagina è un riferimento per l'utilizzo di GQL con NDB e DB in Python librerie client.
GQL è mappato approssimativamente a SQL: puoi pensare a GQL kind
come a una tabella SQL, a GQL
entity
come riga SQL e GQL property
come colonna SQL. Tuttavia, un
La ricerca SQL per riga e colonna è un singolo valore, mentre in GQL un valore di proprietà può essere un elenco.
Versioni GQL
Sono necessarie versioni diverse di GQL a seconda di dove vengono eseguite le query. Esistono due tipi di regole GQL references:
-
Riferimento GQL per Python NDB/DB, per la grammatica GQL utilizzata nel client NDB e DB librerie (utilizza il riferimento in questa pagina).
- Riferimento GQL, per la grammatica GQL utilizzata nell'API Datastore attuale e Visualizzatore Datastore della console Google Cloud.
Sintassi
La sintassi di GQL per Python NDB/DB può essere riassunta come segue:
SELECT [DISTINCT] [* | <property list> | __key__] [FROM <kind>] [WHERE <condition> [AND <condition> ...]] [ORDER BY <property> [ASC | DESC] [, <property> [ASC | DESC] ...]] [LIMIT [<offset>,]<count>] [OFFSET <offset>] <property list> := <property> [, <property> ...] <condition> := <property> {< | <= | > | >= | = | != } <value> <condition> := <property> IN <list> <condition> := ANCESTOR IS <entity or key> <list> := (<value> [, <value> ...]])
Come nel caso di SQL, le parole chiave GQL non fanno distinzione tra maiuscole e minuscole. Nomi di tipo e proprietà sono sensibile alle maiuscole.
GQL supporta solo istruzioni SELECT
.
Una query GQL restituisce zero o più entità intere,
entità previste,
o
tasti
del tipo richiesto. Ogni query GQL inizia sempre con SELECT *
,
SELECT __key__
o SELECT <property list>, dove
property è un elenco delimitato da virgole di una o più proprietà entità
che deve essere restituito dalla query. (una query GQL non può eseguire un "join" di tipo SQL
query.)
Suggerimento: le query SELECT __key__ or SELECT
<property list>
sono più veloci e utilizzano meno CPU
non superiore a SELECT *
query.
La clausola facoltativa DISTINCT
(sperimentale)
specifica che in un insieme di risultati verranno restituiti solo risultati completamente univoci. In questo modo
restituisce solo il primo risultato per entità che hanno gli stessi valori per le proprietà.
che vengono previste.
La clausola facoltativa FROM
limita l'insieme di risultati a queste entità
del tipo dato. Una query senza una clausola FROM
è chiamata
senza tipo di query e può avere solo un WHERE
che specifica un __key__
proprietà.
La clausola WHERE
facoltativa limita l'insieme di risultati a questi
che soddisfano una o più condizioni. Ogni condizione confronta una proprietà
dell'entità con un valore utilizzando un operatore di confronto. Se sono presenti più condizioni
vengono specificate con la parola chiave AND
, un'entità deve soddisfare tutte le
condizioni che la query deve restituire. GQL non ha un OR
operatore. Tuttavia, ha un operatore IN
, che fornisce un
forma limitata di OR
.
L'operatore IN
confronta il valore di una proprietà con ogni elemento in un
dall'elenco di lettura. L'operatore IN
equivale a molte query =
,
uno per ogni valore, contemporaneamente OR insieme. Un'entità il cui valore per
uguale a qualsiasi valore nell'elenco che può essere restituito per la query.
Nota: gli operatori IN
e !=
usare più query dietro le quinte. Ad esempio, IN
esegue una query separata sul datastore sottostante per ogni elemento
dall'elenco di lettura. Le entità restituite sono il risultato del cross-product di tutte le entità
al datastore sottostante e sono deduplicati. Un massimo di 30 datastore
consentite per ogni singola query GQL.
Una condizione può anche verificare se un'entità ha una determinata entità come
predecessore, usando l'operatore ANCESTOR IS
. Il valore è un modello
o l'istanza di Compute Engine
chiave
per l'entità predecessore. Per ulteriori informazioni sui predecessori, vedi
Chiavi e gruppi di entità.
Il lato sinistro di un confronto è sempre il nome di una proprietà. Un tipico
il nome della proprietà è composto da caratteri alfanumerici combinati facoltativamente con
trattini bassi e punti. In altre parole, corrispondono all'espressione regolare
[a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*
.
Attenzione:nomi delle proprietà
contenenti altri caratteri stampabili devono essere racchiusi tra virgolette doppie. Per
esempio: "first-name"
. Spazi o caratteri non stampabili
i nomi delle proprietà non sono supportati.
Il lato destro di un confronto può essere uno dei seguenti (ad esempio appropriati per il tipo di dati della proprietà):
- un valore letterale
str
, come stringa tra virgolette. Virgoletta singola caratteri di questa stringa devono essere preceduti dal carattere di escape''
. Ad esempio:'Joe''s Diner'
- un numero intero o con rappresentazione in virgola mobile. Ad esempio:
42.7
- un valore letterale booleano, come
TRUE
oFALSE
. - il valore letterale
NULL
, che rappresenta il valore nullo (None
in Python). - un valore letterale data/ora, data o ora, con valori numerici o una stringa
di Google, nei seguenti formati:
DATETIME(year, month, day, hour, minute, second)
DATETIME('YYYY-MM-DD HH:MM:SS')
DATE(year, month, day)
DATE('YYYY-MM-DD')
TIME(hour, minute, second)
TIME('HH:MM:SS')
- un valore letterale di chiave di entità, con un
chiave con codifica stringa
o un
percorso completo di tipi e chiave
nomi/ID:
KEY('encoded key')
KEY('kind', 'name'/ID [, 'kind', 'name'/ID...])
- un valore letterale oggetto utente, con l'indirizzo email dell'utente:
USER('email-address')
- un valore letterale GeoPt con latitudine e longitudine come in virgola mobile
valori:
GEOPT(lat, long)
- un valore parametro associato. Nella stringa di query, i parametri posizionali vengono
a cui si fa riferimento in base al numero:
title = :1
. I parametri delle parole chiave sono a cui si fa riferimento con il nome:title = :mytitle
Nota: condizioni del modulo property = NULL
verifica se un valore nullo è archiviato esplicitamente nel datastore per quella proprietà.
Non è la stessa cosa che controllare se nell'entità manca un valore per la proprietà.
Le query Datastore che fanno riferimento a una proprietà non restituiscono mai entità che non hanno
per quella proprietà.
I parametri associati possono essere associati come argomenti posizionali o argomenti parola chiave passati a del costruttore GqlQuery o lo script di una classe di modello gql() . Tipi di dati della proprietà che non hanno una sintassi di valore letterale corrispondente deve essere specificato utilizzando l'associazione di parametri, incluso il tipo di dati dell'elenco. Le associazioni di parametri possono essere ricollegate con nuovi valori durante la durata del parametro GqlQuery (ad esempio per riutilizzare una query in modo efficiente) utilizzando bind() .
La clausola facoltativa ORDER BY
indica che i risultati devono essere
restituiti e ordinati in base alle proprietà specificate, in ordine crescente (ASC
)
in ordine decrescente (DESC
). La clausola ORDER BY
può
specificare più ordinamenti come elenco delimitato da virgole, valutato da sinistra a
a destra. Se la direzione non è specificata, il valore predefinito è ASC
. Se
non viene specificata nessuna clausola ORDER BY
, l'ordine dei risultati è
indefinito e potrebbe cambiare nel tempo.
Una clausola LIMIT
facoltativa impedisce la restituzione della query
dopo le prime <count>
entità. La
La clausola LIMIT
può anche includere un elemento <offset>
, per
ignora quel numero di risultati per trovare il primo da restituire. Un'intestazione facoltativa
La clausola OFFSET
può specificare un <offset>
, se non è presente
È presente la clausola LIMIT
.
Nota: come il parametro offset
per il parametro
fetch()
, un OFFSET
in una stringa di query GQL non riduce il numero
di entità recuperate dal datastore. Influisce solo sui risultati che vengono
restituiti dal metodo fetch(). Una query con un offset ha prestazioni
caratteristiche che corrispondono linearmente alla dimensione dell'offset più il limite
dimensioni.
Per informazioni sull'esecuzione di query GQL, sull'associazione dei parametri e sull'accesso vedi i risultati GqlQuery e il Model.gql() .
Esempi
from google.appengine.ext import db class Person(db.Model): name = db.StringProperty() age = db.IntegerProperty() # We use a unique username for the Entity's key. amy = Person(key_name='amym', name='Amy', age=48) amy.put() Person(key_name='bettyd', name='Betty', age=42).put() Person(key_name='charliec', name='Charlie', age=32).put() Person(key_name='charliek', name='Charlie', age=29).put() Person(key_name='eedna', name='Edna', age=20).put() Person(key_name='fredm', name='Fred', age=16, parent=amy).put() Person(key_name='georgemichael', name='George').put()
Per trovare tutte le entità del tipo Person
le cui età sono
tra 18 e 35 (ovvero sia Charlies che Edna), utilizza questa query:
SELECT * FROM Person WHERE age >= 18 AND age <= 35
Per trovare le tre entità del tipo Person
le cui età sono
il più grande (ad es. Amy, Betty e Charlie), usa questa query:
SELECT * FROM Person ORDER BY age DESC LIMIT 3
Per trovare le entità del tipo Person
i cui nomi sono uno di
"Betty" o "Carlo", utilizza questa query:
SELECT * FROM Person WHERE name IN ('Betty', 'Charlie')
Per restituire solo i valori name
per ogni Person
, utilizza
questa query:
SELECT name FROM Person
Per restituire solo i valori name
per ogni Person
,
ordinato per age
, utilizza questa query:
SELECT name FROM Person ORDER BY age
Per trovare le chiavi delle entità di tipo Person
che hanno un
età None
(ad es. KEY('Person', 'georgemichael')
), usa questa
query:
SELECT __key__ FROM Person WHERE age = NULL
Per trovare tutte le entità, indipendentemente dal tipo, che si trovano nella gruppo di entità (ad es. Anna e Fred), utilizza questa query:
SELECT * WHERE __key__ HAS ANCESTOR KEY(Person, 'Amy')
Per trovare una corrispondenza in base alla chiave, possiamo utilizzare __key__
sul lato sinistro di una condizione.
Ad esempio, possiamo utilizzarlo per ottenere tutte le entità Person
che hanno
un nome utente che inizia con "a".
SELECT * FROM Person WHERE __key__ >= KEY('Person', 'a') AND __key__ < KEY('Person', 'b')
Nota: se crei una query con un'uguaglianza su
__key__
, valuta la possibilità di utilizzare get()
per recuperare
direttamente l'entità.