Riferimento alle proprietà delle entità

Firestore in modalità Datastore (Datastore) supporta una serie di tipi di dati per i valori delle proprietà. Questi includono, tra gli altri:

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

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

Proprietà e tipi di valori

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ù di un tipo 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 in base a una proprietà P ignorano le entità in cui P non è indicizzata). Un'entità può avere al massimo 20.000 proprietà indicizzate.

Sono supportati i seguenti tipi di valori:

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 in virgola fissa
    • Numeri interi
    • Date e ore
  3. Valori booleani
  4. Sequenze di byte
    • Stringa Unicode
    • Chiavi Blobstore
  5. Numeri in virgola mobile
  6. Chiavi Datastore

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

Tipi di proprietà

NDB supporta i seguenti tipi di proprietà:

Tipo di proprietà Descrizione
IntegerProperty Numero intero a 64 bit con segno
FloatProperty Numero in virgola mobile a precisione doppia
BooleanProperty Booleano
StringProperty Stringa Unicode; fino a 1500 byte, indicizzata
TextProperty Stringa Unicode; lunghezza illimitata, non indicizzata
BlobProperty Stringa di byte non interpretata:
se imposti indexed=True, fino a 1500 byte, indicizzata;
se indexed è False (il valore predefinito), lunghezza illimitata, non indicizzata.
Argomento facoltativo della parola chiave: compressed.
DateTimeProperty Data e ora (vedi Proprietà di data e ora)
DateProperty Data (vedi Proprietà di data e ora)
TimeProperty Ora (vedi Proprietà data e ora)
GeoPtProperty Posizione geografica. Si tratta di un oggetto ndb.GeoPt. L'oggetto ha gli attributi lat e lon, entrambi float. Puoi crearne uno con due numeri in virgola mobile come ndb.GeoPt(52.37, 4.88) o con una stringa ndb.GeoPt("52.37, 4.88"). (In realtà, si tratta della stessa classe di db.GeoPt)
KeyProperty Chiave Datastore
Argomento parola chiave facoltativo: kind=kind, per richiedere che le chiavi assegnate a questa proprietà abbiano sempre il tipo indicato. Può essere una stringa o una sottoclasse Model.
BlobKeyProperty Chiave Blobstore
Corrisponde a BlobReferenceProperty nella vecchia API db, ma il valore della proprietà è un BlobKey anziché un BlobInfo; puoi creare un BlobInfo da questo valore utilizzando BlobInfo(blobkey)
UserProperty Oggetto utente.
StructuredProperty Include un tipo di modello all'interno di un altro, per valore (vedi Proprietà strutturate)
LocalStructuredProperty Come StructuredProperty, ma la rappresentazione su disco è un blob opaco e non viene indicizzata (vedi Proprietà strutturate).
Argomento facoltativo della parola chiave: compressed.
JsonProperty Il valore è un oggetto Python (ad esempio un elenco, un dizionario o una stringa) serializzabile utilizzando il modulo json di Python; Datastore memorizza la serializzazione JSON come blob. Non indicizzato per impostazione predefinita.
Argomento facoltativo della parola chiave: compressed.
PickleProperty Il valore è un oggetto Python (ad esempio un elenco, un dizionario o una stringa) serializzabile utilizzando il protocollo pickle di Python. Datastore memorizza la serializzazione pickle come blob. Non indicizzato per impostazione predefinita.
Argomento facoltativo della parola chiave: compressed.
GenericProperty Valore generico
Utilizzato principalmente dalla classe Expando, ma utilizzabile anche in modo esplicito. Il tipo può essere uno dei seguenti: int, long, float, bool, str, unicode, datetime, Key, BlobKey, GeoPt, User, None.
ComputedProperty Valore calcolato da altre proprietà mediante una funzione definita dall'utente;utente. (vedi Proprietà calcolate).

Alcune di queste proprietà hanno un argomento di parola chiave facoltativo, compressed. Se la proprietà ha compressed=True, i relativi dati vengono compressi con gzip sul disco. Occupa meno spazio, ma richiede la CPU per la codifica/decodifica nelle operazioni di scrittura e lettura.

Sia la compressione che la decompressione sono "pigre"; un valore di proprietà compresso verrà decompresso solo la prima volta che vi accedi. Se leggi un'entità contenente un valore di proprietà compresso e lo riscrivi senza accedere alla proprietà compressa, non verrà decompresso e compresso. Anche la cache in-context partecipa a questo schema lazy, ma memcache memorizza sempre il valore compresso per le proprietà compresse.

A causa del tempo CPU aggiuntivo necessario per la compressione, di solito è meglio utilizzare le proprietà compresse solo se i dati sarebbero troppo grandi per essere contenuti senza. Tieni presente che la compressione basata su gzip in genere non è efficace per le immagini e altri dati multimediali, poiché questi formati sono già compressi utilizzando un algoritmo di compressione specifico per i contenuti multimediali (ad es. JPEG per le immagini).

Opzioni proprietà

La maggior parte dei tipi di proprietà supporta alcuni argomenti standard. Il primo è un argomento posizionale facoltativo che specifica il nome Datastore della proprietà. Puoi utilizzarlo per assegnare alla proprietà un nome diverso in Datastore rispetto al punto di vista dell'applicazione. Un utilizzo comune è quello di ridurre lo spazio in Datastore, consentendo a Datastore di utilizzare nomi di proprietà abbreviati mentre il codice utilizza nomi più lunghi e significativi. Ad esempio, 

class Employee(ndb.Model):
    full_name = ndb.StringProperty('n')
    retirement_age = ndb.IntegerProperty('r')

Ciò è particolarmente utile per le proprietà ripetute per le quali prevedi molti valori per entità.

Inoltre, la maggior parte dei tipi di proprietà supporta i seguenti argomenti delle parole chiave:

Argomento Tipo Predefinito Descrizione
indexed bool Di solito True Includi la proprietà negli indici di Datastore. Se False, non è possibile eseguire query sui valori, ma le scritture sono più veloci. Non tutti i tipi di proprietà supportano l'indicizzazione; l'impostazione di indexed su True non va a buon fine per questi tipi.
Le proprietà non indicizzate costano meno operazioni di scrittura rispetto a quelle indicizzate.
repeated bool False Il valore della proprietà è un elenco Python contenente i valori del tipo sottostante (vedi Proprietà ripetute).
Non può essere combinato con required=True o default=True.
required bool False La proprietà deve avere un valore specificato.
default Tipo sottostante della proprietà Nessuno Valore predefinito della proprietà se non ne è specificato esplicitamente nessuno.
choices Elenco dei valori del tipo sottostante None Elenco facoltativo di valori consentiti.
validator Funzione None

Funzione facoltativa per convalidare ed eventualmente forzare il valore.

Verrà chiamato con gli argomenti (prop, value) e deve restituire il valore (eventualmente forzato) o generare un'eccezione. Se chiami di nuovo la funzione su un valore forzato, il valore non deve essere modificato ulteriormente. Ad esempio, restituire value.strip() o value.lower() va bene, ma non value + '$'.) Può anche restituire None, che significa "nessuna modifica". Vedi anche Scrittura nelle sottoclassi di proprietà

verbose_name string None

Etichetta HTML facoltativa da utilizzare in framework di moduli web come jinja2.

Proprietà ripetute

Qualsiasi proprietà con repeated=True diventa una proprietà ripetuta. La proprietà accetta un elenco di valori del tipo sottostante, anziché un singolo valore. Ad esempio, il valore di una proprietà definita con IntegerProperty(repeated=True) è un elenco di numeri interi.

Datastore potrebbe visualizzare più valori per una proprietà di questo tipo. Per ogni valore viene creato un record di indice separato. Ciò influisce sulla semantica delle query. Per un esempio, consulta Esecuzione di query per proprietà ripetute.

Questo esempio utilizza una proprietà ripetuta: 

class Article(ndb.Model):
    title = ndb.StringProperty()
    stars = ndb.IntegerProperty()
    tags = ndb.StringProperty(repeated=True)
... 
article = Article(
    title='Python versus Ruby',
    stars=3,
    tags=['python', 'ruby'])
article.put()

Viene creata un'entità Datastore con i seguenti contenuti: 

assert article.title == 'Python versus Ruby'
assert article.stars == 3
assert sorted(article.tags) == sorted(['python', 'ruby'])

Quando esegui una query per la proprietà tags, questa entità soddisferà una query per 'python' o 'ruby'.

