Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
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.
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.
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.
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:
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:
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:
Option
Typ
Beschreibung
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):
Option
Typ
Beschreibung
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).
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-09-04 (UTC)."],[[["\u003cp\u003eThis page documents the use of legacy bundled services and APIs, which are specifically designed for first-generation runtimes in the App Engine standard environment.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003endb\u003c/code\u003e API provides functions for managing entities, including operations like fetching, deleting, and storing entities, both synchronously and asynchronously.\u003c/p\u003e\n"],["\u003cp\u003eTransactions can be managed through the \u003ccode\u003endb\u003c/code\u003e API, allowing you to run operations in a transactional context, which can be done either directly or using decorators like \u003ccode\u003e@ndb.transactional\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eContext and transaction options are available to configure datastore operations, allowing customization of settings like deadlines, caching behavior, and read policies for individual requests.\u003c/p\u003e\n"],["\u003cp\u003eSpecific exceptions, such as \u003ccode\u003ewebob.exc.HTTPException\u003c/code\u003e and \u003ccode\u003endb.Rollback\u003c/code\u003e, are not logged by default, and users can specify additional exceptions to be excluded from logging via \u003ccode\u003endb.add_flow_exception\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# NDB Functions\n\nFunctions\n---------\n\n| This page describes how to use the legacy bundled services and APIs. This API can only run in first-generation runtimes in the App Engine standard environment. If you are updating to the App Engine Python 3 runtime, refer to the [migration guide](/appengine/migration-center/standard/migrate-to-second-gen/python-differences) to learn about your migration options for legacy bundled services.\n\nndb.add_flow_exception(exc)\n: Specify that an exception should *not* be logged, but is just part of\n normal program flow. (Normally, raising an exception writes a warning\n message to the application's logs.)\n\n **Arguments**\n\n exc\n\n : Exception class that should not be logged. By default, the following exceptions are not logged:\n\n - `webob.exc.HTTPException` (and its subclasses)\n - `ndb.Rollback`\n\nndb.delete_multi(keys, \\*\\*ctx_options)\n\n: Deletes entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\nndb.delete_multi_async(keys, \\*\\*ctx_options)\n\n: Asynchronously deletes entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list of [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n objects. Each future's result will be `None`.\n\nndb.get_multi(keys, \\*\\*ctx_options)\n\n: Fetches entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list. Each list item is either a\n [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instance or `None`\n if the key wasn't found.\n\nndb.get_multi_async(keys, \\*\\*ctx_options)\n\n: Asynchronously fetches entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list of [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n objects. Each future's result is a\n [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instance or `None`\n if the key wasn't found.\n\nndb.in_transaction()\n: Returns a Boolean indicating whether a transaction is currently active.\n\n@ndb.non_transactional \n\n@ndb.non_transactional(allow_existing=True)\n: Decorator to ensure that a function runs *outside* a transaction.\n\n **Arguments:**\n\n allow_existing\n : If `True` (the default) and if the decorated function\n is called by code in a transaction, the function runs independent\n of the transaction. If `False` and if the decorated function\n is called by code in a transaction, it raises an exception.\n\nndb.put_multi(entities, \\*\\*ctx_options)\n: Stores a sequence of [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances.\n\n **Arguments**\n\n entities\n : Sequence of [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list with the stored [keys](/appengine/docs/legacy/standard/python/ndb/keyclass).\n\nndb.put_multi_async(entities, \\*\\*ctx_options)\n: Asynchronously stores a sequence of\n [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances.\n\n **Arguments**\n\n entities\n : Sequence of [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list of [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n objects.\n Each future's result will be a stored [key](/appengine/docs/legacy/standard/python/ndb/keyclass).\n\nndb.transaction(callback, \\*\\*ctx_options)\n\n: Run a callback in a transaction. **Arguments**\n\n callback\n : Function or tasklet to be called\n\n \\*\\*ctx_options\n : [Transaction options](#context_options)\n\n Returns whatever callback returns.\n Raises whatever callback raises or a\n `TransactionFailedError` exception if the transaction fails.\n\n To pass arguments to a callback function, use a lambda. For example, \n\n ```python\n def my_callback(key, inc):\n ...\n\n transaction(lambda: my_callback(Key(...), 1))\n ```\n\nndb.transaction_async(callback, \\*\\*ctx_options)\n\n: Asynchronously run a callback in a transaction. **Arguments**\n\n callback\n : Function or tasklet to be called\n\n \\*\\*ctx_options\n : [Transaction options](#context_options)\n\n Returns a [Future](/appengine/docs/legacy/standard/python/ndb/futureclass).\n The future returns whatever callback returns, or\n raises whatever callback raises or a\n `TransactionFailedError` if the\n transaction fails.\n\n To pass arguments to a callback function, use a lambda. For example, \n\n ```python\n def my_callback(key, inc):\n ...\n\n transaction(lambda: my_callback(Key(...), 1))\n ```\n\n@ndb.transactional \n\n@ndb.transactional(\\*\\*ctx_options)\n\n: Decorator to make a function automatically run in a transaction. **Arguments:**\n\n This decorator can have [transaction options](#context_options).\n\nContext Options, Transaction Options\n------------------------------------\n\nContext options allow you to run specific datastore operations with different\nconfigurations. For example, you might want to vary the read policy\nor the RPC deadline for individual requests.\nYou can do this by passing *context options* to almost any operation.\nSome transaction-related functions take *transaction options*, which include additional options\non top of a set of context options.\n\nHere are a few examples using context options. To set the RPC deadline to 1 second when reading an entity,\nyou can use:\n\n```python\nkey.get(deadline=1)\n```\n\nTo set the memcache timeout to 30 seconds when writing an entity,\nyou can use:\n\n```python\nent.put(ndb_memcache_timeout=30)\n```\n\nTo delete an item that has been cached and force its reload, you can use:\n\n```python\nkey.delete(use_datastore=False)\n```\n\nThe special keyword arguments `options` and `config`\n(which have identical meanings for historical reasons) allow one to specify\nseveral options as a Configuration object. This can be an\n`ndb.ContextOptions` object or\n(for the transactional functions and decorator) an\n`ndb.TransactionOptions` object.\nFor example,\n`key.get(options=ndb.ContextOptions(use_cache=True))`\nis equivalent to\n`key.get(use_cache=True)`.\nThe options set in such an options object can be overridden by\nkeyword parameters.\n\nThe following **context options** are available:\n\nIn some cases, options are ignored because of caching.\nFor example, if you specify an RPC deadline for a read\noperation that is satisfied from the in-context cache,\nthe deadline is ignored.\nOn the other hand,\nunrecognized options cause `TypeError` to be raised.\n\nOperations with different options are grouped together when\nauto-batching applies. For example, if you use `put_async()`\nto write some entities with\n`deadline = 5`\nand some without specifying a deadline, and all are eligible for\nauto-batching, the auto-batcher will make two separate RPC\ncalls---one for the group of entities with\n`deadline = 5`\nand one for the other group---even though the default\nRPC deadline is also 5!\nThis applies even if the option specified is irrelevant to\nthe RPC operation (for example, `ndb_should_cache`)."]]
