NDB-Funktionen

Funktionen

ndb.add_flow_exception(exc)
Gibt an, dass eine Ausnahme nicht protokolliert werden soll, sondern einfach Teil des normalen Programmablaufs ist. (Normalerweise wird beim Auslösen einer Ausnahme eine Warnmeldung in die Logs der Anwendung geschrieben.)

Argumente

exc
Ausnahmeklasse, die nicht protokolliert werden soll.

Standardmäßig werden die folgenden Ausnahmen nicht protokolliert:

  • webob.exc.HTTPException (und abgeleitete Klassen)
  • ndb.Rollback
ndb.delete_multi(keys, **ctx_options)
Löscht Entitäten, die durch die übergebene Schlüsselsequenz identifiziert wurden.

Argumente

keys
Reihenfolge der keys
**ctx_options
Kontextoptionen
ndb.delete_multi_async(keys, **ctx_options)
Löscht asynchron Entitäten, die durch die übergebene Schlüsselsequenz identifiziert wurden.

Argumente

keys
Reihenfolge der keys
**ctx_options
Kontextoptionen

Gibt eine Liste von Future-Objekten zurück. Alle Future-Objekte liefern als Ergebnis None.

ndb.get_multi(keys, **ctx_options)
Ruft Entitäten ab, die durch die übergebene Schlüsselsequenz identifiziert wurden.

Argumente

keys
Reihenfolge der keys
**ctx_options
Kontextoptionen

Liefert eine Liste. Jedes Listenelement ist entweder eine Modellinstanz oder None, wenn der Schlüssel nicht gefunden wurde.

ndb.get_multi_async(keys, **ctx_options)
Ruft asynchron Entitäten ab, die durch die übergebene Schlüsselsequenz identifiziert wurden.

Argumente

keys
Reihenfolge der keys
**ctx_options
Kontextoptionen

Gibt eine Liste von Future-Objekten zurück. Alle Future-Objekte liefern als Ergebnis eine Modellinstanz oder None, wenn der Schlüssel nicht gefunden wurde.

ndb.in_transaction()
Liefert einen booleschen Wert, der angibt, ob eine Transaktion gerade aktiv ist.
@ndb.non_transactional
@ndb.non_transactional(allow_existing=True)
Decorator, der dafür sorgt, dass eine Funktion außerhalb einer Transaktion ausgeführt wird.

Argumente:

allow_existing
Die Funktion wird unabhängig von der Transaktion ausgeführt, wenn True (der Standardwert) eingestellt ist und die dekorierte Funktion in einer Transaktion durch Code aufgerufen wird. Eine Ausnahme wird ausgelöst, wenn False und die dekorierte Funktion in einer Transaktion durch Code aufgerufen wird.
ndb.put_multi(entities, **ctx_options)
Speichert eine Abfolge von Modellinstanzen.

Argumente

Entitäten
Sequenz von Modellinstanzen
**ctx_options
Kontextoptionen

Liefert eine Liste mit den gespeicherten keys.

ndb.put_multi_async(entities, **ctx_options)
Speichert asynchron eine Sequenz von Modellinstanzen.

Argumente

Entitäten
Sequenz von Modellinstanzen
**ctx_options
Kontextoptionen

Gibt eine Liste von Future-Objekten zurück. Alle Future-Objekte liefern als Ergebnis einen gespeicherten key.

ndb.transaction(callback, **ctx_options)
Führt einen Callback in einer Transaktion aus.

Argumente

callback
Funktion oder Tasklet, die/das aufgerufen werden soll
**ctx_options
Transaktionsoptionen

Gibt zurück, was immer der Callback zurückgibt. Löst aus, was immer der Callback auslöst, oder eine TransactionFailedError-Ausnahme, wenn die Transaktion fehlschlägt.

Verwenden Sie zur Übergabe von Argumenten an eine Callback-Funktion ein Lambda. Beispiel:

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
ndb.transaction_async(callback, **ctx_options)
Führt einen Callback in einer Transaktion asynchron aus.

Argumente

callback
Funktion oder Tasklet, die/das aufgerufen werden soll
**ctx_options
Transaktionsoptionen

Gibt Future zurück. Future gibt zurück, was immer der Callback zurückgibt, oder löst aus, was immer der Callback auslöst – oder TransactionFailedError, wenn die Transaktion fehlschlägt.