Quando aggiorni una proprietà ripetuta, puoi assegnarle un nuovo elenco o modificare l'elenco esistente sul posto. Quando assegni un nuovo elenco, i tipi degli elementi dell'elenco vengono convalidati immediatamente. I tipi di elementi non validi (ad esempio, l'assegnazione di [1, 2] a art.tags sopra) generano un'eccezione. Quando modifichi l'elenco, la modifica non viene convalidata immediatamente. Il valore verrà convalidato quando scrivi l'entità in Datastore.

Datastore conserva l'ordine degli elementi dell'elenco in una proprietà ripetuta, in modo da poter assegnare un significato al loro ordine.

Proprietà di data e ora

Sono disponibili tre tipi di proprietà per memorizzare valori correlati a date e ore:

  • DateProperty
  • TimeProperty
  • DateTimeProperty

Questi accettano valori appartenenti alle classi corrispondenti (date, time, datetime) del modulo datetime standard di Python. Il più generale dei tre è DateTimeProperty, che indica sia una data del calendario sia un'ora del giorno; gli altri sono utili occasionalmente per scopi speciali che richiedono solo una data (ad esempio una data di nascita) o solo un'ora (ad esempio l'ora di una riunione). Per motivi tecnici, DateProperty e TimeProperty sono sottoclassi di DateTimeProperty, ma non devi fare affidamento su questa relazione di ereditarietà (e tieni presente che è diversa dalle relazioni di ereditarietà tra le classi sottostanti definite dal modulo datetime stesso).

Nota:gli orari di App Engine sono sempre espressi in tempo universale coordinato (UTC). Ciò diventa importante se utilizzi la data o l'ora corrente (datetime.datetime.now()) come valore o se esegui la conversione tra oggetti datetime e timestamp POSIX o tuple di tempo. Tuttavia, in Datastore non vengono memorizzate informazioni esplicite sul fuso orario, quindi, se fai attenzione, puoi utilizzarli per rappresentare le ore locali in qualsiasi fuso orario, se utilizzi l'ora corrente o le conversioni.

Ognuna di queste proprietà ha due opzioni di parole chiave booleane aggiuntive:

Opzione Descrizione
auto_now_add Imposta la proprietà sulla data/ora corrente quando viene creata l'entità. Puoi eseguire l'override manuale di questa proprietà. Quando l'entità viene aggiornata, la proprietà non cambia. Per questo comportamento, utilizza auto_now.
auto_now Imposta la proprietà sulla data/ora corrente quando viene creata l'entità e ogni volta che viene aggiornata.

Queste opzioni non possono essere combinate con repeated=True. Entrambi i valori predefiniti sono False; se entrambi sono impostati su True, auto_now ha la precedenza. È possibile sostituire il valore di una proprietà con auto_now_add=True, ma non con auto_now=True. Il valore automatico non viene generato finché l'entità non viene scritta; ovvero, queste opzioni non forniscono valori predefiniti dinamici. Questi dettagli sono diversi dalla vecchia API db.

Nota: quando una transazione che scrive una proprietà con auto_now_add=True non va a buon fine e viene ritentata in un secondo momento, riutilizzerà lo stesso valore temporale del tentativo originale anziché aggiornarlo all'ora del nuovo tentativo. Se la transazione non va a buon fine in modo permanente, il valore della proprietà verrà comunque impostato nella copia in memoria dell'entità.

Proprietà strutturate

Puoi strutturare le proprietà di un modello. Ad esempio, puoi definire una classe di modello Contact contenente un elenco di indirizzi, ognuno con una struttura interna. Le proprietà strutturate (tipo StructuredProperty) ti consentono di farlo. Ad esempio: 

class Address(ndb.Model):
    type = ndb.StringProperty()  # E.g., 'home', 'work'
    street = ndb.StringProperty()
    city = ndb.StringProperty()
... 
class Contact(ndb.Model):
    name = ndb.StringProperty()
    addresses = ndb.StructuredProperty(Address, repeated=True)
... 
guido = Contact(
    name='Guido',
    addresses=[
        Address(
            type='home',
            city='Amsterdam'),
        Address(
            type='work',
            street='Spear St',
            city='SF')])

guido.put()

Viene creata una singola entità Datastore con le seguenti proprietà: 

assert guido.name == 'Guido'
addresses = guido.addresses
assert addresses[0].type == 'home'
assert addresses[1].type == 'work'
assert addresses[0].street is None
assert addresses[1].street == 'Spear St'
assert addresses[0].city == 'Amsterdam'
assert addresses[1].city == 'SF'

La lettura di un'entità di questo tipo ricostruisce esattamente l'entità Contact originale. Sebbene le istanze Address siano definite utilizzando la stessa sintassi delle classi di modelli, non sono entità a tutti gli effetti. Non hanno chiavi proprie in Datastore. Non possono essere recuperati indipendentemente dall'entità Contact a cui appartengono. Un'applicazione può, tuttavia, eseguire query per i valori dei singoli campi; vedi Filtro per valori di proprietà strutturati. Tieni presente che address.type, address.street e address.city sono considerati array paralleli dal punto di vista di Datastore, ma la libreria NDB nasconde questo aspetto e crea l'elenco corrispondente di istanze Address.

Puoi specificare le opzioni delle proprietà usuali per le proprietà strutturate (tranne indexed). In questo caso, il nome Datastore è il secondo argomento posizionale (il primo è la classe del modello utilizzata per definire la sottostruttura).

Quando non devi eseguire query per le proprietà interne di una sottostruttura, puoi utilizzare una proprietà strutturata locale (LocalStructuredProperty). Se sostituisci StructuredProperty con LocalStructuredProperty nell'esempio precedente, il comportamento del codice Python è lo stesso, ma Datastore vede solo un blob opaco per ogni indirizzo. L'entità guido creata nell'esempio verrà archiviata nel seguente modo: name = 'Guido' address = <opaque blob for {'type': 'home', 'city': 'Amsterdam'}> address = <opaque blob for {'type': 'work', 'city': 'SF', 'street': 'Spear St'}>

L'entità verrà letta correttamente. Poiché le proprietà di questo tipo sono sempre non indicizzate, non puoi eseguire query per i valori di indirizzo.

Nota:Un StructuredProperty con una proprietà nidificata (strutturata o meno) supporta un solo livello di proprietà ripetute. StructuredProperty può essere ripetuto oppure può essere ripetuta la proprietà nidificata, ma non entrambi. Una soluzione alternativa è utilizzare LocalStructuredProperty, che non presenta questo vincolo (ma non consente query sui valori delle proprietà).

Proprietà calcolate

Le proprietà calcolate (ComputedProperty) sono proprietà di sola lettura il cui valore viene calcolato a partire da altri valori di proprietà da una funzione fornita dall'applicazione. Tieni presente che una proprietà calcolata supporta solo i tipi supportati dalle proprietà generiche. Il valore calcolato viene scritto in Datastore in modo che possa essere interrogato e visualizzato nel visualizzatore Datastore, ma il valore memorizzato viene ignorato quando l'entità viene riletta da Datastore; il valore viene invece ricalcolato chiamando la funzione ogni volta che viene richiesto. Ad esempio: 

class SomeEntity(ndb.Model):
    name = ndb.StringProperty()
    name_lower = ndb.ComputedProperty(lambda self: self.name.lower())
... 
entity = SomeEntity(name='Nick')
entity.put()

Memorizza un'entità con i seguenti valori delle proprietà: 

assert entity.name == 'Nick'
assert entity.name_lower == 'nick'

Se cambiamo il nome in "Nickie" e chiediamo il valore di name_lower, viene restituito "nickie": 

entity.name = 'Nick'
assert entity.name_lower == 'nick'
entity.name = 'Nickie'
assert entity.name_lower == 'nickie'

Nota: Utilizza ComputedProperty se l'applicazione esegue query per il valore calcolato. Se vuoi solo utilizzare la versione derivata nel codice Python, definisci un metodo normale o utilizza la funzione integrata @property di Python.

Nota:Se crei un modello senza una chiave specificata manualmente e ti affidi a Datastore per generare automaticamente l'ID dell'entità, alla prima put() un ComputedProperty non sarà in grado di leggere il campo ID perché viene calcolato prima della generazione dell'ID. Se hai bisogno di un ComputedProperty che utilizzi l'ID dell'entità, puoi utilizzare il metodo allocate_ids per generare un ID e una chiave con cui creare l'entità, in modo che il tuo ComputedProperty possa fare riferimento a questo ID nel primo put() dell'entità.

Proprietà dei messaggi RPC di Google Protocol

La libreria Google Protocol RPC utilizza oggetti Message per i dati strutturati, che possono rappresentare richieste RPC, risposte o altro. NDB fornisce un'API per l'archiviazione di oggetti Google Protocol RPC Message come proprietà delle entità. Supponiamo di definire una sottoclasse Message: 

from protorpc import messages
... 
class Note(messages.Message):
    text = messages.StringField(1, required=True)
    when = messages.IntegerField(2)

Puoi archiviare gli oggetti Note in Datastore come valori delle proprietà dell'entità utilizzando l'API msgprop di NDB. 

from google.appengine.ext import ndb
from google.appengine.ext.ndb import msgprop
... 
class NoteStore(ndb.Model):
    note = msgprop.MessageProperty(Note, indexed_fields=['when'])
    name = ndb.StringProperty()
... 
my_note = Note(text='Excellent note', when=50)

ns = NoteStore(note=my_note, name='excellent')
key = ns.put()

new_notes = NoteStore.query(NoteStore.note.when >= 10).fetch()

Se vuoi eseguire query per i nomi dei campi, questi devono essere indicizzati. Puoi specificare un elenco di nomi di campi che verranno indicizzati con il parametro indexed_fields in MessageProperty.

MessageProperty supporta molte, ma non tutte, le opzioni della proprietà. Supporta:

  • name
  • repeated
  • required
  • default
  • choices
  • validator
  • verbose_name

Le proprietà dei messaggi non supportano l'opzione di proprietà indexed; non puoi indicizzare i valori Message. (Puoi indicizzare i campi di un messaggio come descritto sopra.)

Funzionano anche i messaggi nidificati (utilizzando MessageField): 

class Notebook(messages.Message):
    notes = messages.MessageField(Note, 1, repeated=True)
... 
class SignedStorableNotebook(ndb.Model):
    author = ndb.StringProperty()
    nb = msgprop.MessageProperty(
        Notebook, indexed_fields=['notes.text', 'notes.when'])

MessageProperty ha un'opzione di proprietà speciale, protocol, che specifica come l'oggetto messaggio viene serializzato in Datastore. I valori sono nomi di protocolli utilizzati dalla classe protorpc.remote.Protocols. I nomi dei protocolli supportati sono protobuf e protojson; il protocollo predefinito è protobuf.

msgprop definisce anche EnumProperty, un tipo di proprietà che può essere utilizzato per archiviare un valore protorpc.messages.Enum in un'entità. Esempio: 

class Color(messages.Enum):
    RED = 620
    GREEN = 495
    BLUE = 450
... 
class Part(ndb.Model):
    name = ndb.StringProperty()
    color = msgprop.EnumProperty(Color, required=True)
... 
p1 = Part(name='foo', color=Color.RED)
print p1.color  # prints "RED"

EnumProperty memorizza il valore come numero intero; infatti, EnumProperty è una sottoclasse di IntegerProperty. Ciò implica che puoi rinominare i valori enum senza dover modificare le entità già archiviate, ma non puoi rinumerarli.

EnumProperty supporta le seguenti opzioni di proprietà:

  • name
  • indexed
  • repeated
  • required
  • default
  • choices
  • validator
  • verbose_name

Informazioni sui modelli di entità NDB

Un modello di entità NDB può definire proprietà. Le proprietà delle entità sono un po' come i membri di dati delle classi Python, un modo strutturato per contenere i dati; sono anche un po' come i campi di uno schema di database.

Un'applicazione tipica definisce un modello dei dati definendo una classe che eredita da Model con alcuni attributi di classe di proprietà. Ad esempio,


from google.appengine.ext import ndb
... 
class Account(ndb.Model):
    username = ndb.StringProperty()
    userid = ndb.IntegerProperty()
    email = ndb.StringProperty()

In questo caso, username, userid e email sono proprietà di Account.

Esistono diversi altri tipi di proprietà. Alcuni sono utili per rappresentare date e orari e dispongono di comode funzionalità di aggiornamento automatico.

Un'applicazione può modificare il comportamento di una proprietà specificando le opzioni della proprietà. Queste possono semplificare la convalida, impostare i valori predefiniti o modificare l'indicizzazione delle query.

Un modello può avere proprietà più complesse. Le proprietà ripetute sono simili a elenchi. Le proprietà strutturate sono simili a oggetti. Le proprietà calcolate di sola lettura vengono definite tramite funzioni, il che semplifica la definizione di una proprietà in termini di una o più altre proprietà. I modelli Expando possono definire le proprietà in modo dinamico.