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à.

QLDBDriver Amazon per Python — Guida di riferimento al Cookbook

Questa guida di riferimento mostra i casi d'uso comuni del QLDB driver Amazon 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à.

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

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')

CRUDoperazioni

QLDBesegue operazioni di creazione, lettura, aggiornamento e cancellazione (CRUD) come parte di una transazione.

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 durante l'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 a conflitti ottimistici di controllo della concorrenza (). OCC

Per ulteriori informazioni su OCC, consultare Modello di QLDB concorrenza Amazon.

Transazioni create implicitamente

Il metodo pyqldb.driver.qldb_driver.execute_lambda accetta una funzione lambda che riceve un'istanza di pyQLDB.Execution.Executor.Executor, che puoi usare per eseguire istruzioni. L'istanza di include una Executor transazione creata implicitamente.

È possibile eseguire istruzioni all'interno della funzione lambda utilizzando il metodo execute_statement dell'esecutore della transazione. Il driver esegue implicitamente la transazione quando ritorna la funzione lambda.

Le sezioni seguenti mostrano come eseguire CRUD operazioni di base, specificare una logica di ripetizione personalizzata e implementare vincoli di unicità.

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)

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.

Inserimento di più documenti in un'unica dichiarazione

Per inserire più documenti utilizzando una singola INSERT istruzione, è possibile passare un parametro di tipo elenco 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))

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))

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 e la strategia di backoff sono configurabili.

Il limite di tentativi predefinito è 4 e la strategia di backoff predefinita è Exponential Backoff 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_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à

QLDBnon 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:

Se una transazione concorrente supera contemporaneamente l'asserzione, solo una delle transazioni verrà salvata correttamente. L'altra transazione avrà esito negativo con un'OCCeccezione di conflitto.

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))

Lavorare con Amazon Ion

Le seguenti sezioni mostrano come utilizzare il modulo Amazon Ion per elaborare i dati Ion.

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 Pythondict.

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 su GitHub. Per altri esempi di codice su come lavorare con Ion inQLDB, consultaUtilizzo dei tipi di dati Amazon Ion in Amazon QLDB.