Entità, proprietà e chiavi

Nota: gli sviluppatori che creano nuove applicazioni sono vivamente incoraggiati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, come la memorizzazione automatica nella cache delle entità tramite l'API Memcache. Se attualmente utilizzi la libreria client di DB precedente, leggi la guida alla migrazione da DB a NDB

Gli oggetti di dati in Datastore sono noti come entità. Un'entità ha una o più proprietà denominate, ciascuna delle quali può avere uno o più valori. Non è necessario che entità dello stesso tipo abbiano le stesse proprietà e i valori di un'entità per una determinata proprietà non devono essere tutti dello stesso tipo di dati. Se necessario, un'applicazione può stabilire e applicare queste restrizioni nel proprio modello dei dati.

Datastore supporta diversi tipi di dati per i valori delle proprietà. Sono inclusi, tra gli altri:

• Numeri interi
• Numeri con virgola mobile
• Stringhe
• Date
• Dati binari

Per un elenco completo dei tipi, consulta Proprietà e tipi di valori.

Ogni entità in Datastore ha una chiave che la identifica in modo univoco. La chiave è costituita dai seguenti componenti:

• Lo spazio dei nomi dell'entità, che consente la multitenancy
• Il kind dell'entità, che la classifica per le query Datastore
• Un identificatore per la singola entità, che può essere:
  • una stringa nome chiave
  • Un ID numerico intero
• Un percorso predecessore facoltativo che individua l'entità all'interno della gerarchia di Datastore

Non assegnare il nome "chiave" alla proprietà. Questo nome è riservato a una proprietà speciale utilizzata per archiviare la chiave del modello. Sebbene possa funzionare localmente, una proprietà denominata "key" impedirà il deployment in App Engine.

Un'applicazione può recuperare una singola entità da Datastore utilizzando la chiave dell'entità oppure può recuperare una o più entità inviando una query basata sulle chiavi o sui valori delle proprietà delle entità.

L'SDK per Python App Engine include una libreria di modellazione dei dati per rappresentare le entità Datastore come istanze di classi Python, nonché per archiviare e recuperare queste istanze in Datastore.

Datastore stesso non applica alcuna restrizione sulla struttura delle entità, ad esempio se una determinata proprietà ha un valore di un determinato tipo; questa attività viene lasciata all'applicazione e alla libreria di modellazione dei dati.

Tipi e identificatori

Ogni entità Datastore è di un tipo specifico,che categorizza l'entità ai fini delle query: ad esempio, un'applicazione per le risorse umane potrebbe rappresentare ogni dipendente di un'azienda con un'entità di tipo Employee. Nell'API Python Datastore, il tipo di entità è determinato dalla classe di modello, che definisci nell'applicazione come sottoclasse della classe della libreria di modellazione dei dati db.Model. Il nome della classe del modello diventa il tipo di entità che le appartengono. Tutti i nomi dei tipi che iniziano con due trattini bassi (__) sono riservati e non possono essere utilizzati.

L'esempio seguente crea un'entità di tipo Employee, compila i valori delle proprietà e la salva in Datastore:

import datetime
from google.appengine.ext import db


class Employee(db.Model):
  first_name = db.StringProperty()
  last_name = db.StringProperty()
  hire_date = db.DateProperty()
  attended_hr_training = db.BooleanProperty()


employee = Employee(first_name='Antonio',
                    last_name='Salieri')

employee.hire_date = datetime.datetime.now().date()
employee.attended_hr_training = True

employee.put()

La classe Employee dichiara quattro proprietà per il modello dei dati: first_name, last_name, hire_date e attended_hr_training. La superclasse Model garantisce che gli attributi degli oggetti Employee siano conformi a questo modello: ad esempio, un tentativo di assegnare un valore di stringa all'attributo hire_date comporterebbe un errore di runtime, poiché il modello dei dati per hire_date è stato dichiarato come db.DateProperty.

Oltre a un tipo, ogni entità ha un identificatore, assegnato al momento della creazione dell'entità. Poiché fa parte della chiave dell'entità, l'identificatore è associato in modo permanente all'entità e non può essere modificato. Può essere assegnato in due modi:

• L'applicazione può specificare la propria stringa nome chiave per l'entità.
• Puoi fare in modo che Datastore assegni automaticamente all'entità un ID numerico intero.

