Riferimento GQL per NDB/DB di Python

GQL è un linguaggio simile a SQL per recuperare entità e chiavi. La sintassi delle query GQL è simile a quella di SQL. Questa pagina è un riferimento per l'utilizzo di GQL con le librerie client Python NDB e DB.

GQL corrisponde approssimativamente a SQL: puoi considerare un kind GQL come una tabella SQL, un entity GQL come una riga SQL e un property GQL come una colonna SQL. Tuttavia, una ricerca riga-colonna SQL è un singolo valore, mentre in GQL un valore di proprietà può essere un elenco.

Versioni di GQL

A seconda di dove esegui le query, hai bisogno di versioni diverse di GQL. Esistono due riferimenti GQL:

Sintassi

La sintassi 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 per SQL, le parole chiave GQL non fanno distinzione tra maiuscole e minuscole. I nomi di tipo e proprietà sono sensibili alle maiuscole.

GQL supporta solo le istruzioni SELECT.

Una query GQL restituisce zero o più entità intere, entità proiettate, o chiavi 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à dell'entità da restituire dalla query. Una query GQL non può eseguire una query "join" simile a SQL.

Suggerimento:le query SELECT __key__ or SELECT <property list> sono più veloci e utilizzano meno tempo CPU rispetto alle query SELECT *.

La clausola facoltativa DISTINCT(sperimentale) specifica che in un insieme di risultati verranno restituiti solo risultati completamente unici. Verrà restituito solo il primo risultato per le entità che hanno gli stessi valori per le proprietà che vengono proiettate.

La clausola facoltativa FROM limita il set di risultati alle entità del tipo specificato. Una query senza clausola FROM è chiamata query senza tipo e può avere solo una clausola WHERE che specifica una proprietà __key__.

La clausola facoltativa WHERE limita il set di risultati alle entità che soddisfano una o più condizioni. Ogni condizione confronta una proprietà dell'entità con un valore utilizzando un operatore di confronto. Se vengono fornite più condizioni con la parola chiave AND, un'entità deve soddisfare tutte le condizioni per essere restituita dalla query. GQL non ha un operatore OR. Tuttavia, ha un operatore IN, che fornisce una forma limitata di OR.

L'operatore IN confronta il valore di una proprietà con ogni elemento di un elenco. L'operatore IN equivale a molte query =, una per ogni valore, unite con l'operatore OR. Per la query può essere restituita un'entità il cui valore per la proprietà specificata è uguale a uno qualsiasi dei valori nell'elenco.

Nota:gli operatori IN e != utilizzano più query in background. Ad esempio, l'operatore IN esegue una query datastore sottostante separata per ogni elemento dell'elenco. Le entità restituite sono il risultato del prodotto incrociato di tutte le query del datastore sottostanti e vengono deduplicate. Per una singola query GQL sono consentite al massimo 30 query datastore.

Una condizione può anche verificare se un'entità ha una determinata entità come antenato, utilizzando l'operatore ANCESTOR IS. Il valore è un'istanza del modello o una chiave per l'entità antenata. Per saperne di più sugli antenati, vedi Chiavi e gruppi di entità.

Il lato sinistro di un confronto è sempre un nome di proprietà. Un nome di proprietà tipico è composto da caratteri alfanumerici, trattini bassi e punti. In altre parole, corrispondono all'espressione regolare [a-zA-Z0-9_]+(\.[a-zA-Z0-9_]+)*.

Attenzione: i nomi delle proprietà contenenti altri caratteri stampabili devono essere racchiusi tra virgolette doppie. Ad esempio: "first-name". Gli spazi o i caratteri non stampabili nei nomi delle proprietà non sono supportati.

