Arbeiten mit Elementen und Attributen

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 CRUD-Funktionalität (erstellen/lesen/aktualisieren/löschen). Alle diese Operationen sind atomar.

• PutItem – ein Element erstellen.

• GetItem – ein Element lesen.

• UpdateItem – ein Element aktualisieren.

• DeleteItem – ein Element löschen.

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 außerdem Folgendes:

• BatchGetItem – liest bis zu 100 Elemente aus einer oder mehreren Tabellen.

• BatchWriteItem – erstellt oder löscht bis zu 25 Elemente in einer oder mehreren Tabellen.

Diese Stapeloperationen 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 AWS SDKs verwendet.

Themen

• Lesen eines Elements
• Schreiben eines Elements
• Rückgabewerte
• Batch-Vorgänge
• Unteilbare Zähler
• Bedingte Schreibvorgänge
• Verwenden von Ausdrücken in DynamoDB
• Zeit bis zum Leben (TTL)
• Arbeiten mit Elementen: Java
• Arbeiten mit Elementen: .NET

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.

Beispiel

Das folgende AWS CLI Beispiel zeigt, wie ein Element aus der ProductCatalog Tabelle gelesen wird.

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

Anmerkung

Mit GetItem müssen Sie 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.

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 Projektionsausdrücke.

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

Beispiel

Das folgende Beispiel AWS Command Line Interface (AWS CLI) zeigt einige der optionalen GetItem Parameter.

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:

• PutItem

• UpdateItem

• DeleteItem

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:

• TOTAL – Gibt die Gesamtanzahl der verbrauchten Schreibkapazitätseinheiten zurück.

• INDEXES – Gibt die Gesamtzahl der verbrauchten Schreibkapazitätseinheiten mit Zwischensummen für die Tabelle und alle sekundären Indizes zurück, die vom Vorgang betroffen waren.

• NONE – Es werden keine Schreibkapazitätsdetails zurückgegeben. (Dies ist die Standardeinstellung.)

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.

Beispiel

Schreiben Sie ein neues Element in die Thread-Tabelle. Der Primärschlüssel für die Thread-Tabelle besteht aus ForumName (Partitionsschlüssel) und Subject (Sortierschlüssel).

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

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

{
    "ForumName": {"S": "Amazon DynamoDB"},
    "Subject": {"S": "New discussion thread"},
    "Message": {"S": "First post in this thread"},
    "LastPostedBy": {"S": "[e-mail]"},
    "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.

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

Beispiel

Ändern Sie verschiedene Attribute im Element Thread. Der optionale Parameter ReturnValues zeigt das Element so an, wie es nach der Aktualisierung dargestellt wird. Weitere Informationen finden Sie unter Rückgabewerte.

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":"[e-mail]"}
}

DeleteItem

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

Beispiel

Das folgende AWS CLI Beispiel zeigt, wie das Thread Element gelöscht wird.

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.

Nachfolgend sind die anderen gültigen Einstellungen für ReturnValues nach DynamoDB-API-Operation sortiert aufgeführt.

PutItem

• ReturnValues: ALL_OLD

  • Wenn Sie ein vorhandenes Element überschreiben, gibt ALL_OLD das gesamte Element so zurück, wie es vor dem Überschreiben dargestellt wurde.

  • Wenn Sie ein nicht vorhandenes Element schreiben, hat ALL_OLD keine Auswirkung.

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.

• ReturnValues: ALL_OLD

  • Wenn Sie ein vorhandenes Element aktualisieren, gibt ALL_OLD das gesamte Element so zurück, wie es vor dem Aktualisieren dargestellt wurde.

  • Wenn Sie ein nicht vorhandenes Element aktualisieren (Upsert-Operation), hat ALL_OLD keine Auswirkung.

• ReturnValues: ALL_NEW

  • Wenn Sie ein vorhandenes Element aktualisieren, gibt ALL_NEW das gesamte Element so zurück, wie es nach dem Aktualisieren dargestellt wird.

  • Wenn Sie ein nicht vorhandenes Element aktualisieren (Upsert-Operation), gibt ALL_NEW das gesamte Element zurück.

• ReturnValues: UPDATED_OLD

  • Wenn Sie ein vorhandenes Element aktualisieren, gibt UPDATED_OLD nur die aktualisierten Attribute so zurück, wie sie vor dem Aktualisieren dargestellt wurden.

  • Wenn Sie ein nicht vorhandenes Element aktualisieren (Upsert-Operation), hat UPDATED_OLD keine Auswirkung.

• ReturnValues: UPDATED_NEW

  • Wenn Sie ein vorhandenes Element aktualisieren, gibt UPDATED_NEW nur die betroffenen Attribute so zurück, wie sie nach dem Aktualisieren dargestellt werden.

  • Wenn Sie ein nicht vorhandenes Element aktualisieren (Upsert-Operation), gibt UPDATED_NEW nur die aktualisierten Attribute so zurück, wie sie nach dem Aktualisieren dargestellt werden.

DeleteItem

• ReturnValues: ALL_OLD

  • Wenn Sie ein vorhandenes Element löschen, gibt ALL_OLD das gesamte Element so zurück, wie es vor dem Löschen dargestellt wurde.

  • Wenn Sie ein nicht vorhandenes Element löschen, gibt ALL_OLD keine Daten zurück.

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.

Beispiel

Rufen Sie zwei Elemente aus der Thread-Tabelle mit einem Projektionsausdruck ab, um nur einige der Attribute zurückzugeben.

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

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

{
    "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.

Anmerkung

BatchWriteItem unterstützt keine UpdateItem-Anforderungen.

Beispiel

Fügen Sie der ProductCatalog-Tabelle zwei Elemente hinzu.

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

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

{
    "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.

Beispiel

Im folgenden AWS CLI Beispiel wird der Wert Price eines Produkts um 5 erhöht. In diesem Beispiel war bekannt, dass der Artikel existiert, bevor der Zähler aktualisiert wurde. Da UpdateItem nicht idempotent ist, steigt Price bei jedem Ausführen dieses Codes an.

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 Bedingungsausdrücke.

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.

Anmerkung

Schreibvorgänge verbrauchen nur Schreibkapazitätseinheiten. Sie belegen keine Lesekapazitätseinheiten.

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:

• TOTAL – Gibt die Gesamtanzahl der verbrauchten Schreibkapazitätseinheiten zurück.

• INDEXES – Gibt die Gesamtzahl der verbrauchten Schreibkapazitätseinheiten mit Zwischensummen für die Tabelle und alle sekundären Indizes zurück, die vom Vorgang betroffen waren.

• NONE – Es werden keine Schreibkapazitätsdetails zurückgegeben. (Dies ist die Standardeinstellung.)

Anmerkung

Im Unterschied zu einem globalen sekundären Index teilt ein lokaler sekundärer Index seine bereitgestellte Durchsatzkapazität mit der Tabelle. Die Lese- und Schreibaktivität auf einem lokalen sekundären Index verbraucht die bereitgestellte Durchsatzkapazität aus der Tabelle.