Verwenden Sie zur Übergabe von Argumenten an eine Callback-Funktion ein Lambda. Beispiel:

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
@ndb.transactional
@ndb.transactional
Decorator, der dafür sorgt, dass eine Funktion in einer Transaktion automatisch ausgeführt wird.

Argumente:

Dieser Decorator kann Transaktionsoptionen aufweisen.

Kontextoptionen, Transaktionsoptionen

Mit Kontextoptionen können Sie bestimmte Datenspeichervorgänge mit unterschiedlichen Konfigurationen ausführen. Beispielsweise möchten Sie vielleicht die Leserichtlinie oder das RPC-Zeitlimit für einzelne Requests variieren. Übergeben Sie dazu Kontextoptionen an fast alle Vorgänge. Einige transaktionsbezogene Funktionen verwenden Transaktionsoptionen, die neben einer Reihe von Kontextoptionen zusätzliche Optionen enthalten.

Hier einige Beispiele, die Kontextoptionen verwenden. Sie können Folgendes verwenden, um das RPC-Zeitlimit beim Lesen einer Entität auf 1 Sekunde festzulegen:

key.get(deadline=1)

Sie können Folgendes verwenden, um das Memcache-Zeitlimit beim Schreiben einer Entität auf 30 Sekunden festzulegen:

ent.put(ndb_memcache_timeout=30)

Sie können Folgendes verwenden, um ein Element zu löschen, das zwischengespeichert wurde, und sein erneutes Laden zu erzwingen:

key.delete(use_datastore=False)

Die speziellen Schlüsselwortargumente options und config (die aus historischen Gründen identische Bedeutungen haben) erlauben es, mehrere Optionen als ein Konfigurationsobjekt anzugeben. Dies kann ein ndb.ContextOptions-Objekt oder (für die transaktionalen Funktionen und den Decorator) ein ndb.TransactionOptions-Objekt sein. key.get(options=ndb.ContextOptions(use_cache=True)) entspricht beispielsweise key.get(use_cache=True). Die in einem solchen Optionsobjekt festgelegten Optionen können durch Schlüsselwortparameter überschrieben werden.

Folgende Kontextoptionen sind verfügbar:

OptionTypBeschreibung
deadline float Datenspeicher-Aufrufzeitlimit, angegeben in Sekunden. (Standardmäßig wird der Aufruf nur durch das Request-Handler-Zeitlimit unterbrochen.)
read_policy ndb.EVENTUAL_CONSISTENCY Setzen Sie diesen Wert auf ndb.EVENTUAL_CONSISTENCY, wenn Sie lieber schneller Ergebnisse erhalten möchten, die möglicherweise nicht aktuell sind, anstatt zu warten, bis der Datenspeicher mit dem Anwenden der Änderungen auf alle gelieferten Ergebnisse fertig ist.
force_writes bool Gibt an, ob ein Schreib-Request erfolgreich sein soll, auch wenn die Anwendung schreibgeschützt ist. (Gilt nur für vom Nutzer gesteuerte schreibgeschützte Zeiträume.)
use_cache bool Gibt an, ob Entitäten im Prozesscache gespeichert werden sollen; überschreibt die Prozesscacherichtlinie für diesen Vorgang.
use_memcache bool Gibt an, ob Entitäten in Memcache gespeichert werden sollen; überschreibt die Memcache-Richtlinie für diesen Vorgang.
use_datastore bool Gibt an, ob Entitäten im Datenspeicher gespeichert werden sollen; überschreibt die Datenspeicherrichtlinie für diesen Vorgang.
memcache_timeout int Maximale Lebensdauer von Entitäten in Memcache; überschreibt die Richtlinie für das Memcache-Zeitlimit für diesen Vorgang.
max_memcache_items int Maximale Batchgröße für die Funktion zur automatischen Batchverarbeitung der Context-Memcache-Methoden. Bei der Standardgröße von max_memcache_items (100) werden beispielsweise bis zu 100 Memcache-Vorgänge in einem einzigen set_multi-Vorgang kombiniert.

Für einige transaktionsbezogene Funktionen stehen die folgenden Transaktionsoptionen zur Verfügung (zusammen mit den oben genannten übernommenen Kontextoptionen):

