Arbeiten mit Elementen und Attributen in DynamoDB

In Amazon DynamoDB ist ein Element eine Sammlung von Attributen. Jedes Attribut verfügt über einen Namen und einen Wert. Ein Attributwert kann eine Skalarfunktion, eine Gruppe oder ein Dokumenttyp sein. Weitere Informationen finden Sie unter Amazon DynamoDB: Funktionsweise.

DynamoDB bietet vier Operationen für grundlegende Funktionen zum Erstellen, Lesen, Aktualisieren und Löschen (CRUD). Alle diese Operationen sind atomar.

Jede dieser Operationen erfordert, dass Sie den Primärschlüssel des Elements angeben, mit dem Sie arbeiten möchten. Um z. B. ein Element mit GetItem zu lesen, müssen Sie den Partitions- und den Sortierschlüssel (sofern zutreffend) für das Element angeben.

Zusätzlich zu den vier grundlegenden CRUD Operationen bietet DynamoDB auch die folgenden Funktionen:

Diese Batch-Operationen kombinieren mehrere CRUD Operationen in einer einzigen Anforderung. Darüber hinaus können die Stapeloperationen Elemente parallel lesen und schreiben, um Antwortlatenzen zu minimieren.

In diesem Abschnitt wird beschrieben, wie Sie diese Operationen verwenden. Außerdem wird auf verwandte Themen, wie z. B. bedingte Updates und unteilbare Zähler, eingegangen. Dieser Abschnitt enthält auch Beispielcode, der die verwendet AWS SDKs.

Lesen eines Elements

Verwenden Sie zum Lesen eines Elements von einer DynamoDB-Tabelle die Operation GetItem. Sie müssen den Namen der Tabelle sowie den Primärschlüssel des gewünschten Elements angeben.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}'

Eine GetItem-Anforderung führt standardmäßig einen Eventually Consistent-Lesevorgang durch. Sie können den Parameter ConsistentRead verwenden, um stattdessen einen Strongly Consistent-Lesevorgang anzufordern. (Dadurch werden zusätzliche Lesekapazitätseinheiten verbraucht, es wird jedoch die meiste up-to-date Version des Elements zurückgegeben.)

GetItem gibt alle Attribute des Elements zurück. Sie können einen Projektionsausdruck verwenden, um nur einige der Attribute zurückzugeben. Weitere Informationen finden Sie unter Verwenden von Projektionsausdrücken in DynamoDB.

Um die Anzahl der von GetItem verbrauchten Lesekapazitätseinheiten zurückzugeben, legen Sie den Parameter ReturnConsumedCapacity auf TOTAL fest.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --consistent-read \
    --projection-expression "Description, Price, RelatedItems" \
    --return-consumed-capacity TOTAL

Schreiben eines Elements

Zum Erstellen, Aktualisieren oder Löschen eines Elements in einer DynamoDB-Tabelle verwenden Sie eine der folgenden Operationen:

Für diese Operationen müssen Sie jeweils den Primärschlüssel vollständig und nicht nur teilweise angeben. Wenn eine Tabelle über einen zusammengesetzten Primärschlüssel (Partitions- und Sortierschlüssel) verfügt, müssen Sie einen Wert für den Partitionsschlüssel und einen Wert für den Sortierschlüssel angeben.

Um die Anzahl der von einer dieser Operationen verbrauchten Schreibkapazitätseinheiten zurückzugeben, legen Sie den Parameter ReturnConsumedCapacity auf einen der folgenden Werte fest:

PutItem

PutItem erstellt ein neues Element. Wenn ein Element mit demselben Schlüssel bereits in der Tabelle vorhanden ist, wird es durch das neue Element ersetzt.

aws dynamodb put-item \
    --table-name Thread \
    --item file://item.json

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"},
    "Message": {"S": "First post in this thread"},
    "LastPostedBy": {"S": "fred@example.com"},
    "LastPostDateTime": {"S": "201603190422"}
}

UpdateItem

Wenn kein Element mit dem angegebenen Schlüssel vorhanden ist, erstellt UpdateItem ein neues Element. Andernfalls werden die Attribute eines vorhandenen Elements geändert.

Sie verwenden einen Aktualisierungsausdruck, um die zu ändernden Attribute und deren neue Werte anzugeben. Weitere Informationen finden Sie unter Aktualisierungsausdrücke in DynamoDB verwenden.

Innerhalb des Aktualisierungsausdrucks verwenden Sie die Ausdrucksattributwerte als Platzhalter für die tatsächlichen Werte. Weitere Informationen finden Sie unter Verwenden von Ausdrucksattributwerten in DynamoDB.

