Referenz zu Entitätsattributen

Firestore im Datastore-Modus (Datastore) unterstützt eine Vielzahl von Datentypen für Attributwerte. Diese umfassen unter anderem:

• Ganzzahlen
• Gleitkommazahlen
• Strings
• Datumsangaben
• Binärdaten

Eine vollständige Liste der Typen finden Sie unter Attribute und Werttypen.

Attribute und Werttypen

Die mit einer Entität verknüpften Datenwerte bestehen aus einem oder mehreren Attributen. Jedes Attribut hat einen Namen und einen oder mehrere Werte. Ein Attribut kann Werte mit mehr als einem Typ haben und zwei Entitäten können Werte unterschiedlichen Typs für dasselbe Attribut haben. Attribute können indexiert oder nicht indexiert sein. Abfragen, die nach einem Attribut A sortieren oder filtern, ignorieren Entitäten, bei denen A nicht indexiert ist. Eine Entität kann höchstens 20.000 indexierte Attribute haben.

Die folgenden Werttypen werden unterstützt:

Wenn eine Abfrage ein Attribut mit Werten verschiedener Typen enthält, verwendet Datastore eine deterministische Sortierung anhand der internen Darstellungen:

1. Nullwerte
2. Festkommazahlen
   • Ganzzahlen
   • Datums- und Uhrzeitwerte
3. Boolesche Werte
4. Bytesequenzen
   • Unicode-String
   • Blobstore-Schlüssel
5. Gleitkommazahlen
6. Datastore-Schlüssel

Da lange Textstrings und lange Bytestrings nicht indexiert werden, ist keine Reihenfolge definiert.

Attributtypen

NDB unterstützt die folgenden Attributtypen:

Einige dieser Attribute haben das optionale Keyword-Argument compressed. Wenn das Attribut compressed=True enthält, werden die Daten mit gzip auf dem Laufwerk komprimiert. Dies beansprucht weniger Speicherplatz, benötigt aber CPU zum Codieren/Decodieren bei Schreib- und Lesevorgängen.

Sowohl die Komprimierung als auch die Dekomprimierung werden verzögert durchgeführt. Der Wert eines komprimierten Attributs wird erst beim ersten Zugriff dekomprimiert. Wird eine Entität, die einen komprimierten Attributwert enthält, gelesen und zurückgeschrieben, ohne auf das komprimierte Attribut zuzugreifen, wird es nicht dekomprimiert und auch nicht komprimiert. Der Kontext-Cache folgt ebenfalls diesem verzögerten Schema. Memcache speichert aber für komprimierte Attribute immer den komprimierten Wert.

Aufgrund der zusätzlichen CPU-Zeit, die für die Komprimierung benötigt wird, sollten komprimierte Attribute normalerweise nur dann verwendet werden, wenn die Daten zu groß sind, um ohne sie zu passen. Denken Sie daran, dass die gzip-basierte Komprimierung für Bilder und andere Mediendaten normalerweise keine Wirkung zeigt, da diese Formate bereits mit einem medienspezifischen Komprimierungsalgorithmus komprimiert wurden (z. B. JPEG bei Bildern).

Attributoptionen

Die meisten Attributtypen unterstützen einige Standardargumente. Das erste ist ein optionales Positionsargument, das den Datastore-Namen des Attributs angibt. Damit können Sie dem Attribut in Datastore einen anderen Namen geben als aus Sicht der Anwendung. Dies wird häufig zur Reduzierung des Speicherplatzes in Datastore eingesetzt, sodass Cloud Datastore abgekürzte Attributnamen verwenden kann, während Ihr Code längere, aussagekräftigere Codes verwendet. Beispiel:

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

Dies ist besonders für wiederkehrende Attribute, für die Sie viele Werte pro Entität erwarten, von Vorteil.

Darüber hinaus unterstützen die meisten Attributtypen die folgenden Schlüsselwortargumente:

Wiederkehrende Attribute

Jedes Attribut mit repeated=True wird zu einem wiederkehrenden Attribut . Das Attribut verwendet eine Liste mit Werten des zugrunde liegenden Typs anstelle eines einzelnen Werts. Der Wert eines mit IntegerProperty(repeated=True) definierten Attributs ist beispielsweise eine Liste ganzer Zahlen.