OptionTypBeschreibung
xg bool Lässt gruppenübergreifende (XG) Transaktionen zu. False standardmäßig.
propagation int

NDB bietet eingeschränkte Unterstützung für Transaktionen innerhalb von Transaktionen, die als "verschachtelte Transaktionen" bezeichnet werden.

Der Verteilungsparameter steuert, was passiert, wenn der Code versucht, eine verschachtelte Transaktion zu starten.

Die Verteilungsrichtlinie für @ndb.transactional ist standardmäßig ALLOWED.

Die Verteilungsrichtlinie für ndb.transaction() ist standardmäßig NESTED. Die NESTED-Richtlinie wird von NDB nicht unterstützt, daher löst Ihr Code eine BadRequestError-Ausnahme aus. NDB legt in diesem Fall einen nicht unterstützten Standardwert fest, sodass Programmierer explizit auf die Beschränkungen verschachtelter Transaktionen hingewiesen werden.

Der Verteilungsparameter kann einen der folgenden Werte haben:

ndb.TransactionOptions.NESTED
Die NESTED-Verteilungsrichtlinie führt für alle Änderungen an den äußeren und inneren Transaktionen zusammen das Commit durch, wenn das Commit der äußeren Richtlinie erfolgt. Wenn jedoch eine Ausnahme in der inneren Transaktion ausgelöst wird, werden alle dort vorgenommenen Änderungen verworfen. Die äußere Transaktion kann jedoch optional wiederhergestellt und fortgesetzt werden. Die NESTED-Richtlinie wird nicht unterstützt. Wenn Sie diese Richtlinie verwenden, löst Ihr Code eine BadRequestError-Ausnahme aus.
ndb.TransactionOptions.MANDATORY
Eine vorhandene Transaktion wird immer verteilt; wenn keine Transaktion vorhanden ist, wird eine Ausnahme ausgelöst. Wenn eine Funktion, die diese Richtlinie verwendet, eine Ausnahme auslöst, empfiehlt es sich wahrscheinlich nicht, die Ausnahme abzufangen und das Commit für die äußere Transaktion durchzuführen. Die Funktion hat die äußere Transaktion möglicherweise in einem fehlerhaften Zustand zurückgelassen.
ndb.TransactionOptions.ALLOWED
Wenn es eine vorhandene Transaktion gibt, wird sie verteilt. Wenn eine Funktion, die diese Richtlinie verwendet, eine Ausnahme auslöst, empfiehlt es sich wahrscheinlich nicht, die Ausnahme abzufangen und das Commit für die äußere Transaktion durchzuführen. Die Funktion hat die äußere Transaktion möglicherweise in einem fehlerhaften Zustand zurückgelassen.
ndb.TransactionOptions.INDEPENDENT
Es wird immer eine neue Transaktion verwendet und alle bestehenden Transaktionen werden "angehalten". Eine Funktion, die diese Richtlinie nutzt, gibt in der Regel keine Entitäten zurück, die in der neuen Transaktion gelesen werden, da die Entitäten mit der Transaktion des Aufrufers transaktional nicht konsistent sind.
retries int Gibt an, wie häufig Transaktionen nach einem Fehlschlagen automatisch wiederholt werden sollen. Null bedeutet einen Versuch, aber keine Wiederholung.

In manchen Fällen werden Optionen aufgrund von Caching ignoriert. Wenn Sie beispielsweise ein RPC-Zeitlimit für einen Lesevorgang angeben, der aus dem Kontextcache erfüllt wird, wird das Zeitlimit ignoriert. Andererseits lösen nicht erkannte Optionen TypeError aus.

Vorgänge mit verschiedenen Optionen werden zusammen gruppiert, wenn automatische Batchverarbeitung gilt. Wenn Sie beispielsweise put_async() verwenden, um einige Entitäten mit deadline = 5 und einige ohne Angabe eines Zeitlimits zu schreiben, und alle für automatische Batchverarbeitung geeignet sind, führt die automatische Batchverarbeitung zwei separate RPC-Aufrufe aus – einen für die Gruppe der Entitäten mit deadline = 5 und einen für die andere Gruppe – obwohl das Standard-RPC-Zeitlimit ebenfalls 5 ist! Dies gilt auch dann, wenn die angegebene Option für den RPC-Vorgang irrelevant ist (z. B. ndb_should_cache).