aws dynamodb update-item \
    --table-name Thread \
    --key file://key.json \
    --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \
    --expression-attribute-values file://expression-attribute-values.json \
    --return-values ALL_NEW

Die Argumente für --key werden in der Datei key.json gespeichert:

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"}
}

Die Argumente für --expression-attribute-values werden in der Datei expression-attribute-values.json gespeichert:

{
    ":zero": {"N":"0"},
    ":lastpostedby": {"S":"barney@example.com"}
}

DeleteItem

DeleteItem löscht das Element mit dem angegebenen Schlüssel.

aws dynamodb delete-item \
    --table-name Thread \
    --key file://key.json

Rückgabewerte

In einigen Fällen soll DynamoDB bestimmte Attributwerte so zurückgeben, wie sie vor oder nach der Änderung erschienen. Die Operationen PutItem, UpdateItem und DeleteItem verfügen über einen Parameter ReturnValues, mit dem Sie Attributwerte zurückgeben können, bevor oder nachdem diese geändert wurden.

Der Standardwert für ReturnValues ist NONE. Dies bedeutet, dass DynamoDB keine Informationen über Attribute zurückgibt, die geändert wurden.

Im Folgenden sind die anderen gültigen Einstellungen fürReturnValues, geordnet nach DynamoDBAPI, aufgeführt.

PutItem

UpdateItem

Die häufigste Nutzung für UpdateItem ist das Aktualisieren eines vorhandenen Elements. UpdateItem führt eigentlich eine upsert-Operation aus. Dies bedeutet, dass das Element automatisch erstellt wird, wenn es noch nicht vorhanden ist.

DeleteItem

Batch-Vorgänge

Für Anwendungen, die mehrere Elemente lesen oder schreiben müssen, stellt DynamoDB die Operationen BatchGetItem und BatchWriteItem bereit. Mithilfe dieser Operationen können Sie die Anzahl der Netzläufe von Ihrer Anwendung für DynamoDB reduzieren. Außerdem führt DynamoDB die einzelnen Lese- oder Schreibvorgänge parallel aus. Ihre Anwendungen profitieren von dieser Parallelität, ohne Gleichzeitigkeit oder Threads verwalten zu müssen.

Die Stapeloperationen sind im Wesentlichen Wrapper für mehrere Lese- oder Schreibanforderungen. Wenn eine BatchGetItem-Anforderung z. B. fünf Elemente enthält, führt DynamoDB fünf GetItem-Operationen in Ihrem Namen aus. Wenn eine BatchWriteItem-Anforderung zwei PUT-Anforderungen und vier DELETE-Anforderungen enthält, führt DynamoDB zwei PutItem- und vier DeleteItem-Anforderungen aus.

Im Allgemeinen treten bei einer Stapeloperation nur Fehler auf, wenn alle im Stapel enthaltenen Anforderungen fehlschlagen. Angenommen, Sie führen eine BatchGetItem-Operation aus, doch bei einer der GetItem-Einzelanforderungen des Stapels tritt ein Fehler auf. In diesem Fall gibt BatchGetItem die Schlüssel und Daten der fehlgeschlagenen GetItem-Anforderung zurück. Die anderen GetItem-Anforderungen des Stapels sind davon nicht betroffen.

BatchGetItem

Eine einzelne BatchGetItem-Operation kann bis zu 10 individuelle GetItem-Anforderungen enthalten und bis zu 16 MB Daten abrufen. Darüber hinaus kann eine BatchGetItem-Operation Elemente aus mehreren Tabellen abrufen.

aws dynamodb batch-get-item \
    --request-items file://request-items.json

{
    "Thread": {
        "Keys": [
            {
                "ForumName":{"S": "Amazon DynamoDB"},
                "Subject":{"S": "DynamoDB Thread 1"}
            },
            {
                "ForumName":{"S": "Amazon S3"},
                "Subject":{"S": "S3 Thread 1"}
            }
        ],
        "ProjectionExpression":"ForumName, Subject, LastPostedDateTime, Replies"
    }
}

BatchWriteItem

Die BatchWriteItem-Operation kann bis zu 25 individuelle PutItem und DeleteItem-Anforderungen enthalten und bis zu 16 MB Daten schreiben. (Die maximale Größe eines einzelnen Elements beträgt 400 KB.) Darüber hinaus kann eine BatchWriteItem-Operation Elemente in mehreren Tabellen einfügen oder daraus löschen.

