Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Driver Amazon QLDB per Python
**Importante**
Avviso di fine del supporto: i clienti esistenti potranno utilizzare Amazon QLDB fino alla fine del supporto, il 31/07/2025. Per ulteriori dettagli, consulta [Migrare un registro Amazon QLDB su Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/).
Per lavorare con i dati nel tuo registro, puoi connetterti ad Amazon QLDB dall'applicazione Python utilizzando un driver fornito. AWS I seguenti argomenti descrivono come iniziare a usare il driver QLDB per Python.
**Topics**
+ [Risorse per i driver](#getting-started.python.resources)
+ [Prerequisiti](#getting-started.python.prereqs)
+ [Installazione](#getting-started.python.install)
+ [Tutorial di avvio rapido](driver-quickstart-python.md)
+ [Riferimento al libro di cucina](driver-cookbook-python.md)
## Risorse per i driver
Per ulteriori informazioni sulle funzionalità supportate dal driver Python, consultate le seguenti risorse:
+ [Riferimento 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/)
+ [Codice sorgente del driver () GitHub](https://github.com/awslabs/amazon-qldb-driver-python)
+ [Codice sorgente dell'applicazione di esempio (GitHub)](https://github.com/aws-samples/amazon-qldb-dmv-sample-python)
+ [Esempi di codice Amazon Ion](ion.code-examples.md)
## Prerequisiti
Prima di iniziare con il driver QLDB per Python, devi fare quanto segue:
1. Segui le istruzioni di AWS configurazione riportate in. [Accesso ad Amazon QLDB](accessing.md) Questo include gli output seguenti:
1. Iscriviti a AWS.
1. Crea un utente con le autorizzazioni QLDB appropriate.
1. Concedi l'accesso programmatico per lo sviluppo.
1. Installa una delle seguenti versioni di Python dal sito di download di [Python](https://www.python.org/downloads/):
+ **3.6 o successivo — driver** QLDB per Python v3
+ **3.4 o successivo** — driver QLDB per Python v2
1. Imposta le tue AWS credenziali e quelle predefinite. Regione AWS Per istruzioni, consulta [Quickstart](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#configuration) nella AWS SDK per Python (Boto3) documentazione.
Per un elenco completo delle regioni disponibili, consulta gli [endpoint e le quote di Amazon QLDB](https://docs.aws.amazon.com/general/latest/gr/qldb.html) nel. *Riferimenti generali di AWS*
Successivamente, puoi scaricare l'applicazione di esempio completa del tutorial oppure puoi installare solo il driver in un progetto Python ed eseguire brevi esempi di codice.
+ Per installare il driver QLDB e AWS SDK per Python (Boto3) poi in un progetto esistente, procedi con. [Installazione](#getting-started.python.install)
+ Per configurare un progetto ed eseguire brevi esempi di codice che illustrano le transazioni di dati di base su un registro, consulta il. [Tutorial di avvio rapido](driver-quickstart-python.md)
+ Per eseguire esempi più approfonditi delle operazioni delle API relative ai dati e alla gestione nell'applicazione di esempio completa del tutorial, consulta il. [Tutorial di Python](getting-started.python.tutorial.md)
## Installazione
QLDB supporta le seguenti versioni dei driver e le relative dipendenze in Python.
****
| Versione driver | Versione di Python | Stato | Data di rilascio più recente |
| --- | --- | --- | --- |
| [2.x](https://pypi.org/project/pyqldb/2.0.2/) | 3.4 o versione successiva | Versione di produzione | 7 maggio 2020 |
| [3.x](https://pypi.org/project/pyqldb/) | 3.6 o versione successiva | Rilascio di produzione | 28 ottobre 2021 |
Per installare il driver QLDB da PyPI `pip` utilizzando (un gestore di pacchetti per Python), inserisci quanto segue nella riga di comando.
------
#### [ 3.x ]
```
pip install pyqldb
```
------
#### [ 2.x ]
```
pip install pyqldb==2.0.2
```
------
L'installazione del driver installa anche le sue dipendenze, inclusi i pacchetti Amazon [Ion e [AWS SDK per Python (Boto3)](https://aws.amazon.com/sdk-for-python)Amazon.](ion.md)
**Utilizzo del driver per connettersi a un registro**
Quindi puoi importare il driver e usarlo per connetterti a un libro mastro. Il seguente esempio di codice Python mostra come creare una sessione per un nome di registro specificato.
------
#### [ 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)
```
------
Per brevi esempi di codice su come eseguire transazioni di dati di base su un registro, consulta il. [Riferimento al libro di cucina](driver-cookbook-python.md)
# Driver Amazon QLDB per Python — Tutorial di avvio rapido
**Importante**
Avviso di fine del supporto: i clienti esistenti potranno utilizzare Amazon QLDB fino alla fine del supporto, il 31/07/2025. Per ulteriori dettagli, consulta [Migrare un registro Amazon QLDB su Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/).
In questo tutorial, imparerai come configurare una semplice applicazione utilizzando l'ultima versione del driver Amazon QLDB per Python. Questa guida include i passaggi per l'installazione del driver e brevi esempi in codice delle operazioni di base di *creazione, lettura, aggiornamento ed eliminazione* (CRUD). Per esempi più approfonditi che illustrano queste operazioni in un'applicazione di esempio completa, consulta la. [Tutorial di Python](getting-started.python.tutorial.md)
**Topics**
+ [Prerequisiti](#driver-quickstart-python.prereqs)
+ [Fase 1: Configurazione del progetto](#driver-quickstart-python.step-1)
+ [Fase 2: Inizializzare il driver](#driver-quickstart-python.step-2)
+ [Fase 3: Creare una tabella e un indice](#driver-quickstart-python.step-3)
+ [Fase 4: Inserimento di un documento](#driver-quickstart-python.step-4)
+ [Fase 5: Interrogare il documento](#driver-quickstart-python.step-5)
+ [Fase 6: Aggiornare il documento](#driver-quickstart-python.step-6)
+ [Esecuzione dell'applicazione completa](#driver-quickstart-python.complete)
## Prerequisiti
Prima di iniziare, assicurati di fare quanto segue:
1. Completa il driver [Prerequisiti](getting-started.python.md#getting-started.python.prereqs) for the Python, se non l'hai già fatto. Ciò include la registrazione AWS, la concessione dell'accesso programmatico per lo sviluppo e l'installazione di Python versione 3.6 o successiva.
1. Crea un libro mastro denominato. `quick-start`
Per informazioni su come creare un libro mastro, consulta [Operazioni di base per i registri Amazon QLDB](ledger-management.basics.md) o [Fase 1: Creare un nuovo libro contabile](getting-started-step-1.md) in *Guida introduttiva alla console*.
## Fase 1: Configurazione del progetto
Per prima cosa, configura il tuo progetto Python.
**Nota**
Se utilizzi un IDE con funzionalità per automatizzare questi passaggi di configurazione, puoi passare direttamente a. [Fase 2: Inizializzare il driver](#driver-quickstart-python.step-2)
1. Crea una cartella per la tua applicazione.
```
$ mkdir myproject
$ cd myproject
```
1. Per installare il driver QLDB per Python da PyPI, inserisci il seguente comando. `pip`
```
$ pip install pyqldb
```
L'installazione del driver installa anche le sue dipendenze, inclusi i pacchetti Amazon [Ion e [AWS SDK per Python (Boto3)](https://aws.amazon.com/sdk-for-net)Amazon.](ion.md)
1. Crea un nuovo file denominato `app.py`.
Quindi, aggiungi in modo incrementale gli esempi di codice nei passaggi seguenti per provare alcune operazioni CRUD di base. [In alternativa, puoi saltare il step-by-step tutorial ed eseguire invece l'applicazione completa.](#driver-quickstart-python.complete)
## Fase 2: Inizializzare il driver
Inizializza un'istanza del driver che si connette al registro denominato. `quick-start` Aggiungi il codice seguente al tuo `app.py` file.
```
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)
```
## Fase 3: Creare una tabella e un indice
Il seguente esempio di codice mostra come eseguire le `CREATE INDEX` istruzioni `CREATE TABLE` e le istruzioni.
Aggiungere il codice seguente che crea una tabella denominata `People` e un indice per il `lastName` campo di tale tabella. [Gli indici](ql-reference.create-index.md) sono necessari per ottimizzare le prestazioni delle query e aiutano a limitare le eccezioni ai conflitti [OCC (Optimistic Concurrency Control)](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))
```
## Fase 4: Inserimento di un documento
Il seguente esempio di codice mostra come eseguire un'`INSERT`istruzione. QLDB supporta il linguaggio di interrogazione [PartiQL](ql-reference.md) (compatibile con SQL) e il formato dati [Amazon](ion.md) Ion (superset di JSON).
Aggiungi il codice seguente che inserisce un documento nella tabella. `People`
```
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))
```
Questo esempio utilizza un punto interrogativo (`?`) come segnaposto variabile per passare le informazioni del documento all'istruzione. Il `execute_statement` metodo supporta valori sia nei tipi Amazon Ion che nei tipi nativi Python.
**Suggerimento**
Per inserire più documenti utilizzando una singola [INSERT](ql-reference.insert.md) istruzione, puoi passare un parametro di tipo [elenco](driver-working-with-ion.md#driver-ion-list) all'istruzione come segue.
```
# people is a list
transaction_executor.execute_statement("INSERT INTO Person ?", people)
```
Non racchiudete la variabile placeholder (`?`) tra parentesi angolari doppie (`<<...>>`) quando passate un elenco. *Nelle istruzioni PartiQL manuali, le parentesi doppie angolari indicano una raccolta non ordinata nota come borsa.*
## Fase 5: Interrogare il documento
Il seguente esempio di codice mostra come eseguire un'`SELECT`istruzione.
Aggiungere il codice seguente per interrogare un documento dalla `People` tabella.
```
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))
```
## Fase 6: Aggiornare il documento
Il seguente esempio di codice mostra come eseguire un'`UPDATE`istruzione.
1. Aggiungere il codice seguente che aggiorna un documento nella `People` tabella aggiornandolo `age` a`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. Eseguite nuovamente una query sulla tabella per vedere il valore aggiornato.
```
# Query the updated document
qldb_driver.execute_lambda(lambda executor: read_documents(executor))
```
1. Per eseguire l'applicazione, immettete il seguente comando dalla directory del progetto.
```
$ python app.py
```
## Esecuzione dell'applicazione completa
Il seguente esempio di codice è la versione completa dell'`app.py`applicazione. Invece di eseguire i passaggi precedenti singolarmente, potete anche copiare ed eseguire questo esempio di codice dall'inizio alla fine. Questa applicazione dimostra alcune operazioni CRUD di base sul registro denominato. `quick-start`
**Nota**
Prima di eseguire questo codice, assicuratevi di non avere già una tabella attiva denominata `People` nel registro. `quick-start`
```
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))
```
Per eseguire l'applicazione completa, immettete il seguente comando dalla directory del progetto.
```
$ python app.py
```
# Driver Amazon QLDB per Python — Guida di riferimento al libro di cucina
**Importante**
Avviso di fine del supporto: i clienti esistenti potranno utilizzare Amazon QLDB fino alla fine del supporto, il 31/07/2025. Per ulteriori dettagli, consulta [Migrare un registro Amazon QLDB su Amazon Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/).
Questa guida di riferimento mostra i casi d'uso comuni del driver Amazon QLDB per Python. Fornisce esempi di codice Python che dimostrano come utilizzare il driver per eseguire operazioni di base di *creazione, lettura, aggiornamento ed eliminazione* (CRUD). Include anche esempi di codice per l'elaborazione dei dati di Amazon Ion. Inoltre, questa guida illustra le migliori pratiche per rendere le transazioni idempotenti e implementare vincoli di unicità.
**Nota**
Ove applicabile, alcuni casi d'uso hanno esempi di codice diversi per ogni versione principale supportata del driver QLDB per Python.
**Contents**
+ [Importazione del driver](#cookbook-python.importing)
+ [Istanziazione del driver](#cookbook-python.instantiating)
+ [Operazioni CRUD](#cookbook-python.crud)
+ [Creazione di tabelle](#cookbook-python.crud.creating-tables)
+ [Creazione di indici](#cookbook-python.crud.creating-indexes)
+ [Leggere documenti](#cookbook-python.crud.reading)
+ [Utilizzo dei parametri di interrogazione](#cookbook-python.reading-using-params)
+ [Inserimento di documenti](#cookbook-python.crud.inserting)
+ [Inserimento di più documenti in un'unica dichiarazione](#cookbook-python.crud.inserting.multiple)
+ [Aggiornamento dei documenti](#cookbook-python.crud.updating)
+ [Eliminazione di documenti](#cookbook-python.crud.deleting)
+ [Esecuzione di più istruzioni in una transazione](#cookbook-python.crud.multi-statement)
+ [Logica di ripetizione dei tentativi](#cookbook-python.crud.retry-logic)
+ [Implementazione di vincoli di unicità](#cookbook-python.crud.uniqueness-constraints)
+ [Lavorare con Amazon Ion](#cookbook-python.ion)
+ [Importazione del modulo Ion](#cookbook-python.ion.import)
+ [Creazione di tipi di ioni](#cookbook-python.ion.creating-types)
+ [Ottenere un dump binario Ion](#cookbook-python.ion.getting-binary)
+ [Ottenere un dump di testo Ion](#cookbook-python.ion.getting-text)
## Importazione del driver
Il seguente esempio di codice importa il driver.
------
#### [ 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
```
------
**Nota**
Questo esempio importa anche il pacchetto Amazon Ion (`amazon.ion.simpleion`). Questo pacchetto è necessario per elaborare i dati Ion durante l'esecuzione di alcune operazioni sui dati in questo riferimento. Per ulteriori informazioni, consulta [Lavorare con Amazon Ion](#cookbook-python.ion).
## Istanziazione del driver
Il seguente esempio di codice crea un'istanza del driver che si connette a un nome di registro specificato utilizzando le impostazioni predefinite.
------
#### [ 3.x ]
```
qldb_driver = QldbDriver(ledger_name='vehicle-registration')
```
------
#### [ 2.x ]
```
qldb_driver = PooledQldbDriver(ledger_name='vehicle-registration')
```
------
## Operazioni CRUD
QLDB *esegue operazioni di creazione, lettura, aggiornamento ed* eliminazione (CRUD) come parte di una transazione.
**avvertimento**
Come best practice, rendi le tue transazioni di scrittura strettamente idempotenti.
**Rendere le transazioni idempotenti**
Si consiglia di rendere le transazioni di scrittura idempotenti per evitare effetti collaterali imprevisti in caso di nuovi tentativi. Una transazione è *idempotente* se può essere eseguita più volte e produrre risultati identici ogni volta.
Ad esempio, si consideri una transazione che inserisce un documento in una tabella denominata. `Person` La transazione deve innanzitutto verificare se il documento esiste già o meno nella tabella. Senza questo controllo, la tabella potrebbe finire con documenti duplicati.
Supponiamo che QLDB esegua correttamente il commit della transazione sul lato server, ma che il client scada in attesa di una risposta. Se la transazione non è idempotente, lo stesso documento potrebbe essere inserito più di una volta in caso di nuovo tentativo.
**Utilizzo degli indici per evitare scansioni complete della tabella**
Si consiglia inoltre di eseguire istruzioni con una clausola di `WHERE` predicato utilizzando un operatore di *uguaglianza* su un campo indicizzato o un ID di documento, ad esempio o. `WHERE indexedField = 123` `WHERE indexedField IN (456, 789)` *Senza questa ricerca indicizzata, QLDB deve eseguire una scansione della tabella, che può portare a timeout delle transazioni o conflitti ottimistici di controllo della concorrenza (OCC).*
[Modello di concorrenza Amazon QLDB](concurrency.md)Per ulteriori informazioni su OCC, vedere.
**Transazioni create implicitamente**
[Il metodo [pyqldb.driver.qldb\$1driver.execute\$1lambda accetta una funzione lambda che riceve un'istanza di 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), che puoi usare per eseguire istruzioni.](https://amazon-qldb-driver-python.readthedocs.io/en/stable/reference/execution/executor.html#pyqldb.execution.executor.Executor) L'istanza di include una `Executor` transazione creata implicitamente.
È possibile eseguire istruzioni all'interno della funzione lambda utilizzando il metodo [execute\$1statement dell'esecutore](https://amazon-qldb-driver-python.readthedocs.io/en/stable/reference/execution/executor.html#pyqldb.execution.executor.Executor.execute_statement) della transazione. Il driver esegue implicitamente la transazione quando ritorna la funzione lambda.
**Nota**
Il `execute_statement` metodo supporta sia i tipi Amazon Ion che i tipi nativi di Python. Se si passa un tipo nativo Python come argomento a`execute_statement`, il driver lo converte in un tipo Ion utilizzando il `amazon.ion.simpleion` modulo (a condizione che sia supportata la conversione per il tipo di dati Python specificato). Per i tipi di dati e le regole di conversione supportati, consultate il codice sorgente di [simpleion](https://ion-python.readthedocs.io/en/latest/_modules/amazon/ion/simpleion.html).
Le sezioni seguenti mostrano come eseguire operazioni CRUD di base, specificare una logica di ripetizione personalizzata e implementare vincoli di unicità.
**Contents**
+ [Creazione di tabelle](#cookbook-python.crud.creating-tables)
+ [Creazione di indici](#cookbook-python.crud.creating-indexes)
+ [Leggere documenti](#cookbook-python.crud.reading)
+ [Utilizzo dei parametri di interrogazione](#cookbook-python.reading-using-params)
+ [Inserimento di documenti](#cookbook-python.crud.inserting)
+ [Inserimento di più documenti in un'unica dichiarazione](#cookbook-python.crud.inserting.multiple)
+ [Aggiornamento dei documenti](#cookbook-python.crud.updating)
+ [Eliminazione di documenti](#cookbook-python.crud.deleting)
+ [Esecuzione di più istruzioni in una transazione](#cookbook-python.crud.multi-statement)
+ [Logica di ripetizione dei tentativi](#cookbook-python.crud.retry-logic)
+ [Implementazione di vincoli di unicità](#cookbook-python.crud.uniqueness-constraints)
### Creazione di tabelle
```
def create_table(transaction_executor):
transaction_executor.execute_statement("CREATE TABLE Person")
qldb_driver.execute_lambda(lambda executor: create_table(executor))
```
### Creazione di indici
```
def create_index(transaction_executor):
transaction_executor.execute_statement("CREATE INDEX ON Person(GovId)")
qldb_driver.execute_lambda(lambda executor: create_index(executor))
```
### Leggere documenti
```
# 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))
```
#### Utilizzo dei parametri di interrogazione
Il seguente esempio di codice utilizza un parametro di query di tipo nativo.
```
cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ?", 'TOYENC486FH')
```
Il seguente esempio di codice utilizza un parametro di query di tipo Ion.
```
name = ion.loads('Brent')
cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE FirstName = ?", name)
```
Il seguente esempio di codice utilizza più parametri di query.
```
cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ? AND FirstName = ?", 'TOYENC486FH', "Brent")
```
Il seguente esempio di codice utilizza un elenco di parametri di query.
```
gov_ids = ['TOYENC486FH','ROEE1','YH844']
cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId IN (?,?,?)", *gov_ids)
```
**Nota**
Quando si esegue una query senza una ricerca indicizzata, viene richiamata una scansione completa della tabella. In questo esempio, si consiglia di disporre di un [indice](ql-reference.create-index.md) sul campo per ottimizzare le `GovId` prestazioni. Senza un indice attivo`GovId`, le query possono avere una maggiore latenza e possono anche portare a eccezioni nei conflitti OCC o a timeout delle transazioni.
### Inserimento di documenti
Il seguente esempio di codice inserisce tipi di dati nativi.
```
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))
```
Il seguente esempio di codice inserisce i tipi di dati 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))
```
Questa transazione inserisce un documento nella `Person` tabella. Prima dell'inserimento, controlla innanzitutto se il documento esiste già nella tabella. **Questo controllo rende la transazione di natura idempotente.** Anche se esegui questa transazione più volte, non causerà effetti collaterali indesiderati.
**Nota**
In questo esempio, consigliamo di avere un indice sul `GovId` campo per ottimizzare le prestazioni. Senza un indice attivo`GovId`, le istruzioni possono avere una maggiore latenza e possono anche portare a eccezioni nei conflitti OCC o a timeout delle transazioni.
#### Inserimento di più documenti in un'unica dichiarazione
Per inserire più documenti utilizzando una singola [INSERT](ql-reference.insert.md) istruzione, è possibile passare un parametro di tipo [elenco](driver-working-with-ion.md#driver-ion-list) all'istruzione come segue.
```
# people is a list
transaction_executor.execute_statement("INSERT INTO Person ?", people)
```
Non racchiudete la variabile placeholder (`?`) tra parentesi angolari doppie (`<<...>>`) quando passate un elenco. *Nelle istruzioni PartiQL manuali, le parentesi doppie angolari indicano una raccolta non ordinata nota come borsa.*
### Aggiornamento dei documenti
Il seguente esempio di codice utilizza tipi di dati nativi.
```
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))
```
Il seguente esempio di codice utilizza i tipi di dati 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))
```
**Nota**
In questo esempio, si consiglia di disporre di un indice sul `GovId` campo per ottimizzare le prestazioni. Senza un indice attivo`GovId`, le istruzioni possono avere una maggiore latenza e possono anche portare a eccezioni nei conflitti OCC o a timeout delle transazioni.
### Eliminazione di documenti
Il seguente esempio di codice utilizza tipi di dati nativi.
```
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))
```
Il seguente esempio di codice utilizza i tipi di dati 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))
```
**Nota**
In questo esempio, si consiglia di disporre di un indice sul `GovId` campo per ottimizzare le prestazioni. Senza un indice attivo`GovId`, le istruzioni possono avere una maggiore latenza e possono anche portare a eccezioni nei conflitti OCC o a timeout delle transazioni.
### Esecuzione di più istruzioni in una transazione
```
# 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))
```
### Logica di ripetizione dei tentativi
Il `execute_lambda` metodo del driver dispone di un meccanismo di riprova integrato che riprova la transazione se si verifica un'eccezione riprovabile (ad esempio in caso di timeout o conflitti OCC).
------
#### [ 3.x ]
Il numero massimo di tentativi di nuovo tentativo e la strategia di backoff sono configurabili.
Il limite di tentativi predefinito è `4` e la strategia di backoff predefinita è [Exponential Backoff](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) and Jitter con una base di millisecondi. `10` [È possibile impostare la configurazione dei nuovi tentativi per istanza del driver e anche per transazione utilizzando un'istanza di pyqldb.config.retry\$1config. RetryConfig](https://amazon-qldb-driver-python.readthedocs.io/en/stable/reference/config/retry_config.html#pyqldb.config.retry_config.RetryConfig).
Il seguente esempio di codice specifica la logica dei tentativi con un limite di tentativi personalizzato e una strategia di backoff personalizzata per un'istanza del driver.
```
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)
```
Il seguente esempio di codice specifica la logica dei tentativi con un limite di tentativi personalizzato e una strategia di backoff personalizzata per una particolare esecuzione lambda. Questa configurazione `execute_lambda` sostituisce la logica di riprova impostata per l'istanza del driver.
```
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 ]
Il numero massimo di tentativi di nuovo tentativo è configurabile. È possibile configurare il limite di tentativi impostando la `retry_limit` proprietà al momento dell'inizializzazione. `PooledQldbDriver`
Il limite di tentativi predefinito è. `4`
------
### Implementazione di vincoli di unicità
QLDB non supporta indici univoci, ma puoi implementare questo comportamento nella tua applicazione.
Supponiamo di voler implementare un vincolo di unicità sul campo della tabella. `GovId` `Person` A tale scopo, è possibile scrivere una transazione che esegua le seguenti operazioni:
1. Asserisce che la tabella non ha documenti esistenti con un valore specificato`GovId`.
1. Inserisci il documento se l'asserzione ha esito positivo.
Se una transazione concorrente supera contemporaneamente l'asserzione, solo una delle transazioni verrà salvata correttamente. L'altra transazione avrà esito negativo con un'eccezione relativa al conflitto OCC.
Il seguente esempio di codice mostra come implementare questa logica di vincolo di 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))
```
**Nota**
In questo esempio, si consiglia di disporre di un indice sul `GovId` campo per ottimizzare le prestazioni. Senza un indice attivo`GovId`, le istruzioni possono avere una maggiore latenza e possono anche portare a eccezioni nei conflitti OCC o a timeout delle transazioni.
## Lavorare con Amazon Ion
Le seguenti sezioni mostrano come utilizzare il modulo Amazon Ion per elaborare i dati Ion.
**Contents**
+ [Importazione del modulo Ion](#cookbook-python.ion.import)
+ [Creazione di tipi di ioni](#cookbook-python.ion.creating-types)
+ [Ottenere un dump binario Ion](#cookbook-python.ion.getting-binary)
+ [Ottenere un dump di testo Ion](#cookbook-python.ion.getting-text)
### Importazione del modulo Ion
```
import amazon.ion.simpleion as simpleion
```
### Creazione di tipi di ioni
Il seguente esempio di codice crea un oggetto Ion dal testo 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
```
Il seguente esempio di codice crea un oggetto Ion da 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
```
### Ottenere un dump binario Ion
```
# 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'
```
### Ottenere un dump di testo Ion
```
# ion_obj is an Ion struct
print(simpleion.dumps(ion_obj, binary=False)) # prints $ion_1_0 {GovId:'TOYENC486FH',FirstName:"Brent"}
```
Per ulteriori informazioni sull'utilizzo di Ion, consulta la [documentazione di Amazon Ion](http://amzn.github.io/ion-docs/) su GitHub. Per altri esempi di codice sull'utilizzo di Ion in QLDB, vedere. [Utilizzo dei tipi di dati Amazon Ion in Amazon QLDB](driver-working-with-ion.md)