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 libreria DB Datastore precedente aggiungendo 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-context e Memcache.
- Supporta sia le API asincrone per le 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 dati, chiamati entità. Un'entità ha una o più proprietà, ovvero valori denominati di uno dei diversi tipi di dati supportati. Ad esempio, una proprietà può essere una stringa, un 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 una principale, un'altra chiave. Questo genitore può a sua volta avere un genitore e così via. in cima a questa "catena" dei genitori è una chiave senza padre, chiamata root.
Le entità le cui chiavi hanno la stessa radice in un gruppo di entità oppure gruppo. Se le entità si trovano in gruppi diversi, a volte le modifiche a queste entità potrebbero sembrare "fuori sequenza". Se le entità non sono correlate nella semantica della tua applicazione, va bene. Tuttavia, se alcune modifiche delle entità devono essere coerenti, l'applicazione deve inserirle nello stesso gruppo al momento della creazione.
Il seguente diagramma delle entità e l'esempio di codice mostrano come un Guestbook
puoi avere più Greetings
, ciascuno con proprietà content
e date
.
Questa relazione è implementata nell'esempio di codice riportato di seguito.
Utilizzo di modelli per l'archiviazione dei dati
Un modello è una classe che descrive un tipo di entità, tra cui i tipi e
configurazione per le sue proprietà. È più o meno simile a una tabella in SQL. Un
l'entità può essere creata chiamando il costruttore della classe del modello,
chiamando il metodo put()
.
Questo codice campione definisce la classe del modello Greeting
. Ogni entità Greeting
ha
due proprietà: il contenuto del testo del saluto e la data dell'annuncio
è stato creato.
Per creare e archiviare un nuovo saluto, l'applicazione crea un nuovo Greeting
e chiama il suo metodo put()
.
Per assicurarti che i saluti in un guestbook non risultino "non in ordine"
l'applicazione imposta una chiave padre durante la creazione di un nuovo Greeting
.
Di conseguenza, il nuovo saluto sarà nello stesso gruppo di entità di altri
gli auguri nello stesso guestbook. L'applicazione utilizza questo fatto
durante l'esecuzione di query: utilizza una query da predecessore.
Query e indici
Un'applicazione può eseguire query per trovare entità che corrispondono ad alcuni filtri.
Una query NDB tipica filtra le entità in base al tipo. In questo esempio,
query_book
genera una query che restituisce Greeting
le entità. Una query può anche specificare filtri per i valori e le chiavi delle proprietà delle entità.
Come in questo esempio, una query può specificare un predecessore, individuando solo le entità
"appartengono a" un predecessore. Una query può specificare l'ordinamento. Se una determinata entità ha almeno un valore (eventualmente 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, ovvero una tabella che contiene i risultati relativi la query nell'ordine desiderato. Il datastore sottostante gestisce automaticamente indici semplici (indici che utilizzano una sola proprietà).
Definisce i suoi indici complessi in un file di configurazione, index.yaml
. Il
server web di sviluppo aggiunge automaticamente suggerimenti a questo file quando
incontra query per le quali non sono ancora stati configurati gli indici.
Puoi ottimizzare manualmente gli indici modificando il file prima di caricare il file
un'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 degli indici prima di caricare il codice che utilizza il nuovo indice. Puoi utilizzare la console di amministrazione
per sapere quando è stata completata la creazione degli indici.
Questo meccanismo di indicizzazione supporta un'ampia gamma di query ed è adatto alla maggior parte diverse applicazioni. Tuttavia, non supporta alcuni tipi di query comuni in altre tecnologie di database. In particolare, i join non sono supportati.
Comprensione delle scritture NDB: eseguire il commit, la convalida della cache e l'applicazione
NDB scrive i dati in passaggi:
- Nella fase di commit, le modifiche vengono registrate dal servizio Datastore sottostante.
- NDB invalida le cache delle entità o delle entità interessate. Pertanto, le letture future leggeranno (e memorizzeranno nella cache) il Datastore sottostante anziché leggere valori non aggiornati dalla cache.
- Infine, forse pochi secondi dopo, il datastore sottostante applica la classe modifica. Rende la modifica visibile alle query globali e, operazioni coerenti.
La funzione NDB che scrive i dati (ad esempio, put()
)
restituisce dopo l'annullamento della convalida della cache; si verifica la fase di applicazione
in modo asincrono.
Se si verifica un errore durante la fase di commit, ci sono nuovi tentativi automatici, ma Se gli errori persistono, l'applicazione riceve un'eccezione. Se il commit la fase di applicazione ha esito positivo, ma l'applicazione non riesce e viene eseguito il rollback fino al completamento quando si verifica una delle seguenti condizioni:
- "Sweep" di Datastore periodici controlla la presenza di job di commit non completati e applicali.
- 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 all'applicazione. La modifica potrebbe non essere applicata completamente al datastore sottostante alcune centinaia millisecondi dopo la restituzione della funzione NDB. Una query non principale eseguita durante l'applicazione di una modifica potrebbe mostrare uno stato incoerente, ovvero parte, ma non tutta la modifica.
Transazioni e dati memorizzati nella cache
La libreria client NDB può raggruppare più operazioni in una transazione. La transazione non può avere esito positivo a meno che ogni operazione al suo interno non vada a buon fine. Se una delle operazioni non va a buon fine, la transazione viene annullata automaticamente. Questo è particolarmente utile per le applicazioni web distribuite, in cui più utenti potrebbero accedere o manipolare contemporaneamente gli stessi dati.
NDB utilizza Memcache come servizio di cache per gli "hot spot" 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 di Django, aggiungi
google.appengine.ext.ndb.django_middleware.NdbDjangoMiddleware
alla
Voce MIDDLEWARE_CLASSES
nel tuo file Django settings.py
. È meglio
lo inserisci prima di qualsiasi altra classe middleware, perché qualche altro
il middleware potrebbe effettuare chiamate al datastore che non verranno gestite correttamente se
il middleware viene richiamato prima di questo middleware. Puoi scoprire di più sul middleware Django.
Passaggi successivi
Scopri di più su:
- Creazione di entità in NDB.
- Modalità di elaborazione delle transazioni in Datastore.
- Come creare e formattare una query con la libreria client NDB.
- Memorizzazione nella cache dei dati mediante NDB e l'infrastruttura Memcache sottostante.
- Amministrazione e gestione dei dati archiviati in Datastore.