Riferimento GQL per Python NDB/DB

GQL è un linguaggio simile a SQL per il recupero di entità e chiavi. La sintassi delle query GQL è simile a quella di 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 esegui le query. Esistono due tipi di regole GQL riferimenti:

• 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 GQL per NDB/DB di Python 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 in SQL, le parole chiave GQL non fanno distinzione tra maiuscole e minuscole. Nomi di tipo e proprietà sono sensibile alle maiuscole.

GQL supporta solo le 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ù rapide e utilizzano meno tempo della CPU rispetto alle query SELECT *.

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 query senza tipo e può avere solo un WHERE che specifica una proprietà __key__.

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 è equivalente a molte query =, una per ogni valore, combinate con l'operatore OR. Un'entità il cui valore per la data 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 prodotto incrociato di tutte le query del datastore sottostante e vengono deduplicate. Per ogni singola query GQL sono consentite al massimo 30 query sul datastore.

Una condizione può anche verificare se un'entità ha una determinata entità come antecessore utilizzando l'operatore ANCESTOR IS. Il valore è un'istanza o una chiave del modello per l'entità principale. Per ulteriori informazioni sugli antenati, consulta Chiavi e gruppi di entità.

Il lato sinistro di un confronto è sempre un nome di proprietà. Un nome di proprietà tipico è costituito da caratteri alfanumerici, eventualmente combinati con 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 (ad esempio appropriati per il tipo di dati della proprietà):

• Un valore letterale str, come stringa tra virgolette singole. Virgoletta singola caratteri di questa 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 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 rappresentazione in virgola mobile valori:
  GEOPT(lat, long)
• un valore parametro vincolato. Nella stringa di query, i parametri posizionali vengono indicati tramite 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 all'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() . I tipi di dati delle proprietà che non hanno una sintassi di valore letterale corrispondente devono essere specificati utilizzando la definizione dei parametri, incluso il tipo di dati dell'elenco. Le associazioni di parametri possono essere ricollegate con nuovi valori durante il ciclo di vita 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 restituito ordinati in base alle proprietà specificate, in ordine crescente (ASC) o 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. Una clausola OFFSET facoltativa può specificare un <offset>, se non è presente una 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. Ha effetto solo sui risultati retitrati 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 con 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à di Amy (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 con 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__, ti consigliamo di utilizzare get() per recuperare direttamente l'entità.