Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# pilote Amazon QLDB pour Python
**Important**
Avis de fin de support : les clients existants pourront utiliser Amazon QLDB jusqu'à la fin du support le 31 juillet 2025. Pour plus de détails, consultez [Migrer un registre Amazon QLDB vers Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/).
Pour utiliser les données de votre registre, vous pouvez vous connecter à Amazon QLDB depuis votre application Python à l'aide d'un pilote fourni AWS . Les rubriques suivantes décrivent comment démarrer avec le pilote QLDB pour Python.
**Topics**
+ [Ressources pour les conducteurs](#getting-started.python.resources)
+ [Prérequis](#getting-started.python.prereqs)
+ [Installation](#getting-started.python.install)
+ [Tutoriel de démarrage rapide](driver-quickstart-python.md)
+ [Référence de livre de cuisine](driver-cookbook-python.md)
## Ressources pour les conducteurs
Pour plus d'informations sur les fonctionnalités prises en charge par le pilote Python, consultez les ressources suivantes :
+ [Référence d'API : [3.x, 2.x](https://amazon-qldb-driver-python.readthedocs.io/en/latest/)](https://amazon-qldb-driver-python.readthedocs.io/en/v2.0.2/)
+ [Code source du pilote (GitHub)](https://github.com/awslabs/amazon-qldb-driver-python)
+ [Exemple de code source d'application (GitHub)](https://github.com/aws-samples/amazon-qldb-dmv-sample-python)
+ [Exemples de code Amazon Ion](ion.code-examples.md)
## Prérequis
Avant de commencer à utiliser le pilote QLDB pour Python, vous devez effectuer les opérations suivantes :
1. Suivez les instructions AWS de configuration indiquées dans[Accès à Amazon QLDB](accessing.md). Cela inclut les éléments suivants :
1. Inscrivez-vous pour AWS.
1. Créez un utilisateur doté des autorisations QLDB appropriées.
1. Accordez un accès programmatique pour le développement.
1. Installez l'une des versions suivantes de Python depuis le site de [téléchargement de Python](https://www.python.org/downloads/) :
+ **3.6 ou version ultérieure** — pilote QLDB pour Python v3
+ **3.4 ou version ultérieure** — pilote QLDB pour Python v2
1. Configurez vos AWS informations d'identification et celles par défaut Région AWS. Pour obtenir des instructions, consultez [Quickstart](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#configuration) dans la AWS SDK pour Python (Boto3) documentation.
Pour obtenir la liste complète des régions disponibles, consultez la section [Points de terminaison et quotas Amazon QLDB](https://docs.aws.amazon.com/general/latest/gr/qldb.html) dans le. *Références générales AWS*
Ensuite, vous pouvez télécharger l'exemple complet du didacticiel, ou vous pouvez installer uniquement le pilote dans un projet Python et exécuter des exemples de code abrégé.
+ Pour installer le pilote QLDB et AWS SDK pour Python (Boto3) le dans un projet existant, passez à. [Installation](#getting-started.python.install)
+ Pour configurer un projet et exécuter des exemples de codes abrégés illustrant les transactions de données de base sur un registre, consultez le[Tutoriel de démarrage rapide](driver-quickstart-python.md).
+ Pour obtenir des exemples plus détaillés des opérations relatives aux données et aux API de gestion dans l'exemple d'application complet du didacticiel, consultez le[Tutoriel Python](getting-started.python.tutorial.md).
## Installation
QLDB prend en charge les versions de pilotes suivantes et leurs dépendances en Python.
****
| Versions du pilote | Version Python | Statut | Date de sortie la plus récente |
| --- | --- | --- | --- |
| [2. x](https://pypi.org/project/pyqldb/2.0.2/) | 3.4 ou version ultérieure | Communiqué de production | 7 mai 2020 |
| [3. x](https://pypi.org/project/pyqldb/) | 3.6 ou version ultérieure | Communiqué de production | 28 octobre 2021 |
Pour installer le pilote QLDB depuis PyPI à l'aide de `pip` (un gestionnaire de packages pour Python), entrez ce qui suit sur la ligne de commande.
------
#### [ 3.x ]
```
pip install pyqldb
```
------
#### [ 2.x ]
```
pip install pyqldb==2.0.2
```
------
L'installation du pilote installe également ses dépendances, notamment les packages [AWS SDK pour Python (Boto3)](https://aws.amazon.com/sdk-for-python)et [Amazon Ion](ion.md).
**Utiliser le pilote pour se connecter à un registre**
Vous pouvez ensuite importer le pilote et l'utiliser pour vous connecter à un registre. L'exemple de code Python suivant montre comment créer une session pour un nom de registre spécifié.
------
#### [ 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)
```
------
Pour des exemples de code abrégé expliquant comment exécuter des transactions de données de base sur un registre, consultez le[Référence de livre de cuisine](driver-cookbook-python.md).
# Pilote Amazon QLDB pour Python — Tutoriel de démarrage rapide
**Important**
Avis de fin de support : les clients existants pourront utiliser Amazon QLDB jusqu'à la fin du support le 31 juillet 2025. Pour plus de détails, consultez [Migrer un registre Amazon QLDB vers Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/).
Dans ce didacticiel, vous apprendrez à configurer une application simple à l'aide de la dernière version du pilote Amazon QLDB pour Python. Ce guide inclut les étapes d'installation du pilote et des exemples de code abrégé des opérations de base de *création, de lecture, de mise à jour et de suppression* (CRUD). Pour des exemples plus détaillés illustrant ces opérations dans un exemple complet d'application, consultez le[Tutoriel Python](getting-started.python.tutorial.md).
**Topics**
+ [Prérequis](#driver-quickstart-python.prereqs)
+ [Étape 1 : Configurer votre projet](#driver-quickstart-python.step-1)
+ [Étape 2 : Initialisation du pilote](#driver-quickstart-python.step-2)
+ [Étape 3 : Création d'une table et d'un index](#driver-quickstart-python.step-3)
+ [Étape 4 : Insérer un document](#driver-quickstart-python.step-4)
+ [Étape 5 : Interrogez le document](#driver-quickstart-python.step-5)
+ [Étape 6 : Mettre à jour le document](#driver-quickstart-python.step-6)
+ [Exécution de l'application complète](#driver-quickstart-python.complete)
## Prérequis
Avant de commencer, assurez-vous d'effectuer les opérations suivantes :
1. Complétez le driver [Prérequis](getting-started.python.md#getting-started.python.prereqs) for the Python, si ce n'est pas déjà fait. Cela inclut l'inscription AWS, l'octroi d'un accès programmatique pour le développement et l'installation de Python version 3.6 ou ultérieure.
1. Créez un registre nommé`quick-start`.
Pour savoir comment créer un registre, voir [Opérations de base pour les registres Amazon QLDB](ledger-management.basics.md) ou [Étape 1 : Création d'un nouveau registre](getting-started-step-1.md) dans *Commencer à utiliser la console*.
## Étape 1 : Configurer votre projet
Configurez d'abord votre projet Python.
**Note**
Si vous utilisez un IDE doté de fonctionnalités permettant d'automatiser ces étapes de configuration, vous pouvez passer à[Étape 2 : Initialisation du pilote](#driver-quickstart-python.step-2).
1. Créez un dossier pour votre application.
```
$ mkdir myproject
$ cd myproject
```
1. Pour installer le pilote QLDB pour Python à partir de PyPI, entrez la commande suivante. `pip`
```
$ pip install pyqldb
```
L'installation du pilote installe également ses dépendances, notamment les packages [AWS SDK pour Python (Boto3)](https://aws.amazon.com/sdk-for-net)et [Amazon Ion](ion.md).
1. Créez un nouveau fichier nommé `app.py`.
Ajoutez ensuite progressivement les exemples de code dans les étapes suivantes pour essayer certaines opérations CRUD de base. Vous pouvez également ignorer le step-by-step didacticiel et exécuter l'[application complète](#driver-quickstart-python.complete) à la place.
## Étape 2 : Initialisation du pilote
Initialisez une instance du pilote qui se connecte au registre nommé. `quick-start` Ajoutez le code suivant à votre `app.py` fichier.
```
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)
```
## Étape 3 : Création d'une table et d'un index
L'exemple de code suivant montre comment exécuter `CREATE TABLE` des `CREATE INDEX` instructions.
Ajoutez le code suivant qui crée une table nommée `People` et un index pour le `lastName` champ de cette table. Les [index](ql-reference.create-index.md) sont nécessaires pour optimiser les performances des requêtes et aider à limiter les exceptions de conflit liées au [contrôle optimiste de la simultanéité (OCC).](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))
```
## Étape 4 : Insérer un document
L'exemple de code suivant montre comment exécuter une `INSERT` instruction. QLDB prend en charge le langage de requête [partiQL](ql-reference.md) (compatible SQL) et le format de données [Amazon](ion.md) Ion (surensemble de JSON).
Ajoutez le code suivant qui insère un document dans le `People` tableau.
```
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))
```
Cet exemple utilise un point d'interrogation (`?`) comme espace réservé aux variables pour transmettre les informations du document à l'instruction. La `execute_statement` méthode prend en charge les valeurs des types Amazon Ion et des types natifs Python.
**Astuce**
Pour insérer plusieurs documents en utilisant une seule [INSERT](ql-reference.insert.md) instruction, vous pouvez transmettre un paramètre de type [list](driver-working-with-ion.md#driver-ion-list) à l'instruction comme suit.
```
# people is a list
transaction_executor.execute_statement("INSERT INTO Person ?", people)
```
Vous ne placez pas la variable placeholder (`?`) entre crochets (`<<...>>`) lorsque vous transmettez une liste. *Dans les instructions partiQL manuelles, les crochets à double angle indiquent une collection non ordonnée appelée sac.*
## Étape 5 : Interrogez le document
L'exemple de code suivant montre comment exécuter une `SELECT` instruction.
Ajoutez le code suivant qui interroge un document à partir de la `People` table.
```
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))
```
## Étape 6 : Mettre à jour le document
L'exemple de code suivant montre comment exécuter une `UPDATE` instruction.
1. Ajoutez le code suivant qui met à jour un document du `People` tableau en le mettant à jour `age` vers`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. Interrogez à nouveau la table pour voir la valeur mise à jour.
```
# Query the updated document
qldb_driver.execute_lambda(lambda executor: read_documents(executor))
```
1. Pour exécuter l'application, entrez la commande suivante depuis le répertoire de votre projet.
```
$ python app.py
```
## Exécution de l'application complète
L'exemple de code suivant représente la version complète de l'`app.py`application. Au lieu d'effectuer les étapes précédentes individuellement, vous pouvez également copier et exécuter cet exemple de code du début à la fin. Cette application montre certaines opérations CRUD de base sur le registre nommé. `quick-start`
**Note**
Avant d'exécuter ce code, assurez-vous qu'aucune table active n'est déjà nommée `People` dans le `quick-start` registre.
```
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))
```
Pour exécuter l'application complète, entrez la commande suivante depuis le répertoire de votre projet.
```
$ python app.py
```
# Pilote Amazon QLDB pour Python — Guide de référence du livre de recettes
**Important**
Avis de fin de support : les clients existants pourront utiliser Amazon QLDB jusqu'à la fin du support le 31 juillet 2025. Pour plus de détails, consultez [Migrer un registre Amazon QLDB vers Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/).
Ce guide de référence présente les cas d'utilisation courants du pilote Amazon QLDB pour Python. Il fournit des exemples de code Python qui montrent comment utiliser le pilote pour exécuter des opérations de base de *création, de lecture, de mise à jour et de suppression* (CRUD). Il inclut également des exemples de code pour le traitement des données Amazon Ion. En outre, ce guide met en évidence les meilleures pratiques pour rendre les transactions idempotentes et mettre en œuvre des contraintes d'unicité.
**Note**
Le cas échéant, certains cas d'utilisation comportent des exemples de code différents pour chaque version majeure prise en charge du pilote QLDB pour Python.
**Contents**
+ [Importation du pilote](#cookbook-python.importing)
+ [Instanciation du pilote](#cookbook-python.instantiating)
+ [Opérations CRUD](#cookbook-python.crud)
+ [Création de tables](#cookbook-python.crud.creating-tables)
+ [Création d'index](#cookbook-python.crud.creating-indexes)
+ [Lecture de documents](#cookbook-python.crud.reading)
+ [Utilisation des paramètres de requête](#cookbook-python.reading-using-params)
+ [Insertion de documents](#cookbook-python.crud.inserting)
+ [Insertion de plusieurs documents dans une seule déclaration](#cookbook-python.crud.inserting.multiple)
+ [Mettre à jour des documents](#cookbook-python.crud.updating)
+ [Supprimer des documents](#cookbook-python.crud.deleting)
+ [Exécution de plusieurs instructions dans une transaction](#cookbook-python.crud.multi-statement)
+ [Logique des nouvelles tentatives](#cookbook-python.crud.retry-logic)
+ [Mettre en œuvre des contraintes d'unicité](#cookbook-python.crud.uniqueness-constraints)
+ [Travailler avec Amazon Ion](#cookbook-python.ion)
+ [Importation du module Ion](#cookbook-python.ion.import)
+ [Création de types d'ions](#cookbook-python.ion.creating-types)
+ [Obtenir un dump binaire d'ions](#cookbook-python.ion.getting-binary)
+ [Obtenir un vidage de texte Ion](#cookbook-python.ion.getting-text)
## Importation du pilote
L'exemple de code suivant importe le pilote.
------
#### [ 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
```
------
**Note**
Cet exemple importe également le package Amazon Ion (`amazon.ion.simpleion`). Vous avez besoin de ce package pour traiter les données Ion lors de l'exécution de certaines opérations de données dans cette référence. Pour en savoir plus, consultez [Travailler avec Amazon Ion](#cookbook-python.ion).
## Instanciation du pilote
L'exemple de code suivant crée une instance du pilote qui se connecte à un nom de registre spécifié à l'aide des paramètres par défaut.
------
#### [ 3.x ]
```
qldb_driver = QldbDriver(ledger_name='vehicle-registration')
```
------
#### [ 2.x ]
```
qldb_driver = PooledQldbDriver(ledger_name='vehicle-registration')
```
------
## Opérations CRUD
QLDB *exécute des opérations de création, de lecture, de mise à jour et* de suppression (CRUD) dans le cadre d'une transaction.
**Avertissement**
La meilleure pratique consiste à rendre vos transactions d'écriture strictement idempotentes.
**Rendre les transactions idempotentes**
Nous vous recommandons de rendre les transactions d'écriture idempotentes afin d'éviter tout effet secondaire inattendu en cas de nouvelle tentative. Une transaction est *idempotente* si elle peut être exécutée plusieurs fois et produire des résultats identiques à chaque fois.
Prenons l'exemple d'une transaction qui insère un document dans une table nommée`Person`. La transaction doit d'abord vérifier si le document existe déjà dans le tableau. Sans cette vérification, le tableau peut se retrouver avec des documents dupliqués.
Supposons que QLDB valide correctement la transaction côté serveur, mais que le client expire en attendant une réponse. Si la transaction n'est pas idempotente, le même document peut être inséré plusieurs fois en cas de nouvelle tentative.
**Utilisation d'index pour éviter l'analyse complète des tables**
Nous vous recommandons également d'exécuter des instructions contenant une clause de `WHERE` prédicat à l'aide d'un opérateur d'*égalité* sur un champ indexé ou un identifiant de document ; par exemple, `WHERE indexedField = 123` ou. `WHERE indexedField IN (456, 789)` Sans cette recherche indexée, QLDB doit effectuer une analyse des tables, ce qui peut entraîner des délais d'expiration des transactions *ou des conflits de contrôle de simultanéité optimistes* (OCC).
Pour plus d'informations sur l'OCC, consultez[Modèle de simultanéité Amazon QLDB](concurrency.md).
**Transactions créées implicitement**
[La méthode [pyqldb.driver.qldb\$1driver.execute\$1lambda accepte une fonction lambda qui reçoit une instance de 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), que vous pouvez utiliser pour exécuter des instructions.](https://amazon-qldb-driver-python.readthedocs.io/en/stable/reference/execution/executor.html#pyqldb.execution.executor.Executor) L'instance de `Executor` enveloppe une transaction créée implicitement.
Vous pouvez exécuter des instructions dans la fonction lambda en utilisant la méthode [execute\$1statement de l'exécuteur](https://amazon-qldb-driver-python.readthedocs.io/en/stable/reference/execution/executor.html#pyqldb.execution.executor.Executor.execute_statement) de transactions. Le pilote valide implicitement la transaction lorsque la fonction lambda revient.
**Note**
La `execute_statement` méthode prend en charge les types Amazon Ion et les types natifs Python. Si vous transmettez un type natif Python comme argument à`execute_statement`, le pilote le convertit en type Ion à l'aide du `amazon.ion.simpleion` module (à condition que la conversion pour le type de données Python donné soit prise en charge). Pour connaître les types de données pris en charge et les règles de conversion, consultez le [code source de Simpleion](https://ion-python.readthedocs.io/en/latest/_modules/amazon/ion/simpleion.html).
Les sections suivantes montrent comment exécuter des opérations CRUD de base, spécifier une logique de nouvelle tentative personnalisée et implémenter des contraintes d'unicité.
**Contents**
+ [Création de tables](#cookbook-python.crud.creating-tables)
+ [Création d'index](#cookbook-python.crud.creating-indexes)
+ [Lecture de documents](#cookbook-python.crud.reading)
+ [Utilisation des paramètres de requête](#cookbook-python.reading-using-params)
+ [Insertion de documents](#cookbook-python.crud.inserting)
+ [Insertion de plusieurs documents dans une seule déclaration](#cookbook-python.crud.inserting.multiple)
+ [Mettre à jour des documents](#cookbook-python.crud.updating)
+ [Supprimer des documents](#cookbook-python.crud.deleting)
+ [Exécution de plusieurs instructions dans une transaction](#cookbook-python.crud.multi-statement)
+ [Logique des nouvelles tentatives](#cookbook-python.crud.retry-logic)
+ [Mettre en œuvre des contraintes d'unicité](#cookbook-python.crud.uniqueness-constraints)
### Création de tables
```
def create_table(transaction_executor):
transaction_executor.execute_statement("CREATE TABLE Person")
qldb_driver.execute_lambda(lambda executor: create_table(executor))
```
### Création d'index
```
def create_index(transaction_executor):
transaction_executor.execute_statement("CREATE INDEX ON Person(GovId)")
qldb_driver.execute_lambda(lambda executor: create_index(executor))
```
### Lecture de documents
```
# 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))
```
#### Utilisation des paramètres de requête
L'exemple de code suivant utilise un paramètre de requête de type natif.
```
cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ?", 'TOYENC486FH')
```
L'exemple de code suivant utilise un paramètre de requête de type Ion.
```
name = ion.loads('Brent')
cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE FirstName = ?", name)
```
L'exemple de code suivant utilise plusieurs paramètres de requête.
```
cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ? AND FirstName = ?", 'TOYENC486FH', "Brent")
```
L'exemple de code suivant utilise une liste de paramètres de requête.
```
gov_ids = ['TOYENC486FH','ROEE1','YH844']
cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId IN (?,?,?)", *gov_ids)
```
**Note**
Lorsque vous exécutez une requête sans recherche indexée, elle appelle une analyse complète de la table. Dans cet exemple, nous recommandons d'avoir un [index](ql-reference.create-index.md) sur le `GovId` terrain pour optimiser les performances. Sans index activé`GovId`, les requêtes peuvent avoir une latence plus importante et peuvent également entraîner des exceptions de conflit OCC ou des délais d'expiration des transactions.
### Insertion de documents
L'exemple de code suivant insère des types de données natifs.
```
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))
```
L'exemple de code suivant insère les types de données Ion.
```
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))
```
Cette transaction insère un document dans le `Person` tableau. Avant l'insertion, il vérifie d'abord si le document existe déjà dans le tableau. **Cette vérification rend la transaction idempotente par nature.** Même si vous exécutez cette transaction plusieurs fois, elle ne provoquera aucun effet secondaire involontaire.
**Note**
Dans cet exemple, nous recommandons d'avoir un index sur le `GovId` terrain pour optimiser les performances. Si l'index n'est pas activé`GovId`, les instructions peuvent avoir une latence plus importante et peuvent également entraîner des exceptions de conflit OCC ou des délais d'attente pour les transactions.
#### Insertion de plusieurs documents dans une seule déclaration
Pour insérer plusieurs documents en utilisant une seule [INSERT](ql-reference.insert.md) instruction, vous pouvez transmettre un paramètre de type [list](driver-working-with-ion.md#driver-ion-list) à l'instruction comme suit.
```
# people is a list
transaction_executor.execute_statement("INSERT INTO Person ?", people)
```
Vous ne placez pas la variable placeholder (`?`) entre crochets (`<<...>>`) lorsque vous transmettez une liste. *Dans les instructions partiQL manuelles, les crochets à double angle indiquent une collection non ordonnée appelée sac.*
### Mettre à jour des documents
L'exemple de code suivant utilise des types de données natifs.
```
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))
```
L'exemple de code suivant utilise les types de données Ion.
```
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))
```
**Note**
Dans cet exemple, nous recommandons d'avoir un index sur le `GovId` terrain pour optimiser les performances. Si l'index n'est pas activé`GovId`, les instructions peuvent avoir une latence plus importante et peuvent également entraîner des exceptions de conflit OCC ou des délais d'attente pour les transactions.
### Supprimer des documents
L'exemple de code suivant utilise des types de données natifs.
```
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))
```
L'exemple de code suivant utilise les types de données Ion.
```
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))
```
**Note**
Dans cet exemple, nous recommandons d'avoir un index sur le `GovId` terrain pour optimiser les performances. Si l'index n'est pas activé`GovId`, les instructions peuvent avoir une latence plus importante et peuvent également entraîner des exceptions de conflit OCC ou des délais d'attente pour les transactions.
### Exécution de plusieurs instructions dans une transaction
```
# 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))
```
### Logique des nouvelles tentatives
La `execute_lambda` méthode du pilote comporte un mécanisme de nouvelle tentative intégré qui tente à nouveau la transaction si une exception réessayable se produit (comme un délai d'expiration ou un conflit OCC).
------
#### [ 3.x ]
Le nombre maximum de tentatives et la stratégie de temporisation sont configurables.
La limite de tentatives par défaut est`4`, et la stratégie de réduction par défaut est [Exponential Backoff and Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) avec une base de millisecondes. `10` Vous pouvez définir la configuration des nouvelles tentatives par instance de pilote et également par transaction en utilisant une instance de [pyqldb.config.retry\$1config. RetryConfig](https://amazon-qldb-driver-python.readthedocs.io/en/stable/reference/config/retry_config.html#pyqldb.config.retry_config.RetryConfig).
L'exemple de code suivant spécifie une logique de nouvelles tentatives avec une limite de tentatives personnalisée et une stratégie de temporisation personnalisée pour une instance du pilote.
```
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)
```
L'exemple de code suivant spécifie une logique de nouvelles tentatives avec une limite de tentatives personnalisée et une stratégie de temporisation personnalisée pour une exécution lambda particulière. Cette configuration `execute_lambda` remplace la logique de nouvelle tentative définie pour l'instance de pilote.
```
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 ]
Le nombre maximum de tentatives de nouvelle tentative est configurable. Vous pouvez configurer la limite de tentatives en définissant la `retry_limit` propriété lors de l'initialisation`PooledQldbDriver`.
La limite de nouvelles tentatives par défaut est `4` de.
------
### Mettre en œuvre des contraintes d'unicité
QLDB ne prend pas en charge les index uniques, mais vous pouvez implémenter ce comportement dans votre application.
Supposons que vous souhaitiez implémenter une contrainte d'unicité sur le `GovId` champ de la `Person` table. Pour ce faire, vous pouvez écrire une transaction qui effectue les opérations suivantes :
1. Affirme que le tableau ne contient aucun document existant avec une valeur spécifiée`GovId`.
1. Insérez le document si l'assertion est acceptée.
Si une transaction concurrente passe simultanément l'assertion, une seule des transactions sera validée avec succès. L'autre transaction échouera en raison d'une exception de conflit OCC.
L'exemple de code suivant montre comment implémenter cette logique de contrainte d'unicité.
```
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))
```
**Note**
Dans cet exemple, nous recommandons d'avoir un index sur le `GovId` terrain pour optimiser les performances. Si l'index n'est pas activé`GovId`, les instructions peuvent avoir une latence plus importante et peuvent également entraîner des exceptions de conflit OCC ou des délais d'attente pour les transactions.
## Travailler avec Amazon Ion
Les sections suivantes montrent comment utiliser le module Amazon Ion pour traiter les données ioniques.
**Contents**
+ [Importation du module Ion](#cookbook-python.ion.import)
+ [Création de types d'ions](#cookbook-python.ion.creating-types)
+ [Obtenir un dump binaire d'ions](#cookbook-python.ion.getting-binary)
+ [Obtenir un vidage de texte Ion](#cookbook-python.ion.getting-text)
### Importation du module Ion
```
import amazon.ion.simpleion as simpleion
```
### Création de types d'ions
L'exemple de code suivant crée un objet Ion à partir du texte Ion.
```
ion_text = '{GovId: "TOYENC486FH", FirstName: "Brent"}'
ion_obj = simpleion.loads(ion_text)
print(ion_obj['GovId']) # prints TOYENC486FH
print(ion_obj['Name']) # prints Brent
```
L'exemple de code suivant crée un objet Ion à partir d'un 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
```
### Obtenir un dump binaire d'ions
```
# 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'
```
### Obtenir un vidage de texte Ion
```
# ion_obj is an Ion struct
print(simpleion.dumps(ion_obj, binary=False)) # prints $ion_1_0 {GovId:'TOYENC486FH',FirstName:"Brent"}
```
Pour plus d'informations sur l'utilisation d'Ion, consultez la [documentation Amazon Ion](http://amzn.github.io/ion-docs/) sur GitHub. Pour d'autres exemples de code relatifs à l'utilisation d'Ion dans QLDB, consultez. [Utilisation des types de données Amazon Ion dans Amazon QLDB](driver-working-with-ion.md)