Per assegnare un nome chiave a un'entità, fornisci l'argomento denominato key_name al costruttore della classe del modello quando crei l'entità:

# Create an entity with the key Employee:'asalieri'.
employee = Employee(key_name='asalieri')

Nota:

• I nomi delle chiavi non possono iniziare e terminare con due trattini bassi (__*__)
• Oltre ad argomenti come key_name, il costruttore Model accetta i valori iniziali per le proprietà come argomenti delle parole chiave. Per questo motivo è scomodo avere una proprietà chiamata key_name.

Per saperne di più, consulta la sezione Nomi di proprietà non consentiti.

Per fare in modo che Datastore assegni automaticamente un ID numerico, ometti l'argomento key_name:

# Create an entity with a key such as Employee:8261.
employee = Employee()

Assegnazione degli identificatori

Datastore può essere configurato per generare ID automatici utilizzando due diversi criteri per gli ID automatici:

• Il criterio default genera una sequenza casuale di ID inutilizzati distribuiti approssimativamente in modo uniforme. Ogni ID può contenere fino a 16 cifre decimali.
• Il criterio legacy crea una sequenza di ID interi più piccoli non consecutivi.

Se vuoi mostrare gli ID entità all'utente e/o dipendere dall'ordine, la cosa migliore da fare è utilizzare l'allocazione manuale.

Nota: anziché utilizzare stringhe di nomi chiave o generare ID numerici automaticamente, le applicazioni avanzate a volte potrebbero voler assegnare manualmente i propri ID numerici alle entità che creano. Tuttavia, tieni presente che non c'è nulla che impedisca a Datastore di assegnare uno degli ID numerici manuali a un'altra entità. L'unico modo per evitare questi conflitti è fare in modo che l'applicazione riceva un blocco di ID con i metodi allocate_ids() o allocate_ids_async(). Il generatore di ID automatico di Datastore terrà traccia degli ID allocati con questi metodi e eviterà di riutilizzarli per un'altra entità, in modo da poter utilizzare questi ID senza creare conflitti.

Datastore genera una sequenza casuale di ID inutilizzati distribuiti approssimativamente in modo uniforme. Ogni ID può contenere fino a 16 cifre decimali.

Percorsi predecessori

Le entità in Cloud Datastore formano uno spazio strutturato gerarchicamente, simile alla struttura di directory di un file system. Quando crei un'entità, puoi facoltativamente designare un'altra entità come parent;; la nuova entità è un parent; dell'entità padre (tieni presente che, a differenza di un file system, l'entità padre non deve necessariamente esistere). Un'entità senza un elemento padre è un'entità principale. L'associazione tra un'entità e l'entità padre è permanente e non può essere modificata una volta creata l'entità. Cloud Datastore non assegnerà mai lo stesso ID numerico a due entità con lo stesso padre o a due entità principali (quelle senza una padre).

L'elemento principale di un'entità, l'elemento principale di un'entità padre e così via in modo ricorsivo sono i suoi antenati; gli elementi secondari, quelli secondari e così via sono i discendenti. Un'entità base e tutti i suoi discendenti appartengono allo stesso gruppo di entità. La sequenza di entità che iniziano con un'entità radice e che proseguono da padre a figlio e portano a una data entità, costituiscono il percorso predecessore di quell'entità. La chiave completa che identifica l'entità è composta da una sequenza di coppie tipo-identificatore che specificano il percorso dei predecessori e termina con quelli dell'entità stessa:

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

Per unentità base, il percorso predecessore è vuoto e la chiave è costituita esclusivamente dal tipo e dall'identificatore dell'entità:

[Person:GreatGrandpa]

Questo concetto è illustrato dal seguente diagramma:

Per designare l'elemento padre di un'entità, utilizza l'argomento parent per il costruttore della classe del modello durante la creazione dell'entità figlio. Il valore di questo argomento può essere l'entità padre stessa o la sua chiave; puoi ottenere la chiave chiamando il metodo key() dell'entità padre. L'esempio seguente crea un'entità di tipo Address e mostra due modi per designare un'entità Employee come entità padre:

# Create Employee entity
employee = Employee()
employee.put()

# Set Employee as Address entity's parent directly...
address = Address(parent=employee)