Der Datenspeicher kann für eine solche Eigenschaft mehrere Werte sehen. Für jeden Wert wird ein separater Indexeintrag erstellt. Dies wirkt sich auf die Abfragesemantik aus. Ein Beispiel finden Sie unter Wiederkehrende Attribute abfragen.

In diesem Beispiel wird ein wiederkehrendes Attribut verwendet:

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()

Dadurch wird eine Datenspeicherentität mit folgendem Inhalt erstellt:

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

Bei der Abfrage des Attributs tags erfüllt diese Entität eine Abfrage für 'python' oder 'ruby'.

Wenn Sie ein wiederkehrendes Attribut aktualisieren, können Sie ihm entweder eine neue Liste zuweisen oder die bestehende Liste ändern. Wenn Sie eine neue Liste zuweisen, werden die Typen der Listenelemente sofort validiert. Ungültige Elementtypen, z. B. die Zuweisung von [1, 2] zu art.tags oben, lösen eine Ausnahme aus. Wenn Sie die Liste verändern, wird die Änderung nicht sofort validiert. Stattdessen wird der Wert validiert, wenn Sie die Entität in Datastore schreiben.

Datastore behält die Reihenfolge der Listenelemente in einem wiederkehrenden Attribut bei. Die Reihenfolge ergibt für Sie also einen Sinn.

Datums- und Uhrzeitattribute

Zum Speichern von Datums- und Zeitwerten stehen drei Attributtypen zur Verfügung:

• DateProperty
• TimeProperty
• DateTimeProperty

Diese übernehmen Werte, die zu den entsprechenden Klassen (date, time, datetime) des Python-Standardmoduls datetime gehören. Die allgemeinste der drei ist DateTimeProperty, die sowohl ein Kalenderdatum als auch eine Uhrzeit angibt; die anderen sind gelegentlich für spezielle Zwecke nützlich, bei denen nur ein Datum (z. B. ein Geburtsdatum) oder nur eine Uhrzeit (z. B. eine Besprechungszeit) erforderlich ist. Aus technischen Gründen sind DateProperty und TimeProperty abgeleitete Klassen von DateTimeProperty. Sie sollten sich aber nicht auf diese Übernahmebeziehung verlassen (und beachten, dass sie sich von den Übernahmebeziehungen zwischen den vom Modul datetime selbst definierten zugrunde liegenden Klassen unterscheidet).

Hinweis: Die Uhrzeiten der App Engine werden immer in UTC (Coordinated Universal Time) ausgedrückt. Dies ist relevant, wenn Sie das aktuelle Datum oder die aktuelle Uhrzeit (datetime.datetime.now()) als Wert verwenden oder zwischen Datum/Uhrzeit-Objekten und POSIX-Zeitstempeln oder -Tupeln konvertieren. Es werden jedoch keine expliziten Zeitzoneninformationen in Datastore gespeichert. Wenn Sie also vorsichtig sind, können Sie diese verwenden, um Ortszeiten in jeder Zeitzone darzustellen, wenn Sie die aktuelle Zeit oder die Konvertierungen verwenden.

Für jedes dieser Attribute gibt es zwei zusätzliche boolesche Schlüsselwortoptionen:

Diese Optionen können nicht mit repeated=True kombiniert werden. Beide sind standardmäßig auf False gesetzt. Wenn beide auf True gesetzt sind, hat auto_now Vorrang. Der Wert eines Attributs kann mit auto_now_add=True überschrieben werden, aber nicht für eines mit auto_now=True. Der automatische Wert wird erst generiert, wenn die Entität geschrieben wird. Das bedeutet, dass diese Optionen keine dynamischen Standardwerte bieten. (Diese Details unterscheiden sich von der alten DB-API.)

Hinweis: Wenn eine Transaktion, die ein Attribut mit auto_now_add=True schreibt, fehlschlägt und später wiederholt wird, wird derselbe Zeitwert wie beim ursprünglichen Versuch verwendet, anstatt ihn auf den Zeitpunkt der Wiederholung zu aktualisieren. Wenn die Transaktion dauerhaft fehlschlägt, wird der Wert des Attributs weiterhin in der im Arbeitsspeicher gespeicherten Kopie der Entität festgelegt.

