Python 用 Amazon QLDB ドライバー — クイックスタートチュートリアル

このチュートリアルでは、Python 用 Amazon QLDB ドライバーの最新バージョンを使用して単純なアプリケーションを設定する方法について説明します。このガイドには、ドライバのインストール手順と、作成、読み取り、更新、削除 (CRUD) の基本的なオペレーションを実行する短いコード例が含まれています。これらのオペレーションを完全なサンプルアプリケーションで実行する詳細な例については、「Python チュートリアル」を参照してください。

前提条件

作業を始める前に、次の操作を実行してください。

1. Python ドライバー用の「前提条件」を完了します (まだ完了していない場合)。これには、AWS へのサインアップ、開発のためのプログラムによるアクセスの許可、Python バージョン 3.6 以降のインストールが含まれます。

2. quick-start という名前の台帳を作成します。

   台帳の作成方法については、「Amazon QLDB 台帳の基本的なオペレーション」、または「コンソールの開始方法」の「ステップ 1: 新しい台帳を作成する」を参照してください。

ステップ 1: プロジェクトを設定する

まず、Python プロジェクトをセットアップします。

注記

これらのセットアップ手順を自動化する機能を備えた IDE を使用する場合は、「ステップ 2: ドライバーを初期化する」までスキップできます。

1. アプリケーション用のフォルダを作成します。

   $ mkdir myproject
   $ cd myproject

2. PyPI から Python 用 QLDB ドライバーをインストールするには、以下の pip コマンドを入力します。

   $ pip install pyqldb

   ドライバーをインストールすると、AWS SDK for Python (Boto3) や Amazon Ion パッケージなどの依存関係もインストールされます。

3. app.py という名前の新しいファイルを作成します。

   次に、以下のステップのコード例を段階的に追加し、いくつかの基本的な CRUD オペレーションを試します。または、ステップバイステップのチュートリアルをスキップして、代わりに完全なアプリケーションを実行することもできます。

ステップ 2: ドライバーを初期化する

quick-start という名前の台帳に接続するドライバーのインスタンスを初期化します。以下のコードを app.py ファイルに追加します。

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)

ステップ 3: テーブルとインデックスを作成する

以下のコード例は、CREATE TABLE および CREATE INDEX ステートメントの実行方法を示しています。

以下のコードを追加して、People という名前のテーブルと、そのテーブルの lastName フィールドのインデックスを作成します。クエリのパフォーマンスを最適化し、オプティミスティック同時実行制御 (OCC) 競合例外を制限するために、インデックスが必要です。

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

ステップ 4: ドキュメントを挿入する

次のコード例は、INSERT ステートメントの実行方法を示しています。QLDB は PartiQL クエリ言語 (SQL 互換) と Amazon Ion データ形式 (JSON のスーパーセット) をサポートします。

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

この例では、疑問符 (?) を変数プレースホルダーとして使用して、ドキュメント情報をステートメントに渡します。execute_statement メソッドは、Amazon Ion 型と Python ネイティブ型の両方の値をサポートします。

ヒント

1 つの INSERT ステートメントを使用して複数のドキュメントを挿入するために、次のように型 list のパラメータをステートメントに渡すことができます。

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

リストを渡すときには、変数プレースホルダー (?) を二重山括弧 (<<...>>) で囲まないでください。マニュアルの PartiQL ステートメントでは、二重山括弧はバッグと呼ばれる順序付けされていないコレクションを表します。

ステップ 5: ドキュメントにクエリを実行する

次のコード例は、SELECT ステートメントの実行方法を示しています。

People テーブルからドキュメントをクエリする以下のコードを追加します。

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

ステップ 6: ドキュメントを更新する

次のコード例は、UPDATE ステートメントの実行方法を示しています。

1. age を 42 に更新して People テーブルのドキュメントを更新する以下のコードを追加します。

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

2. テーブルを再度クエリして、更新された値を確認します。

   # Query the updated document
   qldb_driver.execute_lambda(lambda executor: read_documents(executor))

3. アプリケーションを実行するには、プロジェクトディレクトリから以下のコマンドを入力します。

   $ python app.py

完全なアプリケーションの実行

以下のコード例は、app.py アプリケーションの完全なバージョンです。上のステップを個別に実行する代わりに、このコード例を最初から最後までコピーして実行することもできます。このアプリケーションは、quick-start という名前の台帳に対するいくつかの基本的な CRUD オペレーションを実行します。

注記

このコードを実行する前に、quick-start 台帳に People という名前のアクティブなテーブルが存在しないことを確認してください。

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

完全なアプリケーションを実行するには、プロジェクトディレクトリから以下のコマンドを入力します。

$ python app.py