# ...or using its key
e_key = employee.key()
address = Address(parent=e_key)

# Save Address entity to datastore
address.put()

Transazioni e gruppi di entità

Ogni tentativo di creare, aggiornare o eliminare un'entità avviene nel contesto di una transazione. Una singola transazione può includere un numero illimitato di operazioni di questo tipo. Per mantenere la coerenza dei dati, la transazione garantisce che tutte le operazioni che contiene vengano applicate a Datastore come unità o, in caso di operazione non riuscita, nessuna di esse venga applicata. Inoltre, tutte le letture a elevata coerenza (query o richieste dei predecessori) eseguite all'interno della stessa transazione osservano uno snapshot coerente dei dati.

Nota: se la tua applicazione riceve un'eccezione quando tenta di eseguire il commit di una transazione, non significa necessariamente che la transazione non sia andata a buon fine. È possibile ricevere un'eccezione Timeout, TransactionFailedError o InternalError anche se è stato eseguito il commit di una transazione e alla fine verrà applicata correttamente. Quando possibile, struttura le transazioni Datastore in modo che il risultato finale non venga modificato se la stessa transazione viene applicata più di una volta.

Come già detto, un gruppo di entità è un insieme di entità collegate tramite discendenza a un elemento radice comune. L'organizzazione dei dati in gruppi di entità può limitare le transazioni che è possibile eseguire:

• Tutti i dati a cui accede una transazione devono essere contenuti in massimo 25 gruppi di entità.
• Se vuoi utilizzare le query all'interno di una transazione, i dati devono essere organizzati in gruppi di entità in modo da poter specificare i filtri predecessori che corrispondono ai dati corretti.
• Esiste un limite di velocità effettiva di scrittura di circa una transazione al secondo all'interno di un singolo gruppo di entità. Questa limitazione esiste perché Datastore esegue la replica sincrona masterless di ciascun gruppo di entità su un'ampia area geografica per fornire affidabilità e tolleranza di errore elevate.

In molte applicazioni, è accettabile utilizzare la coerenza finale (ovvero una query non predecessore che comprende più gruppi di entità, che a volte può restituire dati leggermente obsoleti) quando si ottiene un'ampia visione di dati non correlati e quindi utilizzare elevata coerenza (una query da predecessore o get di una singola entità) durante la visualizzazione o la modifica di un singolo set di dati altamente correlati. In queste applicazioni, di solito è un buon approccio utilizzare un gruppo di entità separato per ogni set di dati altamente correlati. Per ulteriori informazioni, consulta la sezione Strutturare una struttura per una coerenza elevata.

Nota: evita di archiviare informazioni sensibili nella chiave del gruppo di entità. Le chiavi dei gruppi di entità possono essere conservate dopo l'eliminazione del gruppo di entità per fornire un servizio rapido e affidabile in Datastore.

Proprietà e tipi di valore

I valori dei dati associati a un'entità sono costituiti da una o più proprietà. Ogni proprietà ha un nome e uno o più valori. Una proprietà può avere valori di più tipi e due entità possono avere valori di tipi diversi per la stessa proprietà. Le proprietà possono essere indicizzate o non indicizzate (le query che ordinano o filtrano i dati su una proprietà P ignoreranno le entità in cui P non è indicizzato). Un'entità può avere al massimo 20.000 proprietà indicizzate.

Nota: le proprietà con più valori possono essere utili, ad esempio, quando si eseguono query con filtri di uguaglianza: un'entità soddisfa la query se uno qualsiasi dei suoi valori per una proprietà corrisponde a quello specificato nel filtro. Per ulteriori dettagli sulle proprietà a più valori, inclusi i problemi di cui devi essere a conoscenza, consulta la pagina Query Datastore.

Sono supportati i seguenti tipi di valori:

Tipo di valore	Tipi Python	Ordinamento	Note
Integer	int long	Numerico	Numero intero a 64 bit, firmato
Numero con virgola mobile	float	Numerico	Doppia precisione a 64 bit, IEEE 754
Booleano	bool	False<True
Stringa di testo (breve)	str unicode	Unicode (str considerato come ASCII)	Fino a 1500 byte
Stringa di testo (lunga)	db.Text	Nessuna	Fino a 1 megabyte Non indicizzato
Stringa byte (breve)	db.ByteString	Ordine byte	Fino a 1500 byte
Stringa byte (lunga)	db.Blob	Nessuna	Fino a 1 megabyte Non indicizzato
Data e ora	datetime.date datetime.time datetime.datetime	Cronologica
Punto geografico	db.GeoPt	Per latitudine, poi longitudine
Indirizzo postale	db.PostalAddress	Unicode
Numero di telefono	db.PhoneNumber	Unicode
Indirizzo email	db.Email	Unicode
Utente Account Google	users.User	Indirizzo email in ordine Unicode
Handle per messaggistica immediata	db.IM	Unicode
Link	db.Link	Unicode
Categoria	db.Category	Unicode
Valutazione	db.Rating	Numerico
Chiave Datastore	db.Key	In base agli elementi del percorso (kind, identificatore, kind, identificatore...)
Chiave archivio BLOB	blobstore.BlobKey	Ordine byte
Null	NoneType	Nessuna

Importante: ti consigliamo vivamente di non archiviare un UserProperty, poiché include l'indirizzo email e l'ID univoco dell'utente. Se un utente cambia il proprio indirizzo email e confronti il valore User precedente e archiviato con il nuovo valore User, non corrisponderanno.

Per stringhe di testo e dati binari non codificati (stringhe di byte), Datastore supporta due tipi di valori:

• Le stringhe brevi (fino a 1500 byte) vengono indicizzate e possono essere utilizzate nelle condizioni di filtro delle query e negli ordinamento.
• Le stringhe lunghe (fino a 1 megabyte) non vengono indicizzate e non possono essere utilizzate nei filtri di query e negli ordinamenti.

Nota: il tipo di stringa a byte lunghi è denominato Blob nell'API Datastore. Questo tipo non è correlato ai BLOB utilizzati nell'API Blobstore.

Quando una query coinvolge una proprietà con valori di tipi misti, Datastore utilizza un ordinamento deterministico basato sulle rappresentazioni interne:

1. Valori null
2. Numeri a punto fisso
   • Numeri interi
   • Date e ore
   • Valutazioni
3. Valori booleani
4. Sequenze byte
   • Stringa byte
   • Stringa Unicode
   • Chiavi dell'archivio BLOB
5. Numeri con virgola mobile
6. Punti geografici
7. Utenti con account Google
8. Chiavi Datastore

Poiché le stringhe di testo lunghe e le stringhe di byte lunghi non vengono indicizzate, non è stato definito un ordinamento.

Nota: i numeri interi e i numeri in virgola mobile sono considerati tipi separati in Datastore. Se un'entità utilizza una combinazione di numeri interi e numeri in virgola mobile per la stessa proprietà, tutti i numeri interi vengono ordinati prima di tutti i numeri in virgola mobile: ad esempio,

7 < 3.2

Utilizzo delle entità

Le applicazioni possono utilizzare l'API Datastore per creare, recuperare, aggiornare ed eliminare entità. Se l'applicazione conosce la chiave completa di un'entità (o può derivarla dalla chiave, dal tipo e dall'identificatore padre), può utilizzare la chiave per operare direttamente sull'entità. Un'applicazione può inoltre ottenere la chiave di un'entità come risultato di una query Datastore; consulta la pagina Query Datastore per ulteriori informazioni.

Creazione di un'entità

In Python, crei una nuova entità costruendo un'istanza di una classe di modello, popolandone le proprietà se necessario e chiamando il relativo metodo put() per salvarla in Datastore. Puoi specificare il nome chiave dell'entità passando un argomento key_name al costruttore:

employee = Employee(key_name='asalieri',
                    first_name='Antonio',
                    last_name='Salieri')

employee.hire_date = datetime.datetime.now().date()
employee.attended_hr_training = True

employee.put()

Se non fornisci un nome chiave, Datastore genererà automaticamente un ID numerico per la chiave dell'entità:

employee = Employee(first_name='Antonio',
                    last_name='Salieri')

employee.hire_date = datetime.datetime.now().date()
employee.attended_hr_training = True

employee.put()

Recupero di un'entità

Per recuperare un'entità identificata da una determinata chiave, passa l'oggetto Key come argomento alla funzione db.get(). Puoi generare l'oggetto Key utilizzando il metodo della classe Key.from_path(). Il percorso completo è una sequenza di entità nel percorso predecessore, dove ogni entità è rappresentata dal tipo (una stringa) seguito dal relativo identificatore (nome chiave o ID numerico):

address_k = db.Key.from_path('Employee', 'asalieri', 'Address', 1)
address = db.get(address_k)

db.get() restituisce un'istanza della classe del modello appropriata. Assicurati di aver importato la classe del modello per l'entità che viene recuperata.

Aggiornamento di un'entità

Per aggiornare un'entità esistente, modifica gli attributi dell'oggetto, quindi chiama il relativo metodo put(). I dati dell'oggetto sovrascrivono l'entità esistente. L'intero oggetto viene inviato a Datastore con ogni chiamata a put().

Nota: l'API Datastore non fa distinzione tra la creazione di una nuova entità e l'aggiornamento di una esistente. Se la chiave dell'oggetto rappresenta un'entità già esistente, il metodo put() sovrascrive l'entità esistente. Puoi utilizzare una transazione per verificare l'esistenza di un'entità con una determinata chiave prima di crearne una. Vedi anche il metodo Model.get_or_insert().

Per eliminare una proprietà, elimina l'attributo dall'oggetto Python:

del address.postal_code

quindi salva l'oggetto.

Eliminazione di un'entità

Data la chiave di un'entità, puoi eliminare l'entità con la funzione db.delete()

address_k = db.Key.from_path('Employee', 'asalieri', 'Address', 1)
db.delete(address_k)

oppure chiamando il metodo delete() dell'entità:

employee_k = db.Key.from_path('Employee', 'asalieri')
employee = db.get(employee_k)

# ...

employee.delete()

Operazioni batch

Le funzioni db.put(), db.get() e db.delete() (e le relative controparti asincrone db.put_async(), db.get_async() e db.delete_async()) possono accettare un argomento elenco per agire su più entità in una singola chiamata Datastore:

# A batch put.
db.put([e1, e2, e3])

# A batch get.
entities = db.get([k1, k2, k3])

# A batch delete.
db.delete([k1, k2, k3])

Le operazioni collettive non modificano i tuoi costi. Ti verrà addebitata ogni chiave in un'operazione in batch, indipendentemente dal fatto che ogni chiave esista o meno. Le dimensioni delle entità coinvolte in un'operazione non influiscono sui costi.

Nota: una chiamata batch a db.put() o db.delete() potrebbe riuscire per alcune entità, ma non per altre. Se è importante che la chiamata abbia esito positivo o negativo del tutto, devi utilizzare una transazione e tutte le entità interessate devono essere nello stesso gruppo di entità.

Eliminazione di entità in blocco

Se devi eliminare un numero elevato di entità, ti consigliamo di utilizzare Dataflow per eliminare le entità in blocco.

Utilizzo di un elenco vuoto

Per l'interfaccia NDB, Datastore ha scritto storicamente un elenco vuoto come proprietà omessa per le proprietà statiche e dinamiche. Per mantenere la compatibilità con le versioni precedenti, questo comportamento continua a essere predefinito. Per eseguire l'override di questo criterio a livello globale o in base a ListProperty, imposta l'argomento write_empty_list su true nella tua classe Property; l'elenco vuoto viene quindi scritto in Datastore e può essere letto come elenco vuoto.

Per l'interfaccia DB, in passato non erano consentite scritture di elenchi vuoti se la proprietà era dinamica: se hai tentato di eseguire questa operazione, si è verificato un errore. Ciò significa che non è necessario mantenere alcun comportamento predefinito per la compatibilità con le versioni precedenti delle proprietà dinamiche del database. Di conseguenza, puoi semplicemente scrivere e leggere l'elenco vuoto nel modello dinamico senza alcuna modifica.

Tuttavia, per le proprietà statiche del database, l'elenco vuoto è stato scritto come proprietà omessa e questo comportamento continua per impostazione predefinita per garantire la compatibilità con le versioni precedenti. Se vuoi attivare elenchi vuoti per le proprietà statiche del database, utilizza l'argomento write_empty_list in true nella tua classe Property. L'elenco vuoto viene quindi scritto in Datastore.