aws dynamodb batch-write-item \
    --request-items file://request-items.json

{
    "ProductCatalog": [
        {
            "PutRequest": {
                "Item": {
                    "Id": { "N": "601" },
                    "Description": { "S": "Snowboard" },
                    "QuantityOnHand": { "N": "5" },
                    "Price": { "N": "100" }
                }
            }
        },
        {
            "PutRequest": {
                "Item": {
                    "Id": { "N": "602" },
                    "Description": { "S": "Snow shovel" }
                }
            }
        }
    ]
}

Unteilbare Zähler

Mit der UpdateItem-Operation können Sie einen unteilbaren Zähler implementieren. Hierbei handelt es sich um ein numerisches Attribut, das erhöht wird, und zwar ohne Bedingung und ohne Konflikte mit anderen Schreibanforderungen. (Alle Schreibanforderungen werden in der Reihenfolge angewendet, in der sie empfangen wurden.) Mit einem unteilbaren Zähler sind die Updates nicht idempotent. Mit anderen Worten, der numerische Wert wird bei jedem Aufruf von UpdateItem erhöht oder verringert. Wenn der zur Aktualisierung des unteilbaren Zählers verwendete Inkrementwert positiv ist, kann dies zu einer Überzählung führen. Wenn der Inkrementwert negativ ist, kann dies zu einer Unterzählung führen.

Sie können einen unteilbaren Zähler verwenden, um die Anzahl der Besucher einer Website zu verfolgen. In diesem Fall erhöht Ihre Anwendung einen numerischen Wert, unabhängig vom aktuellen Wert. Wenn bei einer UpdateItem-Operation ein Fehler auftritt, kann die Anwendung die Operation einfach wiederholen. Das bringt zwar das Risiko mit sich, den Zähler zweimal zu aktualisieren, doch eine leichte Unter- oder Überzählung der Websitebesucher ist tolerierbar.

Ein unteilbarer Zähler ist nicht geeignet, wenn eine Überzählung oder Unterzählung nicht toleriert werden kann (z. B. in einer Bankanwendung). In diesem Fall ist es sicherer, ein bedingtes Update anstelle eines unteilbaren Zählers zu verwenden.

Weitere Informationen finden Sie unter Vergrößern und Verkleinern numerischer Attribute.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id": { "N": "601" }}' \
    --update-expression "SET Price = Price + :incr" \
    --expression-attribute-values '{":incr":{"N":"5"}}' \
    --return-values UPDATED_NEW

Bedingte Schreibvorgänge

Standardmäßig sind die DynamoDB-Schreibvorgänge (PutItem, UpdateItem, DeleteItem) bedingungslos: Jede dieser Operationen überschreibt ein vorhandenes Element, das den angegebenen Primärschlüssel umfasst.

DynamoDB unterstützt optional bedingte Schreibvorgänge für diese Operationen. Ein bedingter Schreibvorgang wird nur dann erfolgreich ausgeführt, wenn die Elementattribute eine oder mehrere erwartete Bedingungen erfüllen. Andernfalls wird ein Fehler zurückgegeben.

Bei bedingten Schreibvorgängen werden ihre Bedingungen mit der zuletzt aktualisierten Version des Elements verglichen. Beachten Sie, dass beim bedingten Schreiben kein vorheriges Element gefunden wird, wenn das Element zuvor nicht vorhanden war oder wenn der letzte erfolgreiche Vorgang für dieses Element ein Löschen war.

Bedingte Schreibvorgänge sind in vielen Situationen hilfreich. Eine PutItem-Operation soll beispielsweise nur erfolgreich abgeschlossen werden, wenn noch kein Element mit demselben Primärschlüssel vorhanden ist. Sie können eine UpdateItem-Operation auch daran hindern, ein Element zu ändern, wenn eines seiner Attribute einen bestimmten Wert aufweist.

Bedingte Schreibvorgänge sind hilfreich, wenn mehrere Benutzer versuchen, dasselbe Element zu ändern. Betrachten Sie das folgende Diagramm, in dem zwei Benutzer (Alice und Bob) mit demselben Element aus einer DynamoDB-Tabelle arbeiten:

Angenommen, Alice verwendet das AWS CLI , um das Price Attribut auf 8 zu aktualisieren.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --update-expression "SET Price = :newval" \
    --expression-attribute-values file://expression-attribute-values.json

Die Argumente für --expression-attribute-values werden in der Datei expression-attribute-values.json gespeichert:

{
    ":newval":{"N":"8"}
}

Angenommen, Bob erstellt später eine ähnliche UpdateItem-Anforderung, ändert den Price jedoch in 12. Für Bob sieht der Parameter --expression-attribute-values wie folgt aus:

{
    ":newval":{"N":"12"}
}

Bobs Anforderung wird erfolgreich ausgeführt, aber das Update, das Alice vorher vorgenommen hatte, geht verloren.

Für eine bedingte PutItem-, DeleteItem- oder UpdateItem-Anforderung geben Sie einen Bedingungsausdruck an. Ein Bedingungsausdruck ist eine Zeichenfolge, die Attributnamen, bedingte Operatoren und integrierte Funktionen enthält. Der gesamte Ausdruck muss mit True ausgewertet werden. Andernfalls schlägt die Operation fehl.

Betrachten Sie jetzt das folgende Diagramm, das zeigt, wie bedingte Schreibvorgänge verhindern würden, dass die von Alice vorgenommene Aktualisierung überschrieben wird:

Alice versucht zunächst, Price auf 8 zu aktualisieren, jedoch nur wenn der aktuelle Price 10 beträgt.

aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}' \
    --update-expression "SET Price = :newval" \
    --condition-expression "Price = :currval" \
    --expression-attribute-values file://expression-attribute-values.json

Die Argumente für --expression-attribute-values werden in der Datei expression-attribute-values.json gespeichert:

{
    ":newval":{"N":"8"},
    ":currval":{"N":"10"}
}

Das Update von Alice wird erfolgreich ausgeführt, da die Bedingung mit True ausgewertet wird.

Als Nächstes versucht Bob, den Price auf 12 zu aktualisieren, jedoch nur wenn der aktuelle Price 10 beträgt. Für Bob sieht der Parameter --expression-attribute-values wie folgt aus:

{
    ":newval":{"N":"12"},
    ":currval":{"N":"10"}
}

Da Alice den Price zuvor in 8 geändert hat, wird der Bedingungsausdruck mit False ausgewertet und Bobs Aktualisierung schlägt fehl.

Weitere Informationen finden Sie unter Beispiel für einen DynamoDB-Bedingungsausdruck CLI.

Idempotenz von bedingten Schreibvorgängen

Bedingte Schreibvorgänge können idempotent sein, wenn die bedingte Prüfung für dasselbe Attribut ausgeführt wird, das aktualisiert wird. Das bedeutet, dass DynamoDB den jeweiligen Schreibvorgang nur ausführt, wenn bestimmte Attributwerte in dem Element mit den zum Zeitpunkt der Anforderung erwarteten Werten übereinstimmen.

Angenommen, Sie erstellen eine UpdateItem-Anforderung, um den Price eines Elements um 3 zu erhöhen, jedoch nur wenn der Price aktuell 20 beträgt. Nachdem Sie die Anforderung senden und bevor Sie die Ergebnisse erhalten, tritt ein Netzwerkfehler auf und Sie wissen nicht, ob die Anforderung erfolgreich war. Da dieser bedingte Schreibvorgang idempotent ist, können Sie dieselbe UpdateItem-Anforderung wiederholen und DynamoDB aktualisiert das Element nur, wenn Price gegenwärtig 20 beträgt.

Von bedingten Schreibvorgängen verbrauchte Kapazitätseinheiten

Wenn ConditionExpression während eines bedingten Schreibvorgangs als falsch ausgewertet wird, verbraucht DynamoDB weiterhin Schreibkapazität aus der Tabelle. Die verbrauchte Menge hängt von der Größe des vorhandenen Elements ab (oder beträgt mindestens 1). Wenn beispielsweise ein vorhandenes Element 300 KB groß ist und das neue Element, das Sie erstellen oder aktualisieren möchten, 310 KB hat, entsprechen die verbrauchten Schreibkapazitätseinheiten 300, wenn die Bedingung fehlschlägt, und 310, wenn die Bedingung erfolgreich ist. Wenn es sich um ein neues Element handelt (kein vorhandenes Element), beträgt die verbrauchte Schreibkapazität 1, wenn die Bedingung fehlschlägt, und 310, wenn die Bedingung erfolgreich ist.

Tritt bei einem bedingten Schreibvorgang ein Fehler auf, wird eine ConditionalCheckFailedException zurückgegeben. In diesem Fall erhalten Sie in der Antwort keine Informationen über die verbrauchte Schreibkapazität.

Um die Anzahl von Schreibkapazitätseinheiten zurückzugeben, die während eines bedingten Schreibvorgangs verbraucht wurden, verwenden Sie den Parameter ReturnConsumedCapacity: