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:
- Nullwerte
- Festkommazahlen
- Ganzzahlen
- Datums- und Uhrzeitwerte
- Boolesche Werte
- Bytesequenzen
- Unicode-String
- Blobstore-Schlüssel
- Gleitkommazahlen
- Datastore-Schlüssel
Da lange Textstrings und lange Bytestrings nicht indexiert werden, ist keine Reihenfolge definiert.
Attributtypen
NDB unterstützt die folgenden Attributtypen:
Attributtyp | Beschreibung |
---|---|
IntegerProperty | Vorzeichenbehaftete 64-Bit-Ganzzahl |
FloatProperty | Gleitkommazahl mit doppelter Genauigkeit |
BooleanProperty | Boolesch |
StringProperty | Unicode-String, bis zu 1.500 Bytes, indexiert |
TextProperty | Unicode-String, unbegrenzte Länge, nicht indexiert |
BlobProperty | Nicht interpretierter Bytestring: Wenn Sie indexed=True festlegen, bis zu 1500 Byte, indexiert; wenn indexed gleich False (Standard) ist, unbegrenzte Länge, nicht indexiert.Optionales Keyword-Argument: compressed .
|
DateTimeProperty
| Datum und Uhrzeit (siehe Datums- und Uhrzeitattribute) |
DateProperty
| Datum (siehe Datums- und Uhrzeitattribute) |
TimeProperty
| Zeit (siehe Datums- und Uhrzeitattribute) |
GeoPtProperty
| Geografischer Ort. Dies ist ein ndb.GeoPt - Objekt.
Das Objekt hat die Attribute lat und lon , beide Gleitkommazahlen.
Sie können eines mit zwei Gleitkommazahlen wie ndb.GeoPt(52.37, 4.88) oder einem String ndb.GeoPt("52.37, 4.88") erstellen.
(Dies ist die gleiche Klasse wie
db.GeoPt )
|
KeyProperty | Datastore-Schlüssel Das optionale Keyword-Argument: kind=kind macht es erforderlich, dass Schlüssel, die diesem Attribut zugewiesen sind, immer die angegebene Art aufweisen. Kann ein String oder eine abgeleitete Modellklasse sein. |
BlobKeyProperty
| Blobstore-Schlüssel Entspricht BlobReferenceProperty in der alten Database API, aber der Attributwert ist BlobKey anstelle von BlobInfo . Mit BlobInfo(blobkey) können Sie BlobInfo erstellen. |
UserProperty | Nutzerobjekt. |
StructuredProperty
| Enthält eine Modellart innerhalb einer anderen, nach Wert (siehe Strukturierte Attribute) |
LocalStructuredProperty
| Entspricht dem Attribut StructuredProperty . Die Darstellung auf dem Laufwerk besteht aber aus einem intransparenten Blob und ist nicht indexiert (siehe Strukturierte Attribute).Optionales Keyword-Argument: compressed .
|
JsonProperty
| Der Wert ist ein Python-Objekt (z. B. eine Liste, ein Wörterbuch oder ein String), das mit dem json -Modul von Python serialisiert werden kann. Datastore speichert die JSON-Serialisierung als Blob. Wird standardmäßig nicht indexiert.Optionales Keyword-Argument: compressed .
|
PickleProperty
| Der Wert ist ein Python-Objekt (z. B. eine Liste, ein Wörterbuch oder ein String), das mit dem Pickle-Protokoll von Python serialisiert werden kann. Datastore speichert die Pickle-Serialisierung als Blob. Wird standardmäßig nicht indexiert. Optionales Keyword-Argument: compressed .
|
GenericProperty | Allgemeiner Wert Wird hauptsächlich von der Klasse Expando verwendet, ist aber auch explizit verwendbar. Der Typ kann
int , long ,
float , bool , str ,
unicode , datetime , Key ,
BlobKey , GeoPt , User oder
None sein.
|
ComputedProperty
| Wert, der von anderen Attributen durch eine benutzerdefinierte Funktion berechnet wird (siehe Berechnete Attribute) |
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:
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:
Argument | Typ | Standardeinstellung | Beschreibung |
---|---|---|---|
indexed | bool | Normalerweise True | Eigenschaft in die Datenspeicherindex einschließen; Wenn False , können Werte nicht abgefragt werden, aber Schreibvorgänge sind schneller. Nicht alle Property-Typen unterstützen die Indexierung. die Einstellung indexed bis True schlägt fehl.Nicht indexierte Attribute benötigen weniger Schreibvorgänge als indexierte Attribute. |
repeated | bool | False | Der Attributwert ist eine Python-Liste, die Werte des zugrunde liegenden Typs enthält (siehe Wiederkehrende Attribute). Kann nicht mit required=True oder default=True kombiniert werden.
|
required | bool | False | Für das Attribut muss ein Wert angegeben werden. |
default | Der zugrunde liegende Typ des Attributs | – | Standardwert des Attributs, wenn keiner explizit angegeben ist |
choices | Liste der Werte des zugrunde liegenden Typs | None | Optionale Liste zulässiger Werte |
validator | Funktion | None | Optionale Funktion, um den Wert zu validieren und möglicherweise zu erzwingen Wird mit Argumenten (prop, value) aufgerufen und sollte entweder den (möglicherweise erzwungenen) Wert zurückgeben oder eine Ausnahme auslösen. Durch erneutes Aufrufen der Funktion für einen erzwungenen Wert darf der Wert nicht weiter geändert werden.
Die Rückgabe von |
verbose_name | String | None
| Optionales HTML-Label zur Verwendung in Webformular-Frameworks wie jinja2 |
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:
...
Dadurch wird eine Datenspeicherentität mit folgendem Inhalt erstellt:
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:
Option | Beschreibung |
---|---|
auto_now_add
| Setzen Sie das Attribut auf das aktuelle Datum/die aktuelle Uhrzeit, wenn die Entität erstellt wird. Sie können dieses Attribut manuell überschreiben. Wenn die Entität aktualisiert wird, ändert sich das Attribut nicht. Verwenden Sie für dieses Verhalten auto_now .
|
auto_now
| Setzen Sie das Attribut auf das aktuelle Datum/die aktuelle Uhrzeit, wenn die Entität erstellt wird und wann immer sie aktualisiert wird. |
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:
...
...
Dadurch wird eine einzelne Datenspeicherentität mit den folgenden Eigenschaften erstellt:
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:
...
So wird eine Entität mit den folgenden Attributwerten gespeichert:
Wenn wir den Namen in "Nickie" ändern und nach dem Wert von name_lower
fragen, wird "nickie" zurückgegeben:
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:
...
Sie können Note
-Objekte in Datastore als Entitätsattribute speichern, indem Sie die msgprop
API von NDB verwenden.
...
...
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:
...
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:
...
...
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:
...
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.