Llamar a plpy.execute con una cadena de consulta y un argumento de límite de filas opcional hace que se ejecute la consulta y se devuelva el resultado en un objeto de resultado.

Si se especifica limit y es mayor que cero, entonces plpy.execute recupera como máximo limit filas, como si la consulta incluyera una cláusula LIMIT. Omitir limit o especificarlo como cero hace que no haya límite de filas.

El objeto de resultado emula un objeto de lista o diccionario. Se puede acceder al objeto de resultado por número de fila y nombre de columna. Por ejemplo:

rv = plpy.execute("SELECT * FROM my_table", 5)

devuelve hasta 5 filas de my_table. Si my_table tiene una columna my_column, se accedería a ella como:

foo = rv[i]["my_column"]

El número de filas devueltas se puede obtener utilizando la función incorporada len.

El objeto de resultado tiene estos métodos adicionales:

El objeto de resultado se puede modificar.

Ten en cuenta que llamar a plpy.execute hará que todo el conjunto de resultados se lea en memoria. Solo usa esa función cuando estés seguro de que el conjunto de resultados será relativamente pequeño. Si no quieres correr el riesgo de un uso excesivo de memoria al obtener resultados grandes, usa plpy.cursor en lugar de plpy.execute.

plpy.prepare prepara el plan de ejecución para una consulta. Se llama con una cadena de consulta y una lista de tipos de parámetros, si tienes referencias a parámetros en la consulta. Por ejemplo:

plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", ["text"])

text es el tipo de la variable que pasarás para $1. El segundo argumento es opcional si no deseas pasar ningún parámetro a la consulta.

Después de preparar una sentencia, utilizas una variante de la función plpy.execute para ejecutarla:

rv = plpy.execute(plan, ["name"], 5)

Pasa el plan como primer argumento (en lugar de la cadena de consulta), y una lista de valores para sustituir en la consulta como segundo argumento. El segundo argumento es opcional si la consulta no espera ningún parámetro. El tercer argumento es el límite de filas opcional como antes.

Alternativamente, puedes llamar al método execute en el objeto de plan:

rv = plan.execute(["name"], 5)

Los parámetros de la consulta y los campos de las filas de resultados se convierten entre los tipos de datos de PostgreSQL y Python como se describe en Section 44.2.

Cuando preparas un plan utilizando el módulo PL/Python, se guarda automáticamente. Lee la documentación de SPI (Chapter 45) para obtener una descripción de lo que esto significa. Para hacer un uso efectivo de esto a través de las llamadas a funciones, se debe usar uno de los diccionarios de almacenamiento persistente SD o GD (consulta Section 44.3). Por ejemplo:

CREATE FUNCTION usesavedplan() RETURNS trigger AS $$
    if "plan" in SD:
        plan = SD["plan"]
    else:
        plan = plpy.prepare("SELECT 1")
        SD["plan"] = plan
    # resto de la función
$$ LANGUAGE plpython3u;

La función plpy.cursor acepta los mismos argumentos que plpy.execute (excepto por el límite de filas) y devuelve un objeto de cursor, que te permite procesar grandes conjuntos de resultados en fragmentos más pequeños. Al igual que con plpy.execute, se puede utilizar una cadena de consulta o un objeto de plan junto con una lista de argumentos, o la función cursor se puede llamar como un método del objeto de plan.

El objeto de cursor proporciona un método fetch que acepta un parámetro entero y devuelve un objeto de resultado. Cada vez que llames a fetch, el objeto devuelto contendrá el siguiente lote de filas, nunca mayor que el valor del parámetro. Una vez que se agoten todas las filas, fetch comenzará a devolver un objeto de resultado vacío. Los objetos de cursor también proporcionan una interfaz de iterador, entregando una fila a la vez hasta que se agoten todas las filas. Los datos obtenidos de esa manera no se devuelven como objetos de resultado, sino más bien como diccionarios, correspondiendo cada diccionario a una sola fila de resultado.

Un ejemplo de dos formas de procesar datos de una tabla grande es:

CREATE FUNCTION count_odd_iterator() RETURNS integer AS $$
odd = 0
for row in plpy.cursor("select num from largetable"):
    if row['num'] % 2:
         odd += 1
return odd
$$ LANGUAGE plpython3u;

CREATE FUNCTION count_odd_fetch(batch_size integer) RETURNS integer AS $$
odd = 0
cursor = plpy.cursor("select num from largetable")
while True:
    rows = cursor.fetch(batch_size)
    if not rows:
        break
    for row in rows:
        if row['num'] % 2:
            odd += 1
return odd
$$ LANGUAGE plpython3u;

CREATE FUNCTION count_odd_prepared() RETURNS integer AS $$
odd = 0
plan = plpy.prepare("select num from largetable where num % $1 <> 0", ["integer"])
rows = list(plpy.cursor(plan, [2]))  # o: = list(plan.cursor([2]))

return len(rows)
$$ LANGUAGE plpython3u;

Los cursores se eliminan automáticamente. Pero si deseas liberar explícitamente todos los recursos retenidos por un cursor, utiliza el método close. Una vez cerrado, ya no se pueden obtener más datos de un cursor.