Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

QLDBDriver Amazon untuk Python - Referensi buku masak

Panduan referensi ini menunjukkan kasus penggunaan umum QLDB driver Amazon untuk Python. Ini memberikan contoh kode Python yang menunjukkan bagaimana menggunakan driver untuk menjalankan operasi create, read, update, dan delete (CRUD) dasar. Ini juga mencakup contoh kode untuk memproses data Amazon Ion. Selain itu, panduan ini menyoroti praktik terbaik untuk membuat transaksi idempoten dan menerapkan kendala keunikan.

Mengimpor driver

Contoh kode berikut mengimpor 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

Membuat instantiasi pengemudi

Contoh kode berikut membuat instance driver yang terhubung ke nama buku besar tertentu menggunakan pengaturan default.

3.x

qldb_driver = QldbDriver(ledger_name='vehicle-registration')

2.x

qldb_driver = PooledQldbDriver(ledger_name='vehicle-registration')

Operasi CRUD

QLDBmenjalankan operasi create, read, update, dan delete (CRUD) sebagai bagian dari transaksi.

Membuat transaksi idempoten

Kami menyarankan Anda membuat transaksi tulis idempoten untuk menghindari efek samping yang tidak terduga dalam kasus percobaan ulang. Transaksi adalah idempoten jika dapat berjalan beberapa kali dan menghasilkan hasil yang identik setiap kali.

Misalnya, pertimbangkan transaksi yang menyisipkan dokumen ke dalam tabel bernamaPerson. Transaksi harus terlebih dahulu memeriksa apakah dokumen sudah ada dalam tabel atau tidak. Tanpa pemeriksaan ini, tabel mungkin berakhir dengan dokumen duplikat.

Misalkan QLDB berhasil melakukan transaksi di sisi server, tetapi klien kehabisan waktu sambil menunggu respons. Jika transaksi tidak idempoten, dokumen yang sama dapat dimasukkan lebih dari sekali dalam kasus percobaan ulang.

Menggunakan indeks untuk menghindari pemindaian tabel penuh

Kami juga menyarankan Anda menjalankan pernyataan dengan klausa WHERE predikat menggunakan operator kesetaraan pada bidang yang diindeks atau ID dokumen; misalnya, atau. WHERE indexedField = 123 WHERE indexedField IN (456, 789) Tanpa pencarian yang diindeks ini, QLDB perlu melakukan pemindaian tabel, yang dapat menyebabkan batas waktu transaksi atau konflik kontrol konkurensi () yang optimis. OCC

Untuk informasi selengkapnya tentang OCC, lihat Model QLDB konkurensi Amazon.

Transaksi yang dibuat secara implisit

Metode pyqldb.driver.qldb_driver.execute_lambda menerima fungsi lambda yang menerima instance PyQLDB.Execution.Executor.Executor, yang dapat Anda gunakan untuk menjalankan pernyataan. Contoh Executor membungkus transaksi yang dibuat secara implisit.

Anda dapat menjalankan pernyataan dalam fungsi lambda dengan menggunakan metode execute_statement dari pelaksana transaksi. Pengemudi secara implisit melakukan transaksi saat fungsi lambda kembali.

Bagian berikut menunjukkan cara menjalankan CRUD operasi dasar, menentukan logika coba ulang kustom, dan menerapkan kendala keunikan.

Membuat tabel

def create_table(transaction_executor):
    transaction_executor.execute_statement("CREATE TABLE Person")

qldb_driver.execute_lambda(lambda executor: create_table(executor))

Membuat indeks

def create_index(transaction_executor):
    transaction_executor.execute_statement("CREATE INDEX ON Person(GovId)")

qldb_driver.execute_lambda(lambda executor: create_index(executor))

Membaca dokumen

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

Menggunakan parameter kueri

Contoh kode berikut menggunakan parameter query tipe asli.

cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ?", 'TOYENC486FH')

Contoh kode berikut menggunakan parameter query tipe Ion.

name = ion.loads('Brent')
cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE FirstName = ?", name)

Contoh kode berikut menggunakan beberapa parameter query.

cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId = ? AND FirstName = ?", 'TOYENC486FH', "Brent")

Contoh kode berikut menggunakan daftar parameter query.

gov_ids = ['TOYENC486FH','ROEE1','YH844']
cursor = transaction_executor.execute_statement("SELECT * FROM Person WHERE GovId IN (?,?,?)", *gov_ids)

Memasukkan dokumen

Contoh kode berikut menyisipkan tipe data asli.

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

Contoh kode berikut menyisipkan tipe data 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))

Transaksi ini memasukkan dokumen ke dalam Person tabel. Sebelum memasukkan, pertama-tama memeriksa apakah dokumen sudah ada di tabel. Pemeriksaan ini membuat transaksi idempoten di alam. Bahkan jika Anda menjalankan transaksi ini beberapa kali, itu tidak akan menyebabkan efek samping yang tidak diinginkan.

Memasukkan beberapa dokumen dalam satu pernyataan

Untuk menyisipkan beberapa dokumen dengan menggunakan satu INSERT pernyataan, Anda dapat meneruskan parameter daftar tipe ke pernyataan sebagai berikut.

# people is a list
transaction_executor.execute_statement("INSERT INTO Person ?", people)

Anda tidak melampirkan variabel placeholder (?) dalam tanda kurung sudut ganda (<<...>>) saat melewati daftar. Dalam pernyataan PartiQL manual, tanda kurung sudut ganda menunjukkan koleksi tidak berurutan yang dikenal sebagai tas.

Memperbarui dokumen

Contoh kode berikut menggunakan tipe data asli.

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

Contoh kode berikut menggunakan tipe data 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))

Menghapus dokumen

Contoh kode berikut menggunakan tipe data asli.

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

Contoh kode berikut menggunakan tipe data 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))

Menjalankan beberapa pernyataan dalam transaksi

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

Logika coba lagi

execute_lambdaMetode pengemudi memiliki mekanisme coba ulang bawaan yang mencoba ulang transaksi jika terjadi pengecualian yang dapat dicoba ulang (seperti batas waktu atau konflik). OCC

3.x

Jumlah maksimum upaya coba lagi dan strategi backoff dapat dikonfigurasi.

Batas coba lagi default adalah4, dan strategi backoff default adalah Exponential Backoff dan Jitter dengan basis milidetik. 10 Anda dapat mengatur konfigurasi coba lagi per instance driver dan juga per transaksi dengan menggunakan instance pyqldb.config.retry_config. RetryConfig.

Contoh kode berikut menentukan logika coba lagi dengan batas coba ulang khusus dan strategi backoff khusus untuk instance 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)

Contoh kode berikut menentukan logika coba lagi dengan batas coba ulang khusus dan strategi backoff khusus untuk eksekusi lambda tertentu. Konfigurasi ini untuk execute_lambda mengganti logika coba lagi yang disetel untuk instance 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

Jumlah maksimum upaya coba lagi dapat dikonfigurasi. Anda dapat mengonfigurasi batas coba lagi dengan menyetel retry_limit properti saat menginisialisasiPooledQldbDriver.

Batas coba ulang default adalah4.

Menerapkan kendala keunikan

QLDBtidak mendukung indeks unik, tetapi Anda dapat menerapkan perilaku ini di aplikasi Anda.

Misalkan Anda ingin menerapkan kendala keunikan pada GovId bidang dalam tabel. Person Untuk melakukan ini, Anda dapat menulis transaksi yang melakukan hal berikut:

Jika transaksi yang bersaing secara bersamaan melewati pernyataan, hanya satu transaksi yang akan berhasil dilakukan. Transaksi lainnya akan gagal dengan pengecualian OCC konflik.

Contoh kode berikut menunjukkan bagaimana menerapkan logika kendala keunikan ini.

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

Bekerja dengan Amazon Ion

Bagian berikut menunjukkan cara menggunakan modul Amazon Ion untuk memproses data Ion.

Mengimpor modul Ion

import amazon.ion.simpleion as simpleion

Membuat tipe Ion

Contoh kode berikut membuat objek Ion dari teks 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

Contoh kode berikut membuat objek Ion dari 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

Mendapatkan dump biner 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'

Mendapatkan dump teks Ion

# ion_obj is an Ion struct
print(simpleion.dumps(ion_obj, binary=False)) # prints $ion_1_0 {GovId:'TOYENC486FH',FirstName:"Brent"}

Untuk informasi selengkapnya tentang bekerja dengan Ion, lihat dokumentasi Amazon Ion di GitHub. Untuk contoh kode lebih lanjut tentang bekerja dengan Ion inQLDB, lihatBekerja dengan tipe data Amazon Ion di Amazon QLDB.