Panoramica della libreria client NDB di App Engine

La libreria client NDB di Google Datastore consente alle app Python di App Engine di connettersi a Datastore. La libreria client NDB si basa sulla precedente libreria DB Datastore e aggiunge le seguenti funzionalità del datastore:

  • La classe StructuredProperty, che consente alle entità di avere una struttura nidificata.
  • Memorizzazione nella cache automatica integrata, che in genere consente letture rapide ed economiche tramite una cache in contesto e Memcache.
  • Supporta sia le API asincrone per azioni simultanee sia le API sincrone.

Questa pagina fornisce un'introduzione e una panoramica della libreria client NDB di App Engine. Per informazioni su come eseguire la migrazione a Cloud NDB, che supporta Python 3, consulta Migrazione a Cloud NDB.

Definizione di entità, chiavi e proprietà

Datastore archivia oggetti di dati, chiamati entità. Un'entità ha una o più proprietà, valori denominati di uno dei diversi tipi di dati supportati. Ad esempio, una proprietà può essere una stringa, un numero intero o un riferimento a un'altra entità.

Ogni entità è identificata da una chiave, un identificatore univoco all'interno del datastore dell'applicazione. La chiave può avere un genitore, un'altra chiave. Questo genitore può a sua volta avere un genitore e così via; in cima a questa "catena" di genitori c'è una chiave senza genitore, chiamata radice.

Mostra la relazione tra l'entità principale e le entità secondarie in un gruppo di entità

Le entità le cui chiavi hanno la stessa radice formano un gruppo di entità o gruppo. Se le entità si trovano in gruppi diversi, le modifiche apportate a queste entità a volte potrebbero sembrare "fuori ordine". Se le entità non sono correlate nella semantica della tua applicazione, non c'è problema. Tuttavia, se le modifiche di alcune entità devono essere coerenti, l'applicazione deve includerle nello stesso gruppo durante la creazione.

Il seguente diagramma delle relazioni tra entità e l'esempio di codice mostrano come un Guestbook possa avere più Greetings, ognuno con proprietà content e date.

Mostra le relazioni tra le entità come create dal codice di esempio incluso

Utilizzo dei modelli per l'archiviazione dei dati

Un modello è una classe che descrive un tipo di entità, inclusi i tipi e la configurazione delle relative proprietà. È più o meno analogo a una tabella in SQL. Un'entità può essere creata chiamando il costruttore della classe del modello e poi archiviata chiamando il metodo put().

Query e indici

Un'applicazione può eseguire query per trovare entità che corrispondono ad alcuni filtri.

Una tipica query NDB filtra le entità per tipo. Una query può anche specificare filtri su chiavi e valori delle proprietà delle entità, nonché l'ordinamento. Se una determinata entità ha almeno un valore (possibilmente nullo) per ogni proprietà nei filtri e negli ordini di ordinamento e tutti i criteri di filtro sono soddisfatti dai valori delle proprietà, l'entità viene restituita come risultato.

Ogni query utilizza un indice, una tabella che contiene i risultati della query nell'ordine desiderato. Datastore sottostante gestisce automaticamente gli indici semplici (indici che utilizzano una sola proprietà).

Definisce gli indici complessi in un file di configurazione, index.yaml. Il server web di sviluppo aggiunge automaticamente suggerimenti a questo file quando rileva query per le quali non sono ancora stati configurati indici.

Puoi ottimizzare gli indici manualmente modificando il file prima di caricare l'applicazione. Puoi aggiornare gli indici separatamente dal caricamento dell'applicazione eseguendo gcloud app deploy index.yaml.

Se il tuo datastore contiene molte entità, la creazione di un nuovo indice richiede molto tempo. In questo caso, è consigliabile aggiornare le definizioni dell'indice prima di caricare il codice che utilizza il nuovo indice. Puoi utilizzare la console di amministrazione per scoprire quando è terminata la creazione degli indici.

Questo meccanismo di indicizzazione supporta un'ampia gamma di query ed è adatto alla maggior parte delle applicazioni. Tuttavia, non supporta alcuni tipi di query comuni in altre tecnologie di database. In particolare, i join non sono supportati.

Informazioni sulle scritture NDB: commit, annullamento della convalida della cache e applicazione

NDB scrive i dati in passaggi:

  • Nella fase di commit, il servizio Datastore sottostante registra le modifiche.
  • NDB invalida le cache delle entità interessate. Pertanto, le letture future leggeranno (e memorizzeranno nella cache) il Datastore sottostante anziché leggere valori non aggiornati dalla cache.
  • Infine, forse qualche secondo dopo, Datastore sottostante applica la modifica. Rende la modifica visibile alle query globali e, alla fine, alle letture coerenti.

La funzione NDB che scrive i dati (ad esempio put()) viene restituita dopo l'invalidazione della cache; la fase di applicazione avviene in modo asincrono.

Se si verifica un errore durante la fase di commit, vengono eseguiti nuovi tentativi automatici, ma se gli errori continuano, l'applicazione riceve un'eccezione. Se la fase Commit va a buon fine, ma la fase Apply non riesce, l'applicazione viene completata quando si verifica una delle seguenti condizioni:

  • Le "pulizie" periodiche di Datastore controllano i job di commit non completati e li applicano.
  • La successiva scrittura, transazione o lettura fortemente coerente nel gruppo di entità interessato fa sì che le modifiche non ancora applicate vengano applicate prima della lettura, della scrittura o della transazione.

Questo comportamento influisce su come e quando i dati sono visibili alla tua applicazione. La modifica potrebbe non essere applicata completamente al datastore sottostante qualche centinaio di millisecondi dopo la restituzione della funzione NDB. Una query non discendente eseguita durante l'applicazione di una modifica potrebbe visualizzare uno stato incoerente, ovvero parte della modifica, ma non tutta.

Transazioni e dati memorizzati nella cache

La libreria client NDB può raggruppare più operazioni in una singola transazione. La transazione non può andare a buon fine a meno che ogni operazione al suo interno non abbia esito positivo; se una delle operazioni non riesce, la transazione viene automaticamente annullata. Ciò è particolarmente utile per le applicazioni web distribuite, in cui più utenti potrebbero accedere o manipolare gli stessi dati contemporaneamente.

NDB utilizza Memcache come servizio di memorizzazione nella cache per gli "hotspot" nei dati. Se l'applicazione legge spesso alcune entità, NDB può leggerle rapidamente dalla cache.

Utilizzo di Django con NDB

Per utilizzare NDB con il framework web Django, aggiungi google.appengine.ext.ndb.django_middleware.NdbDjangoMiddleware all'elemento MIDDLEWARE_CLASSES nel file settings.py di Django. È meglio inserirlo prima di qualsiasi altra classe middleware, perché alcuni altri middleware potrebbero effettuare chiamate al datastore e queste non verranno gestite correttamente se il middleware viene richiamato prima di questo. Puoi scoprire di più sul middleware Django.

Passaggi successivi

Scopri di più su: