Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Amazon QLDB-Treiber für Python **Wichtig** Hinweis zum Ende des Supports: Bestandskunden können Amazon QLDB bis zum Ende des Supports am 31.07.2025 nutzen. Weitere Informationen finden Sie unter [Migrieren eines Amazon QLDB-Ledgers zu Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL. Um mit Daten in Ihrem Ledger zu arbeiten, können Sie von Ihrer Python-Anwendung aus mithilfe eines bereitgestellten Treibers eine AWS Verbindung zu Amazon QLDB herstellen. In den folgenden Themen werden die ersten Schritte mit dem QLDB-Treiber für Python beschrieben. **Topics** + [ ## Ressourcen für Treiber ](#getting-started.python.resources) + [ ## Voraussetzungen ](#getting-started.python.prereqs) + [ ## Installation ](#getting-started.python.install) + [Schnellstart-Tutorial](driver-quickstart-python.md) + [Referenz zum Kochbuch](driver-cookbook-python.md) ## Ressourcen für Treiber Weitere Informationen zu den vom Python-Treiber unterstützten Funktionen finden Sie in den folgenden Ressourcen: + [API-Referenz: [3.x, 2.x](https://amazon-qldb-driver-python.readthedocs.io/en/latest/)](https://amazon-qldb-driver-python.readthedocs.io/en/v2.0.2/) + [Treiber-Quellcode () GitHub](https://github.com/awslabs/amazon-qldb-driver-python) + [Quellcode einer Beispielanwendung (GitHub)](https://github.com/aws-samples/amazon-qldb-dmv-sample-python) + [Beispiele für Amazon Ion-Code](ion.code-examples.md) ## Voraussetzungen Bevor Sie mit dem QLDB-Treiber für Python beginnen, müssen Sie Folgendes tun: 1. Folgen Sie den Anweisungen zur AWS Einrichtung unter. [Zugreifen auf Amazon QLDB](accessing.md) Diese umfasst die folgenden Funktionen: 1. Melde dich an für AWS. 1. Erstellen Sie einen Benutzer mit den entsprechenden QLDB-Berechtigungen. 1. Gewähren Sie programmatischen Zugriff für die Entwicklung. 1. Installieren Sie eine der folgenden Versionen von Python von der [Python-Downloadseite](https://www.python.org/downloads/): + **3.6 oder höher** — QLDB-Treiber für Python v3 + **3.4 oder höher** — QLDB-Treiber für Python v2 1. Richten Sie Ihre AWS Anmeldeinformationen und Ihren Standard ein. AWS-Region Anweisungen finden Sie in der AWS SDK für Python (Boto3) Dokumentation unter [Schnellstart](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#configuration). Eine vollständige Liste der verfügbaren Regionen finden Sie unter [Amazon QLDB-Endpunkte und Kontingente](https://docs.aws.amazon.com/general/latest/gr/qldb.html) in der. *Allgemeine AWS-Referenz* Als Nächstes können Sie die vollständige Tutorial-Beispielanwendung herunterladen — oder Sie können nur den Treiber in einem Python-Projekt installieren und kurze Codebeispiele ausführen. + Um den QLDB-Treiber und den AWS SDK für Python (Boto3) in einem vorhandenen Projekt zu installieren, fahren Sie mit fort. [Installation](#getting-started.python.install) + Informationen zum Einrichten eines Projekts und zur Ausführung von kurzen Codebeispielen, die grundlegende Datentransaktionen in einem Ledger demonstrieren, finden Sie unter. [Schnellstart-Tutorial](driver-quickstart-python.md) + Ausführlichere Beispiele für Daten- und Verwaltungs-API-Operationen in der vollständigen Beispielanwendung des Tutorials finden Sie unter. [Python-Tutorial](getting-started.python.tutorial.md) ## Installation QLDB unterstützt die folgenden Treiberversionen und ihre Python-Abhängigkeiten. **** | Treiberversion | Python-Version | Status | Datum der letzten Veröffentlichung | | --- | --- | --- | --- | | [2.x](https://pypi.org/project/pyqldb/2.0.2/) | 3.4 oder später | Produktionsfreigabe | 7. Mai 2020 | | [3.x](https://pypi.org/project/pyqldb/) | 3.6 oder später | Produktionsfreigabe | 28. Oktober 2021 | Um den QLDB-Treiber von PyPI mit `pip` (einem Paketmanager für Python) zu installieren, geben Sie in der Befehlszeile Folgendes ein. ------ #### [ 3.x ] ``` pip install pyqldb ``` ------ #### [ 2.x ] ``` pip install pyqldb==2.0.2 ``` ------ Durch die Installation des Treibers werden auch seine Abhängigkeiten installiert, einschließlich der Pakete [AWS SDK für Python (Boto3)](https://aws.amazon.com/sdk-for-python)und [Amazon Ion](ion.md). **Verwenden des Treibers zum Herstellen einer Verbindung mit einem Ledger** Dann können Sie den Treiber importieren und mit ihm eine Verbindung zu einem Ledger herstellen. Im folgenden Python-Codebeispiel wird gezeigt, wie eine Sitzung für einen angegebenen Ledger-Namen erstellt wird. ------ #### [ 3.x ] ``` from pyqldb.driver.qldb_driver import QldbDriver qldb_driver = QldbDriver(ledger_name='testLedger') for table in qldb_driver.list_tables(): print(table) ``` ------ #### [ 2.x ] ``` from pyqldb.driver.pooled_qldb_driver import PooledQldbDriver qldb_driver = PooledQldbDriver(ledger_name='testLedger') qldb_session = qldb_driver.get_session() for table in qldb_session.list_tables(): print(table) ``` ------ Kurze Codebeispiele für die Ausführung grundlegender Datentransaktionen in einem Ledger finden Sie unter[Referenz zum Kochbuch](driver-cookbook-python.md). # Amazon QLDB-Treiber für Python — Schnellstartanleitung **Wichtig** Hinweis zum Ende des Supports: Bestandskunden können Amazon QLDB bis zum Ende des Supports am 31.07.2025 nutzen. Weitere Informationen finden Sie unter [Migrieren eines Amazon QLDB-Ledgers zu Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL. In diesem Tutorial erfahren Sie, wie Sie eine einfache Anwendung mit der neuesten Version des Amazon QLDB-Treibers für Python einrichten. Dieses Handbuch enthält Schritte zum Installieren des Treibers und kurze Codebeispiele für grundlegende CRUD-Vorgänge (*Create, Read, Update und Delete*). Ausführlichere Beispiele, die diese Vorgänge in einer vollständigen Beispielanwendung veranschaulichen, finden Sie im [Python-Tutorial](getting-started.python.tutorial.md). **Topics** + [ ## Voraussetzungen ](#driver-quickstart-python.prereqs) + [ ## Schritt 1: Einrichten des Projekts ](#driver-quickstart-python.step-1) + [ ## Schritt 2: Initialisieren des Treibers ](#driver-quickstart-python.step-2) + [ ## Schritt 3: Erstellen einer Tabelle und eines Index ](#driver-quickstart-python.step-3) + [ ## Schritt 4: Einfügen eines Dokuments ](#driver-quickstart-python.step-4) + [ ## Schritt 5: Abfragen des Dokuments ](#driver-quickstart-python.step-5) + [ ## Schritt 6: Aktualisieren des Dokuments ](#driver-quickstart-python.step-6) + [ ## Ausführen der vollständigen Anwendung ](#driver-quickstart-python.complete) ## Voraussetzungen Bevor Sie beginnen, stellen Sie sicher, dass die folgende Voraussetzung erfüllt ist: 1. Füllen Sie den [Voraussetzungen](getting-started.python.md#getting-started.python.prereqs) für den Python-Treiber aus, falls Sie dies noch nicht getan haben. Dazu gehören die Registrierung für AWS, die Gewährung von programmatischem Zugriff für die Entwicklung und die Installation von Python Version 3.6 oder höher. 1. Ledger mit dem Namen `quick-start` erstellen. Informationen zum Erstellen eines Ledgers finden Sie unter [Grundlegende Operationen für Amazon QLDB-Ledger](ledger-management.basics.md) oder [Schritt 1: Erstellen Sie ein neues Hauptbuch](getting-started-step-1.md) in *Erste Schritte mit der Konsole*. ## Schritt 1: Einrichten des Projekts Richten Sie zunächst Ihr Python-Projekt ein. **Anmerkung** Wenn Sie eine IDE verwenden, die über Funktionen zur Automatisierung dieser Einrichtungsschritte verfügt, können Sie mit folgenden Schritten fortfahren[Schritt 2: Initialisieren des Treibers](#driver-quickstart-python.step-2). 1. Erstellen Sie einen Ordner für Ihre Anwendung. ``` $ mkdir myproject $ cd myproject ``` 1. Geben Sie den folgenden Befehl ein, um den QLDB-Treiber für Python von PyPI zu installieren. `pip` ``` $ pip install pyqldb ``` Durch die Installation des Treibers werden auch seine Abhängigkeiten installiert, einschließlich der Pakete [AWS SDK für Python (Boto3)](https://aws.amazon.com/sdk-for-net)und [Amazon Ion](ion.md). 1. Erstellen Sie eine neue Datei mit dem Namen `app.py`. Fügen Sie dann schrittweise die Codebeispiele in den folgenden Schritten hinzu, um einige grundlegende CRUD-Operationen auszuprobieren. Sie können das step-by-step Tutorial auch überspringen und stattdessen die [gesamte](#driver-quickstart-python.complete) Anwendung ausführen. ## Schritt 2: Initialisieren des Treibers Initialisieren Sie eine Instance des Treibers, der eine Verbindung mit dem Ledger `quick-start` herstellt. Fügen Sie nun folgenden Code in die Datei `app.py` ein: ``` from pyqldb.config.retry_config import RetryConfig from pyqldb.driver.qldb_driver import QldbDriver # Configure retry limit to 3 retry_config = RetryConfig(retry_limit=3) # Initialize the driver print("Initializing the driver") qldb_driver = QldbDriver("quick-start", retry_config=retry_config) ``` ## Schritt 3: Erstellen einer Tabelle und eines Index Im folgenden Codebeispiel wird veranschaulicht, wie `CREATE TABLE`- und `CREATE INDEX`-Anweisungen ausgeführt werden. Fügen Sie den folgenden Code hinzu, der eine Tabelle mit dem Namen `People` und einen Index für das Feld `lastName` in dieser Tabelle erstellt. [Indizes](ql-reference.create-index.md) sind erforderlich, um die Abfrageleistung zu optimieren und zur Begrenzung von Konfliktausnahmen bei der [optimistischen Parallelitätssteuerung (OCC) beizutragen](concurrency.md). ``` def create_table(transaction_executor): print("Creating a table") transaction_executor.execute_statement("Create TABLE People") def create_index(transaction_executor): print("Creating an index") transaction_executor.execute_statement("CREATE INDEX ON People(lastName)") # Create a table qldb_driver.execute_lambda(lambda executor: create_table(executor)) # Create an index on the table qldb_driver.execute_lambda(lambda executor: create_index(executor)) ``` ## Schritt 4: Einfügen eines Dokuments Im folgenden Codebeispiel wird veranschaulicht, wie eine `INSERT`-Anweisung ausgeführt wird. QLDB unterstützt die [PartiQL-Abfragesprache](ql-reference.md) (SQL-kompatibel) und das [Amazon Ion-Datenformat](ion.md) (Superset von JSON). Fügen Sie den folgenden Code hinzu, der ein Dokument in die Tabelle `People` einfügt. ``` def insert_documents(transaction_executor, arg_1): print("Inserting a document") transaction_executor.execute_statement("INSERT INTO People ?", arg_1) # Insert a document doc_1 = { 'firstName': "John", 'lastName': "Doe", 'age': 32, } qldb_driver.execute_lambda(lambda x: insert_documents(x, doc_1)) ``` In diesem Beispiel wird ein Fragezeichen (`?`) als Variablenplatzhalter verwendet, um die Dokumentinformationen an die Anweisung zu übergeben. Die `execute_statement` Methode unterstützt Werte sowohl in Amazon Ion-Typen als auch in systemeigenen Python-Typen. **Tipp** Um mehrere Dokumente mithilfe einer einzigen [INSERT](ql-reference.insert.md) Anweisung einzufügen, können Sie der Anweisung wie folgt einen Parameter vom Typ [list](driver-working-with-ion.md#driver-ion-list) übergeben. ``` # people is a list transaction_executor.execute_statement("INSERT INTO Person ?", people) ``` Sie setzen den Platzhalter für die Variable (`?`) nicht in doppelte spitze Klammern (`<<...>>`), wenn Sie eine Liste übergeben. *In manuellen PartiQL-Anweisungen bezeichnen doppelte spitze Klammern eine ungeordnete Sammlung, die als Tasche bezeichnet wird.* ## Schritt 5: Abfragen des Dokuments Im folgenden Codebeispiel wird veranschaulicht, wie eine `SELECT`-Anweisung ausgeführt wird. Fügen Sie den folgenden Code hinzu, der ein Dokument aus der Tabelle `People` abfragt. ``` def read_documents(transaction_executor): print("Querying the table") cursor = transaction_executor.execute_statement("SELECT * FROM People WHERE lastName = ?", 'Doe') for doc in cursor: print(doc["firstName"]) print(doc["lastName"]) print(doc["age"]) # Query the table qldb_driver.execute_lambda(lambda executor: read_documents(executor)) ``` ## Schritt 6: Aktualisieren des Dokuments Im folgenden Codebeispiel wird veranschaulicht, wie eine `UPDATE`-Anweisung ausgeführt wird. 1. Fügen Sie den folgenden Code hinzu, der ein Dokument in der `People` Tabelle aktualisiert, indem Sie auf aktualisieren. `age` `42` ``` def update_documents(transaction_executor, age, lastName): print("Updating the document") transaction_executor.execute_statement("UPDATE People SET age = ? WHERE lastName = ?", age, lastName) # Update the document age = 42 lastName = 'Doe' qldb_driver.execute_lambda(lambda x: update_documents(x, age, lastName)) ``` 1. Fragen Sie die Tabelle erneut ab, um den aktualisierten Wert zu sehen. ``` # Query the updated document qldb_driver.execute_lambda(lambda executor: read_documents(executor)) ``` 1. Um die Anwendung auszuführen, geben Sie den folgenden Befehl aus Ihrem Projektverzeichnis ein. ``` $ python app.py ``` ## Ausführen der vollständigen Anwendung Das folgende Codebeispiel ist die vollständige Version der `app.py` Anwendung. Anstatt die vorherigen Schritte einzeln auszuführen, können Sie dieses Codebeispiel auch kopieren und von Anfang bis Ende ausführen. Diese Anwendung demonstriert einige grundlegende CRUD-Operationen für den Ledger namens `quick-start`. **Anmerkung** Bevor Sie diesen Code ausführen, stellen Sie sicher, dass Sie noch keine aktive Tabelle mit dem Namen `People` im `quick-start`-Ledger besitzen. ``` from pyqldb.config.retry_config import RetryConfig from pyqldb.driver.qldb_driver import QldbDriver def create_table(transaction_executor): print("Creating a table") transaction_executor.execute_statement("CREATE TABLE People") def create_index(transaction_executor): print("Creating an index") transaction_executor.execute_statement("CREATE INDEX ON People(lastName)") def insert_documents(transaction_executor, arg_1): print("Inserting a document") transaction_executor.execute_statement("INSERT INTO People ?", arg_1) def read_documents(transaction_executor): print("Querying the table") cursor = transaction_executor.execute_statement("SELECT * FROM People WHERE lastName = ?", 'Doe') for doc in cursor: print(doc["firstName"]) print(doc["lastName"]) print(doc["age"]) def update_documents(transaction_executor, age, lastName): print("Updating the document") transaction_executor.execute_statement("UPDATE People SET age = ? WHERE lastName = ?", age, lastName) # Configure retry limit to 3 retry_config = RetryConfig(retry_limit=3) # Initialize the driver print("Initializing the driver") qldb_driver = QldbDriver("quick-start", retry_config=retry_config) # Create a table qldb_driver.execute_lambda(lambda executor: create_table(executor)) # Create an index on the table qldb_driver.execute_lambda(lambda executor: create_index(executor)) # Insert a document doc_1 = { 'firstName': "John", 'lastName': "Doe", 'age': 32, } qldb_driver.execute_lambda(lambda x: insert_documents(x, doc_1)) # Query the table qldb_driver.execute_lambda(lambda executor: read_documents(executor)) # Update the document age = 42 lastName = 'Doe' qldb_driver.execute_lambda(lambda x: update_documents(x, age, lastName)) # Query the table for the updated document qldb_driver.execute_lambda(lambda executor: read_documents(executor)) ``` Um die gesamte Anwendung auszuführen, geben Sie den folgenden Befehl aus Ihrem Projektverzeichnis ein. ``` $ python app.py ``` # Amazon QLDB-Treiber für Python — Kochbuch-Referenz **Wichtig** Hinweis zum Ende des Supports: Bestandskunden können Amazon QLDB bis zum Ende des Supports am 31.07.2025 nutzen. Weitere Informationen finden Sie unter [Migrieren eines Amazon QLDB-Ledgers zu Amazon](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/) Aurora PostgreSQL. Dieses Referenzhandbuch zeigt allgemeine Anwendungsfälle des Amazon QLDB-Treibers für Python. Es enthält Python-Codebeispiele, die zeigen, wie der Treiber verwendet wird, um grundlegende *Erstellungs-, Lese-, Aktualisierungs- und Löschvorgänge* (CRUD) auszuführen. Es enthält auch Codebeispiele für die Verarbeitung von Amazon Ion-Daten. Darüber hinaus werden in diesem Leitfaden bewährte Verfahren zur idempotenten Gestaltung von Transaktionen und zur Implementierung von Eindeutigkeitsbeschränkungen beschrieben. **Anmerkung** Gegebenenfalls haben einige Anwendungsfälle unterschiedliche Codebeispiele für jede unterstützte Hauptversion des QLDB-Treibers für Python. **Contents** + [ ## Der Treiber wird importiert ](#cookbook-python.importing) + [ ## Der Treiber wird instanziiert ](#cookbook-python.instantiating) + [ ## CRUD-Operationen ](#cookbook-python.crud) + [ ### Erstellen von Tabellen ](#cookbook-python.crud.creating-tables) + [ ### Erstellen von Indizes ](#cookbook-python.crud.creating-indexes) + [ ### Dokumente lesen ](#cookbook-python.crud.reading) + [ #### Verwenden von Abfrageparametern ](#cookbook-python.reading-using-params) + [ ### Dokumente werden eingefügt ](#cookbook-python.crud.inserting) + [ #### Einfügen mehrerer Dokumente in eine Anweisung ](#cookbook-python.crud.inserting.multiple) + [ ### Dokumente werden aktualisiert ](#cookbook-python.crud.updating) + [ ### Dokumente löschen ](#cookbook-python.crud.deleting) + [ ### Ausführung mehrerer Anweisungen in einer Transaktion ](#cookbook-python.crud.multi-statement) + [ ### Logik für Wiederholversuche ](#cookbook-python.crud.retry-logic) + [ ### Implementierung von Eindeutigkeitsbeschränkungen ](#cookbook-python.crud.uniqueness-constraints) + [ ## Arbeiten mit Amazon Ion ](#cookbook-python.ion) + [ ### Das Ion-Modul importieren ](#cookbook-python.ion.import) + [ ### Ion-Typen erstellen ](#cookbook-python.ion.creating-types) + [ ### Einen Ion-Binär-Dump abrufen ](#cookbook-python.ion.getting-binary) + [ ### Einen Ion-Textdump abrufen ](#cookbook-python.ion.getting-text) ## Der Treiber wird importiert Das folgende Codebeispiel importiert den Treiber. ------ #### [ 3.x ] ``` from pyqldb.driver.qldb_driver import QldbDriver import amazon.ion.simpleion as simpleion ``` ------ #### [ 2.x ] ``` from pyqldb.driver.pooled_qldb_driver import PooledQldbDriver import amazon.ion.simpleion as simpleion ``` ------ **Anmerkung** In diesem Beispiel wird auch das Amazon Ion-Paket (`amazon.ion.simpleion`) importiert. Sie benötigen dieses Paket, um Ion-Daten zu verarbeiten, wenn Sie einige Datenoperationen in dieser Referenz ausführen. Weitere Informationen hierzu finden Sie unter [Arbeiten mit Amazon Ion](#cookbook-python.ion). ## Der Treiber wird instanziiert Im folgenden Codebeispiel wird eine Instanz des Treibers erstellt, die mithilfe der Standardeinstellungen eine Verbindung zu einem angegebenen Ledger-Namen herstellt. ------ #### [ 3.x ] ``` qldb_driver = QldbDriver(ledger_name='vehicle-registration') ``` ------ #### [ 2.x ] ``` qldb_driver = PooledQldbDriver(ledger_name='vehicle-registration') ``` ------ ## CRUD-Operationen QLDB führt *Erstellungs-, Lese-, Aktualisierungs- und Löschvorgänge* (CRUD) als Teil einer Transaktion aus. **Warnung** Als bewährte Methode sollten Sie Ihre Schreibtransaktionen strikt idempotent gestalten. **Transaktionen idempotent machen** Wir empfehlen, Schreibtransaktionen idempotent zu machen, um unerwartete Nebenwirkungen bei Wiederholungsversuchen zu vermeiden. Eine Transaktion ist *idempotent*, wenn sie mehrfach ausgeführt werden kann und jedes Mal identische Ergebnisse liefert. Stellen Sie sich zum Beispiel eine Transaktion vor, die ein Dokument in eine Tabelle mit dem Namen einfügt. `Person` Bei der Transaktion sollte zunächst geprüft werden, ob das Dokument bereits in der Tabelle vorhanden ist. Ohne diese Prüfung könnte die Tabelle doppelte Dokumente enthalten. Nehmen wir an, dass QLDB die Transaktion auf der Serverseite erfolgreich festschreibt, der Client jedoch während des Wartens auf eine Antwort eine Zeitüberschreitung ausführt. Wenn die Transaktion nicht idempotent ist, könnte dasselbe Dokument bei einem erneuten Versuch mehrmals eingefügt werden. **Verwendung von Indizes, um vollständige Tabellenscans zu vermeiden** Es wird außerdem empfohlen, Anweisungen mit einer `WHERE` Prädikatklausel unter Verwendung eines *Gleichheitsoperators* für ein indiziertes Feld oder eine Dokument-ID auszuführen, z. B. oder. `WHERE indexedField = 123` `WHERE indexedField IN (456, 789)` Ohne diese indizierte Suche muss QLDB einen Tabellenscan durchführen, was zu Transaktions-Timeouts oder Konflikten mit *optimistischer Parallelitätskontrolle* (OCC) führen kann. Weitere Informationen zu OCC finden Sie unter [Amazon QLDB-Parallelitätsmodell](concurrency.md). **Implizit erstellte Transaktionen** [Die Methode [pyqldb.driver.qldb\$1driver.execute\$1lambda akzeptiert eine Lambda-Funktion, die eine Instanz von pyqldb.execution.executor.Executor](https://amazon-qldb-driver-python.readthedocs.io/en/stable/reference/driver/qldb_driver.html#pyqldb.driver.qldb_driver.QldbDriver.execute_lambda) empfängt, mit der Sie Anweisungen ausführen können.](https://amazon-qldb-driver-python.readthedocs.io/en/stable/reference/execution/executor.html#pyqldb.execution.executor.Executor) Die Instanz von umschließt eine `Executor` implizit erstellte Transaktion. Sie können Anweisungen innerhalb der Lambda-Funktion ausführen, indem Sie die Methode [execute\$1statement des Transaktionsausführers](https://amazon-qldb-driver-python.readthedocs.io/en/stable/reference/execution/executor.html#pyqldb.execution.executor.Executor.execute_statement) verwenden. Der Treiber schreibt die Transaktion implizit fest, wenn die Lambda-Funktion zurückkehrt. **Anmerkung** Die `execute_statement` Methode unterstützt sowohl Amazon Ion-Typen als auch native Python-Typen. Wenn Sie einen nativen Python-Typ als Argument an übergeben`execute_statement`, konvertiert der Treiber ihn mithilfe des `amazon.ion.simpleion` Moduls in einen Ion-Typ (vorausgesetzt, dass die Konvertierung für den angegebenen Python-Datentyp unterstützt wird). Die unterstützten Datentypen und Konvertierungsregeln finden Sie im [simpleion-Quellcode](https://ion-python.readthedocs.io/en/latest/_modules/amazon/ion/simpleion.html). In den folgenden Abschnitten wird gezeigt, wie grundlegende CRUD-Operationen ausgeführt, eine benutzerdefinierte Wiederholungslogik angegeben und Eindeutigkeitsbeschränkungen implementiert werden. **Contents** + [ ### Erstellen von Tabellen ](#cookbook-python.crud.creating-tables) + [ ### Erstellen von Indizes ](#cookbook-python.crud.creating-indexes) + [ ### Dokumente lesen ](#cookbook-python.crud.reading) + [ #### Verwenden von Abfrageparametern ](#cookbook-python.reading-using-params) + [ ### Dokumente werden eingefügt ](#cookbook-python.crud.inserting) + [ #### Einfügen mehrerer Dokumente in eine Anweisung ](#cookbook-python.crud.inserting.multiple) + [ ### Dokumente werden aktualisiert ](#cookbook-python.crud.updating) + [ ### Dokumente löschen ](#cookbook-python.crud.deleting) + [ ### Ausführung mehrerer Anweisungen in einer Transaktion ](#cookbook-python.crud.multi-statement) + [ ### Logik für Wiederholversuche ](#cookbook-python.crud.retry-logic) + [ ### Implementierung von Eindeutigkeitsbeschränkungen ](#cookbook-python.crud.uniqueness-constraints) ### Erstellen von Tabellen ``` def create_table(transaction_executor): transaction_executor.execute_statement("CREATE TABLE Person") qldb_driver.execute_lambda(lambda executor: create_table(executor)) ``` ### Erstellen von Indizes ``` def create_index(transaction_executor): transaction_executor.execute_statement("CREATE INDEX ON Person(GovId)") qldb_driver.execute_lambda(lambda executor: create_index(executor)) ``` ### Dokumente lesen ``` # Assumes that Person table has documents as follows: # { "GovId": "TOYENC486FH", "FirstName": "Brent" } def read_documents(transaction_executor): cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = 'TOYENC486FH'") for doc in cursor: print(doc["GovId"]) # prints TOYENC486FH print(doc["FirstName"]) # prints Brent qldb_driver.execute_lambda(lambda executor: read_documents(executor)) ``` #### Verwenden von Abfrageparametern Das folgende Codebeispiel verwendet einen systemeigenen Abfrageparameter. ``` cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ?", 'TOYENC486FH') ``` Das folgende Codebeispiel verwendet einen Abfrageparameter vom Typ Ion. ``` name = ion.loads('Brent') cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE FirstName = ?", name) ``` Das folgende Codebeispiel verwendet mehrere Abfrageparameter. ``` cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ? AND FirstName = ?", 'TOYENC486FH', "Brent") ``` Das folgende Codebeispiel verwendet eine Liste von Abfrageparametern. ``` gov_ids = ['TOYENC486FH','ROEE1','YH844'] cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId IN (?,?,?)", *gov_ids) ``` **Anmerkung** Wenn Sie eine Abfrage ohne indizierte Suche ausführen, wird ein vollständiger Tabellenscan aufgerufen. In diesem Beispiel empfehlen wir, einen [Index](ql-reference.create-index.md) für das `GovId` Feld zu verwenden, um die Leistung zu optimieren. Ohne aktivierten `GovId` Index können Abfragen eine höhere Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen. ### Dokumente werden eingefügt Im folgenden Codebeispiel werden systemeigene Datentypen eingefügt. ``` def insert_documents(transaction_executor, arg_1): # Check if doc with GovId:TOYENC486FH exists # This is critical to make this transaction idempotent cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ?", 'TOYENC486FH') # Check if there is any record in the cursor first_record = next(cursor, None) if first_record: # Record already exists, no need to insert pass else: transaction_executor.execute_statement("INSERT INTO Person ?", arg_1) doc_1 = { 'FirstName': "Brent", 'GovId': 'TOYENC486FH', } qldb_driver.execute_lambda(lambda executor: insert_documents(executor, doc_1)) ``` Im folgenden Codebeispiel werden Ion-Datentypen eingefügt. ``` def insert_documents(transaction_executor, arg_1): # Check if doc with GovId:TOYENC486FH exists # This is critical to make this transaction idempotent cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ?", 'TOYENC486FH') # Check if there is any record in the cursor first_record = next(cursor, None) if first_record: # Record already exists, no need to insert pass else: transaction_executor.execute_statement("INSERT INTO Person ?", arg_1) doc_1 = { 'FirstName': 'Brent', 'GovId': 'TOYENC486FH', } # create a sample Ion doc ion_doc_1 = simpleion.loads(simpleion.dumps(doc_1))) qldb_driver.execute_lambda(lambda executor: insert_documents(executor, ion_doc_1)) ``` Diese Transaktion fügt ein Dokument in die `Person` Tabelle ein. Vor dem Einfügen wird zunächst geprüft, ob das Dokument bereits in der Tabelle vorhanden ist. **Diese Prüfung macht die Transaktion ihrem Wesen nach idempotent.** Selbst wenn Sie diese Transaktion mehrmals ausführen, hat sie keine unbeabsichtigten Nebenwirkungen. **Anmerkung** In diesem Beispiel empfehlen wir, einen Index für das `GovId` Feld zu verwenden, um die Leistung zu optimieren. Ohne aktivierten `GovId` Index können Anweisungen eine längere Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen. #### Einfügen mehrerer Dokumente in eine Anweisung Um mehrere Dokumente mit einer einzigen [INSERT](ql-reference.insert.md) Anweisung einzufügen, können Sie der Anweisung wie folgt einen Parameter vom Typ [list](driver-working-with-ion.md#driver-ion-list) übergeben. ``` # people is a list transaction_executor.execute_statement("INSERT INTO Person ?", people) ``` Sie setzen den Platzhalter für die Variable (`?`) nicht in doppelte spitze Klammern (`<<...>>`), wenn Sie eine Liste übergeben. *In manuellen PartiQL-Anweisungen bezeichnen doppelte spitze Klammern eine ungeordnete Sammlung, die als Tasche bezeichnet wird.* ### Dokumente werden aktualisiert Das folgende Codebeispiel verwendet native Datentypen. ``` def update_documents(transaction_executor, gov_id, name): transaction_executor.execute_statement("UPDATE Person SET FirstName = ? WHERE GovId = ?", name, gov_id) gov_id = 'TOYENC486FH' name = 'John' qldb_driver.execute_lambda(lambda executor: update_documents(executor, gov_id, name)) ``` Das folgende Codebeispiel verwendet Ion-Datentypen. ``` def update_documents(transaction_executor, gov_id, name): transaction_executor.execute_statement("UPDATE Person SET FirstName = ? WHERE GovId = ?", name, gov_id) # Ion datatypes gov_id = simpleion.loads('TOYENC486FH') name = simpleion.loads('John') qldb_driver.execute_lambda(lambda executor: update_documents(executor, gov_id, name)) ``` **Anmerkung** In diesem Beispiel empfehlen wir, einen Index für das `GovId` Feld zu verwenden, um die Leistung zu optimieren. Ohne aktivierten `GovId` Index können Anweisungen eine längere Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen. ### Dokumente löschen Im folgenden Codebeispiel werden systemeigene Datentypen verwendet. ``` def delete_documents(transaction_executor, gov_id): cursor = transaction_executor.execute_statement("DELETE FROM Person WHERE GovId = ?", gov_id) gov_id = 'TOYENC486FH' qldb_driver.execute_lambda(lambda executor: delete_documents(executor, gov_id)) ``` Das folgende Codebeispiel verwendet Ion-Datentypen. ``` def delete_documents(transaction_executor, gov_id): cursor = transaction_executor.execute_statement("DELETE FROM Person WHERE GovId = ?", gov_id) # Ion datatypes gov_id = simpleion.loads('TOYENC486FH') qldb_driver.execute_lambda(lambda executor: delete_documents(executor, gov_id)) ``` **Anmerkung** In diesem Beispiel empfehlen wir, einen Index für das `GovId` Feld zu verwenden, um die Leistung zu optimieren. Ohne aktivierten `GovId` Index können Anweisungen eine längere Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen. ### Ausführung mehrerer Anweisungen in einer Transaktion ``` # This code snippet is intentionally trivial. In reality you wouldn't do this because you'd # set your UPDATE to filter on vin and insured, and check if you updated something or not. def do_insure_car(transaction_executor, vin): cursor = transaction_executor.execute_statement( "SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE", vin) first_record = next(cursor, None) if first_record: transaction_executor.execute_statement( "UPDATE Vehicles SET insured = TRUE WHERE vin = ?", vin) return True else: return False def insure_car(qldb_driver, vin_to_insure): return qldb_driver.execute_lambda( lambda executor: do_insure_car(executor, vin_to_insure)) ``` ### Logik für Wiederholversuche Die `execute_lambda` Treibermethode verfügt über einen integrierten Wiederholungsmechanismus, der die Transaktion wiederholt, wenn eine Ausnahme auftritt, die wiederholt werden kann (z. B. Timeouts oder OCC-Konflikte). ------ #### [ 3.x ] Die maximale Anzahl von Wiederholungsversuchen und die Backoff-Strategie sind konfigurierbar. Das Standardlimit für Wiederholungsversuche ist`4`, und die Standard-Backoff-Strategie ist [Exponential Backoff](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) and Jitter mit einer Basis von Millisekunden. `10` [Sie können die Wiederholungskonfiguration pro Treiberinstanz und auch pro Transaktion festlegen, indem Sie eine Instanz von pyqldb.config.retry\$1config verwenden. RetryConfig](https://amazon-qldb-driver-python.readthedocs.io/en/stable/reference/config/retry_config.html#pyqldb.config.retry_config.RetryConfig). Das folgende Codebeispiel spezifiziert die Wiederholungslogik mit einem benutzerdefinierten Wiederholungslimit und einer benutzerdefinierten Backoff-Strategie für eine Instanz des Treibers. ``` from pyqldb.config.retry_config import RetryConfig from pyqldb.driver.qldb_driver import QldbDriver # Configuring retry limit to 2 retry_config = RetryConfig(retry_limit=2) qldb_driver = QldbDriver("test-ledger", retry_config=retry_config) # Configuring a custom backoff which increases delay by 1s for each attempt. def custom_backoff(retry_attempt, error, transaction_id): return 1000 * retry_attempt retry_config_custom_backoff = RetryConfig(retry_limit=2, custom_backoff=custom_backoff) qldb_driver = QldbDriver("test-ledger", retry_config=retry_config_custom_backoff) ``` Das folgende Codebeispiel spezifiziert die Wiederholungslogik mit einem benutzerdefinierten Wiederholungslimit und einer benutzerdefinierten Backoff-Strategie für eine bestimmte Lambda-Ausführung. Diese Konfiguration für `execute_lambda` überschreibt die Wiederholungslogik, die für die Treiberinstanz festgelegt ist. ``` from pyqldb.config.retry_config import RetryConfig from pyqldb.driver.qldb_driver import QldbDriver # Configuring retry limit to 2 retry_config_1 = RetryConfig(retry_limit=4) qldb_driver = QldbDriver("test-ledger", retry_config=retry_config_1) # Configuring a custom backoff which increases delay by 1s for each attempt. def custom_backoff(retry_attempt, error, transaction_id): return 1000 * retry_attempt retry_config_2 = RetryConfig(retry_limit=2, custom_backoff=custom_backoff) # The config `retry_config_1` will be overriden by `retry_config_2` qldb_driver.execute_lambda(lambda txn: txn.execute_statement("CREATE TABLE Person"), retry_config_2) ``` ------ #### [ 2.x ] Die maximale Anzahl von Wiederholungsversuchen ist konfigurierbar. Sie können das Wiederholungslimit konfigurieren, indem Sie die `retry_limit` Eigenschaft bei der Initialisierung festlegen. `PooledQldbDriver` Das Standardlimit für Wiederholungsversuche ist. `4` ------ ### Implementierung von Eindeutigkeitsbeschränkungen QLDB unterstützt keine eindeutigen Indizes, aber Sie können dieses Verhalten in Ihrer Anwendung implementieren. Angenommen, Sie möchten eine Eindeutigkeitsbeschränkung für das `GovId` Feld in der Tabelle implementieren. `Person` Zu diesem Zweck können Sie eine Transaktion schreiben, die Folgendes tut: 1. Bestätigen Sie, dass die Tabelle keine vorhandenen Dokumente mit einem angegebenen Wert enthält`GovId`. 1. Fügt das Dokument ein, wenn die Assertion erfolgreich ist. Wenn eine konkurrierende Transaktion gleichzeitig die Assertion besteht, wird nur eine der Transaktionen erfolgreich festgeschrieben. Die andere Transaktion schlägt mit einer OCC-Konfliktausnahme fehl. Das folgende Codebeispiel zeigt, wie diese Eindeutigkeitsbeschränkungslogik implementiert wird. ``` def insert_documents(transaction_executor, gov_id, document): # Check if doc with GovId = gov_id exists cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ?", gov_id) # Check if there is any record in the cursor first_record = next(cursor, None) if first_record: # Record already exists, no need to insert pass else: transaction_executor.execute_statement("INSERT INTO Person ?", document) qldb_driver.execute_lambda(lambda executor: insert_documents(executor, gov_id, document)) ``` **Anmerkung** In diesem Beispiel empfehlen wir, einen Index für das `GovId` Feld zu verwenden, um die Leistung zu optimieren. Ohne aktivierten `GovId` Index können Anweisungen eine längere Latenz haben und auch zu OCC-Konfliktausnahmen oder Transaktions-Timeouts führen. ## Arbeiten mit Amazon Ion In den folgenden Abschnitten wird gezeigt, wie das Amazon Ion-Modul zur Verarbeitung von Ion-Daten verwendet wird. **Contents** + [ ### Das Ion-Modul importieren ](#cookbook-python.ion.import) + [ ### Ion-Typen erstellen ](#cookbook-python.ion.creating-types) + [ ### Einen Ion-Binär-Dump abrufen ](#cookbook-python.ion.getting-binary) + [ ### Einen Ion-Textdump abrufen ](#cookbook-python.ion.getting-text) ### Das Ion-Modul importieren ``` import amazon.ion.simpleion as simpleion ``` ### Ion-Typen erstellen Im folgenden Codebeispiel wird ein Ion-Objekt aus Ion-Text erstellt. ``` ion_text = '{GovId: "TOYENC486FH", FirstName: "Brent"}' ion_obj = simpleion.loads(ion_text) print(ion_obj['GovId']) # prints TOYENC486FH print(ion_obj['Name']) # prints Brent ``` Das folgende Codebeispiel erstellt ein Ion-Objekt aus einem Python`dict`. ``` a_dict = { 'GovId': 'TOYENC486FH', 'FirstName': "Brent" } ion_obj = simpleion.loads(simpleion.dumps(a_dict)) print(ion_obj['GovId']) # prints TOYENC486FH print(ion_obj['FirstName']) # prints Brent ``` ### Einen Ion-Binär-Dump abrufen ``` # ion_obj is an Ion struct print(simpleion.dumps(ion_obj)) # b'\xe0\x01\x00\xea\xee\x97\x81\x83\xde\x93\x87\xbe\x90\x85GovId\x89FirstName\xde\x94\x8a\x8bTOYENC486FH\x8b\x85Brent' ``` ### Einen Ion-Textdump abrufen ``` # ion_obj is an Ion struct print(simpleion.dumps(ion_obj, binary=False)) # prints $ion_1_0 {GovId:'TOYENC486FH',FirstName:"Brent"} ``` Weitere Informationen zur Arbeit mit Ion finden Sie in der [Amazon Ion-Dokumentation](http://amzn.github.io/ion-docs/) unter GitHub. Weitere Codebeispiele für die Arbeit mit Ion in QLDB finden Sie unter. [Arbeiten mit Amazon Ion-Datentypen in Amazon QLDB](driver-working-with-ion.md)