Strukturierte Attribute

Sie können die Attribute eines Modells strukturieren. Beispielsweise können Sie eine Modellklasse "Contact" definieren, die eine Liste von Adressen mit jeweils interner Struktur enthält. Mit strukturierten Attributen vom Typ StructuredProperty ist dies möglich. Beispiel:

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()

Dadurch wird eine einzelne Datenspeicherentität mit den folgenden Eigenschaften erstellt:

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'

Das Zurücklesen einer solchen Entität rekonstruiert exakt die ursprüngliche Entität Contact. Obwohl die Address-Instanzen mit derselben Syntax wie für Modellklassen definiert werden, sind sie keine vollwertigen Entitäten. Sie haben keine eigenen Schlüssel in Datastore. Sie können nicht unabhängig von der Entität Contact abgerufen werden, zu der sie gehören. Eine Anwendung kann jedoch die Werte ihrer einzelnen Felder abfragen; siehe Nach Werten für strukturierte Attribute filtern. address.type, address.street und address.city werden aus Sicht von Datastore als parallele Arrays angesehen, aber die NDB-Bibliothek blendet diesen Aspekt aus und erstellt die entsprechende Liste von Address-Instanzen.

Sie können die üblichen Attributoptionen für strukturierte Attribute angeben (außer indexed). Der Datastore-Name ist in diesem Fall das zweite Positionsargument (das erste ist die Modellklasse, die zum Definieren der Unterstruktur verwendet wird).

Wenn Sie die internen Attribute einer Unterstruktur nicht abfragen müssen, können Sie stattdessen ein lokales strukturiertes Attribut (LocalStructuredProperty) verwenden. Wenn Sie im obigen Beispiel StructuredProperty durch LocalStructuredProperty ersetzen, ist das Verhalten des Python-Codes identisch, aber Datastore sieht nur ein undurchsichtiges Blob für jede Adresse. Die im Beispiel erstellte Entität guido würde so gespeichert: name = 'Guido' adresse = <undurchsichtiger Blob für {'type': 'home', 'city': 'Amsterdam'}> address = <undurchsichtiger Blob für {"type": "work", "city": "SF", "street": "Speer St"}>

Die Entität wird korrekt zurückgelesen. Da Attribute dieses Typs immer nicht indexiert sind, können Sie keine Adresswerte abfragen.

Hinweis:: Ein StructuredProperty mit einem verschachtelten Attribut unterstützt nur eine einzige Ebene mit wiederkehrenden Attributen, unabhängig davon, ob es strukturiert ist. Das StructuredProperty oder das verschachtelte Attribut kann wiederholt werden, aber nicht beide. Eine Problemumgehung ist die Verwendung von LocalStructuredProperty, das diese Einschränkung nicht aufweist, aber keine Abfragen der zugehörigen Attributwerte zulässt.

Berechnete Attribute

Berechnete Attribute (ComputedProperty) sind schreibgeschützte Attribute, deren Wert aus anderen Attributwerten durch eine von der Anwendung bereitgestellte Funktion berechnet wird. Beachten Sie, dass ein berechnetes Attribut nur die Typen unterstützt, die von generischen Attributen unterstützt werden. Der berechnete Wert wird in Datastore geschrieben, sodass er abgefragt und im Datastore-Betrachter angezeigt werden kann. Der gespeicherte Wert wird jedoch ignoriert, wenn die Entität aus Datastore zurückgelesen wird. Stattdessen wird der Wert neu berechnet, indem die Funktion immer dann aufgerufen wird, wenn der Wert angefordert wird. Beispiel:

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

entity = SomeEntity(name='Nick')
entity.put()

So wird eine Entität mit den folgenden Attributwerten gespeichert:

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

Wenn wir den Namen in "Nickie" ändern und nach dem Wert von name_lower fragen, wird "nickie" zurückgegeben:

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

Hinweis: Verwenden Sie ComputedProperty, wenn die Anwendung den berechneten Wert abfragt. Wenn Sie nur die abgeleitete Version im Python-Code verwenden möchten, definieren Sie eine reguläre Methode oder verwenden Sie die integrierte Funktion @property von Python.

Hinweis:: Wenn Sie ein Modell erstellen, ohne manuell einen Schlüssel anzugeben, und stattdessen Datastore zum automatischen Generieren der Entitäts-ID verwenden, kann ein ComputedProperty das ID-Feld beim ersten put()-Aufruf nicht lesen. Dies liegt daran, dass das Feld berechnet wird, bevor die ID generiert wird. Wenn Sie ein ComputedProperty benötigen, das die ID der Entität verwendet, können Sie mit der Methode allocate_ids eine ID und einen Schlüssel für das Erstellen der Entität generieren. Mit dem ComputedProperty kann dann beim ersten put()-Aufruf auf diese ID verwiesen werden.

Google Protocol RPC – Nachrichtenattribute

Die Google Protocol RPC-Bibliothek verwendet Message-Objekte für strukturierte Daten. Sie können RPC-Anfragen, -Antworten oder andere Dinge darstellen. NDB bietet eine API zum Speichern der Message-Objekte von Google Protocol RPC als Entitätsattribute. Angenommen, Sie definieren eine Message - Unterklasse:

from protorpc import messages

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

Sie können Note-Objekte in Datastore als Entitätsattribute speichern, indem Sie die msgprop API von NDB verwenden.

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()

Wenn Sie Feldnamen abfragen möchten, müssen diese indexiert werden. Sie können eine Liste mit Feldnamen angeben, die mit dem Parameter indexed_fields bis MessageProperty indexiert werden.

MessageProperty unterstützt viele, aber nicht alle Attributoptionen. Unterstützt werden:

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

Nachrichtenattribute unterstützen die Attributoption indexed nicht. Sie können keine Message-Werte indexieren. (Sie können Felder einer Nachricht wie oben beschrieben indexieren.)

Verschachtelte Nachrichten (mit MessageField) funktionieren auch:

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 hat die spezielle Attributoption protocol, die angibt, wie das Nachrichtenobjekt in Datastore serialisiert wird. Die Werte sind Protokollnamen, die von der Klasse protorpc.remote.Protocols verwendet werden. Unterstützte Protokollnamen sind protobuf und protojson; der Standardwert ist protobuf.

msgprop definiert auch EnumProperty, einen Attributtyp, der zum Speichern eines protorpc.messages.Enum-Werts in einer Entität verwendet werden kann. Beispiel:

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 speichert den Wert als Ganzzahl. Tatsächlich ist EnumProperty eine abgeleitete Klasse von IntegerProperty. Dies bedeutet, dass Sie Ihre Enum-Werte umbenennen können, ohne bereits gespeicherte Entitäten ändern zu müssen. Sie können sie jedoch nicht neu nummerieren.

EnumProperty unterstützt die folgenden Attributoptionen:

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

Weitere Informationen zu NDB-Entitätsmodellen

Ein NDB-Entitätsmodell kann Attribute definieren. Entitätsattribute sind ungefähr wie Datenelemente bei Python-Klassen, eine strukturierte Methode zum Speichern von Daten; sie ähneln auch Feldern in einem Datenbankschema.

Eine typische Anwendung definiert ein Datenmodell, indem sie eine Klasse definiert, die von Model mit einigen Attributen der Attributklasse übernimmt. Beispiel:

from google.appengine.ext import ndb

class Account(ndb.Model):
    username = ndb.StringProperty()
    userid = ndb.IntegerProperty()
    email = ndb.StringProperty()

Hier sind username, userid, und email Attribute von Account.

Es gibt mehrere andere Attributtypen. Einige eignen sich gut für die Darstellung von Daten und Zeiten und haben praktische automatische Updatefunktionen.

In einer Anwendung kann das Verhalten eines Attributs angepasst werden. Dazu müssen Optionen für das Attribut festgelegt werden. Diese können die Validierung vereinfachen, Standardwerte bestimmen oder die Indexierung von Abfragen ändern.

Ein Modell kann komplexe Attribute haben. Wiederkehrende Attribute sind listenähnlich. Strukturierte Attribute sind objektähnlich. Schreibgeschützte berechnete Attribute werden über Funktionen definiert; so kann ein Attribut in Bezug auf eine oder mehrere andere Attribute mühelos definiert werden. Expando-Modelle können Attribute dynamisch definieren.