Il lato destro di un confronto può essere uno dei seguenti (a seconda del tipo di dati della proprietà):

  • un valore letterale str, come stringa tra virgolette singole. I caratteri virgoletta singola nella stringa devono essere preceduti dal carattere di escape ''. Ad esempio: 'Joe''s Diner'
  • un valore letterale numerico intero o con rappresentazione in virgola mobile. Ad esempio: 42.7
  • un valore letterale booleano, come TRUE o FALSE.
  • il valore letterale NULL, che rappresenta il valore null (None in Python).
  • un valore letterale di data/ora, data o ora, con valori numerici o una rappresentazione di stringa, 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 della chiave dell'entità, con una chiave codificata come stringa o un percorso completo di tipi e nomi/ID delle chiavi:

    • KEY('encoded key')
    • KEY('kind', 'name'/ID [, 'kind', 'name'/ID...])
  • un letterale oggetto User, con l'indirizzo email dell'utente:
    USER('email-address')
  • un valore letterale GeoPt, con latitudine e longitudine come valori in virgola mobile:
    GEOPT(lat, long)
  • un valore parametro vincolato. Nella stringa di query, i parametri posizionali sono indicati con un numero: title = :1. I parametri delle parole chiave fanno riferimento al nome: title = :mytitle

Nota:le condizioni del modulo property = NULL controllano se un valore nullo è esplicitamente archiviato nel datastore per quella proprietà. Non è la stessa cosa che verificare se l'entità non ha alcun valore per la proprietà. Le query Datastore che fanno riferimento a una proprietà non restituiscono mai entità che non hanno un valore per quella proprietà.

I parametri associati possono essere associati come argomenti posizionali o argomenti di parole chiave passati a il costruttore GqlQuery o al metodo gql() di una classe modello. I tipi di dati delle proprietà che non hanno una sintassi letterale del valore corrispondente devono essere specificati utilizzando il binding dei parametri, incluso il tipo di dati elenco. I binding dei parametri possono essere riassegnati con nuovi valori durante la durata dell'istanza GqlQuery (ad esempio per riutilizzare in modo efficiente una query) utilizzando il metodo bind().

La clausola facoltativa ORDER BY indica che i risultati devono essere restituiti ordinati in base alle proprietà specificate, in ordine crescente (ASC) o decrescente (DESC). La clausola ORDER BY può specificare più ordini di ordinamento come elenco delimitato da virgole, valutati da sinistra a destra. Se la direzione non è specificata, il valore predefinito è ASC. Se non viene specificata alcuna clausola ORDER BY, l'ordine dei risultati è indefinito e potrebbe cambiare nel tempo.

Una clausola LIMIT facoltativa fa sì che la query smetta di restituire risultati dopo le prime <count> entità. La clausola LIMIT può includere anche un <offset>, per saltare quel numero di risultati e trovare il primo risultato da restituire. Una clausola OFFSET facoltativa può specificare un <offset> se non è presente alcuna clausola LIMIT.

Nota:come il parametro offset per il metodo fetch(), un OFFSET in una stringa di query GQL non riduce il numero di entità recuperate dal datastore. Influisce solo sui risultati restituiti dal metodo fetch(). Una query con un offset ha caratteristiche di rendimento che corrispondono linearmente alla dimensione dell'offset più la dimensione del limite.

Per informazioni sull'esecuzione di query GQL, sul binding dei parametri e sull'accesso ai risultati, consulta la classe GqlQuery e il metodo della classe 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à di tipo Person la cui età è compresa tra 18 e 35 anni (ovvero sia Charlie che Edna), utilizza questa query:

SELECT * FROM Person WHERE age >= 18 AND age <= 35

Per trovare le tre entità di tipo Person le cui età sono le maggiori (ovvero Amy, Betty e Charlie), utilizza questa query:

SELECT * FROM Person ORDER BY age DESC LIMIT 3

Per trovare le entità di tipo Person i cui nomi sono "Betty" o "Charlie", 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, ordinati 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à di None (ovvero KEY('Person', 'georgemichael')), utilizza questa query:

SELECT __key__ FROM Person WHERE age = NULL

Per trovare tutte le entità, indipendentemente dal tipo, che si trovano nel gruppo di entità (ovvero Amy e Fred), utilizza questa query:

SELECT * WHERE __key__ HAS ANCESTOR KEY(Person, 'Amy')

Per la corrispondenza per 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à.