Controlador Amazon QLDB para Python: tutorial de inicio rápido

En este tutorial aprenderá a configurar una aplicación sencilla con la última versión del controlador Amazon QLDB para Python. En esta guía se incluyen los pasos para instalar el controlador y ejemplos de código breve de las operaciones básicas de creación, lectura, actualización y eliminación (CRUD). Para ver ejemplos más detallados que presentan estas operaciones en una aplicación de muestra completa, consulte Tutorial de Python.

Requisitos previos

Antes de comenzar, asegúrese de que hace lo siguiente:

1. Si aún no lo ha hecho, complete el Requisitos previos para el controlador Python. Deberá registrarse en AWS, conceder acceso programático de desarrollo e instalar Python versión 3.6 o posterior.

2. Cree un libro mayor denominado quick-start.

   Para obtener más información sobre cómo crear un libro mayor, consulte Operaciones básicas de libros mayores de Amazon QLDB o Paso 1: crear un nuevo libro mayor en Introducción a la consola.

Paso 1: Configuración del proyecto

En primer lugar, configure su proyecto de Python.

nota

Si usa un IDE con características para automatizar estos pasos de configuración, puede pasar directamente a Paso 2: inicializar el controlador.

1. Cree una carpeta para su aplicación.

   $ mkdir myproject
   $ cd myproject

2. Para instalar el controlador QLDB para Python desde PyPI, introduzca el comando pip.

   $ pip install pyqldb

   Al instalar el controlador también se instalan sus dependencias, incluidos AWS SDK for Python (Boto3) y los paquetes de Amazon Ion.

3. Cree un nuevo archivo llamado app.py.

   A continuación, añada gradualmente los ejemplos de código en los siguientes pasos para probar algunas operaciones básicas de CRUD. También puede saltarse el tutorial paso a paso y ejecutar la aplicación completa.

Paso 2: inicializar el controlador

Inicialice una instancia del controlador que se conecte al libro mayor denominado quick-start. Agregue el siguiente código al archivo 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)

Paso 3: crear una tabla y un índice

Los siguientes ejemplos de código muestran cómo ejecutar las instrucciones CREATE TABLE y CREATE INDEX.

Agregue el siguiente código para crear una tabla con el nombre People y un índice para el campo lastName de dicha tabla. Los índices son necesarios para optimizar el rendimiento de las consultas y ayudar a limitar las excepciones de conflicto de control de concurrencia optimista (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))

Paso 4: insertar un documento

Los siguientes ejemplos de código muestran cómo ejecutar una instrucción de INSERT. QLDB es compatible con el lenguaje de consultas PartiQL (compatible con SQL) y el formato de datos Amazon Ion (superconjunto de JSON).

Añada el siguiente código para insertar un documento en la tabla 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))

En este ejemplo se emplea un signo de interrogación (?) como marcador de posición variable para pasar la información del documento a la instrucción. El método execute_statement admite valores tanto en los tipos de Amazon Ion como en los tipos nativos de Python.

sugerencia

Para insertar varios documentos mediante una sola instrucción INSERT, puede pasar un parámetro del tipo list a la instrucción de la siguiente manera.

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

No coloque el marcador de posición variable (?) entre corchetes de doble ángulo (<<...>>) al pasar una lista. En las instrucciones PartiQL manuales, los corchetes de doble ángulo indican una colección desordenada conocida como bolsa.

Paso 5: consulta del documento

El siguiente ejemplo de código muestra cómo ejecutar una instrucción de SELECT.

Agregue el siguiente código para consultar un documento de la tabla 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))

Paso 6: actualizar el documento

Los siguientes ejemplos de código muestran cómo ejecutar una instrucción de UPDATE.

1. Añada el siguiente código para actualizar un documento de la tabla People actualizando 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))

2. Vuelva a consultar la tabla para ver el valor actualizado.

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

3. Para ejecutar la aplicación, introduzca el siguiente comando desde el directorio del proyecto.

   $ python app.py

Ejecución de la aplicación completa

El siguiente ejemplo de código es la versión completa de la aplicación app.py. En lugar de seguir los pasos anteriores de forma individual, también puede copiar y ejecutar este ejemplo de código de principio a fin. Esta aplicación muestra algunas operaciones básicas de CRUD en el libro mayor denominado quick-start.

nota

Antes de ejecutar este código, asegúrese de no tener ya una tabla activa con el nombre People en el libro mayor 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))

Para ejecutar la aplicación completa, introduzca el siguiente comando desde el directorio de su proyecto.

$ python app.py