Objeto Cursor¶

Cursor.__enter__()¶

El punto de entrada para el cursor como gestor de contexto. Vuelve solo.

Cursor.__exit__()¶

El punto de salida del cursor como gestor de contexto. Cierra el cursor.

Cursor.arraysize¶

Este atributo de lectura y escritura se puede usar para ajustar el número de filas que las llamadas internas a la base de datos configuran y almacenan en búfer al obtener filas de las instrucciones SELECT y los CURSORES REF. El valor puede afectar drásticamente el rendimiento de una consulta, ya que afecta directamente el número de viajes en red entre Python y la base de datos. Para métodos comofetchone() y fetchall() no cambia cuántas filas se devuelven a la aplicación. Parafetchmany() es el número predeterminado de filas a buscar.

Debido a los beneficios de rendimiento, el valor predeterminado Cursor.arraysize es 100 en lugar del 1 que recomienda la API de DB. Este valor significa que cada llamada interna a la base de datos obtiene 100 filas.

Consulte Ajuste de rendimiento de recuperación para obtener más información.

Cursor.bindarraysize¶

Este atributo de lectura y escritura especifica el número de filas a enlazar a la vez y se utiliza al crear variables a través de setinputsizes() ovar(). El valor predeterminado es 1, lo que significa enlazar una sola fila a la vez.

Cursor.arrayvar(Tipo de datos, valor)¶

Cree una variable de matriz asociada con el cursor del tipo y tamaño dados y devuelva un objeto variable. El valor es uninteger que especifica el número de elementos a asignar o es una lista y el número de elementos asignados se extrae del tamaño de la lista. Si el valor es una lista, la variable también se establece con el contenido de la lista. Si no se especifica el tamaño y el tipo es una cadena o un binario, se asignan 4000 bytes. Esto es necesario para pasar matrices a PL / SQL (en los casos en que la lista puede estar vacía y el tipo no se puede determinar automáticamente) o para devolver matrices de PL/SQL.

Las variables de matriz solo se pueden usar para matrices asociativas PL/SQL con claves contiguas. Para matrices asociativas PL/SQL con claves escasamente pobladas o para varrays y tablas anidadas, se debe usar el enfoque que se muestra en este ejemplo.

Cursor.bindnames()¶

Devuelve la lista de nombres de variables de enlace enlazados a la instrucción. Tenga en cuenta que la declaración debe haberse preparado primero.

Cursor.bindvars¶

Este atributo de solo lectura proporciona las variables de enlace utilizadas para lastexecute. El valor será una lista o un diccionario dependiendo de si el enlace se realizó por posición o nombre. Se debe tener cuidado al hacer referencia a este atributo. En particular, los elementos no deben eliminarse ni reemplazarse.

Cursor.callfunc(name, ReturnType, parameters=, keywordParameters={})¶

Llama a una función con el nombre dado. El tipo de retorno se especifica en la misma notación que requiere setinputsizes(). La secuencia de parámetros debe contener una entrada para cada parámetro que la función espera. Cualquier parámetro de palabra clave se incluirá después de los parámetros de posición. El resultado de la llamada es el valor de retorno de la función.

Consulte Funciones almacenadas PL / SQL para ver un ejemplo.

Cursor.callproc(name, parameters=, keywordParameters = {})¶

Llame a un procedimiento con el nombre dado. La secuencia de parámetros debe contener una entrada para cada parámetro que el procedimiento espera. El resultado de la llamada es una copia modificada de la secuencia de entrada. Los parámetros de entrada quedan intactos; los parámetros de salida y de entrada/salida se sustituyen por valores posiblemente nuevos. Los parámetros de palabras clave se incluirán después de los parámetros de posición y no se devolverán como parte de la secuencia de salida.

Consulte Procedimientos almacenados PL / SQL para ver un ejemplo.

Cursor.close()¶

Cierre el cursor ahora, en lugar de cuando se llame a _ _ del__. El curso será inutilizable a partir de este punto; se levantará una excepción de error si se intenta cualquier operación con el cursor.

Cursor.connection¶

Este atributo de solo lectura devuelve una referencia al objeto de conexión en el que se creó el cursor.

Cursor.description¶

Este atributo de solo lectura es una secuencia de secuencias de 7 elementos. Cada una de estas consecuencias contiene información que describe una columna de resultados: (nombre, tipo,display_size, internal_size, precisión, escala, null_ok). Este atributo no será ninguno para operaciones que no devuelvan filas o si el cursor no ha tenido una operación invocada a través del método execute() todavía.

El tipo será una de las constantes de tipo de base de datos definidas a nivel de módulo.

Cursor.execute(instrucción, * * Parámetros de palabras clave)¶

Ejecutar una instrucción en la base de datos. Consulte Ejecución SQL.

Los parámetros se pueden pasar como un diccionario o secuencia o como parámetros de palabras clave. Si los parámetros son un diccionario, los valores estarán obligados apodo y si los parámetros son una secuencia de los valores estará obligado byposition. Tenga en cuenta que si los valores están vinculados por posición, el orden de las variables es de izquierda a derecha, ya que se encuentran en el estado y las sentencias SQL se procesan de manera diferente a las sentencias PL/SQL. Por esta razón, generalmente se recomienda enlazar parámetros por nombre en lugar de por posición.

Los parámetros pasados como diccionario son pares de nombre y valor. El nombre se asigna al nombre de variable de enlace utilizado por la instrucción y el valor se asigna al valor de Python que desea vincular a esa variable de enlace.

El cursor conservará una referencia a la instrucción. Si no se vuelve a pasar ninguno o el mismo objeto de cadena, el cursor ejecutará esa declaración de nuevo sin realizar una preparación o rebinding y redefinición.Esto es más efectivo para algoritmos donde se usa la misma instrucción, pero diferentes parámetros están vinculados a ella (muchas veces). Tenga en cuenta que los parámetros que no se pasan durante las ejecuciones posteriores conservarán el valor que se pasó durante la última ejecución que los contenía.

Para obtener la máxima eficiencia al reutilizar una instrucción, es mejor usar el métodosetinputsizes() para especificar los tipos y tamaños de parámetros con anticipación; en particular, se asume que Ninguno es una cadena de longitud 1, por lo que cualquier valor que se vincule posteriormente como números o fechas elevará una excepción de error de tipo.

Si la instrucción es una consulta, el cursor se devuelve como una conveniencia para thecaller (por lo que se puede usar directamente como un iterador sobre las filas en thecursor); de lo contrario, se devuelve None.

Cursor.executemany(instrucción, parámetros, batcherrors = False, arraydmlrowcounts=False)¶

Prepare una instrucción para su ejecución en una base de datos y luego ejecútela contra todas las asignaciones de parámetros o secuencias encontradas en los separadores de secuencias. Consulte Ejecución de Sentencias por Lotes y Carga Masiva.

La instrucción se administra de la misma manera que el método execute()la administra. Si el tamaño de los búferes asignados para cualquiera de los parámetros supera los 2 GB, recibirá el error » DPI-1015: el tamaño de la matriz de < n > es demasiado grande», donde < n> varía con el tamaño de cada elemento asignado en el búfer. Si recibe este error, disminuya el número de elementos en los parámetros de secuencia.

Si no hay parámetros, o los parámetros se han enlazado previamente, el número de iteraciones se puede especificar como un entero en lugar de necesitar proporcionar una lista de asignaciones o secuencias vacías.

Cuando es true, el parámetro batcherrors habilita la compatibilidad con errores de lote dentro de Oracle y garantiza que la llamada tenga éxito incluso si se produce una excepción en uno o más de los parámetros de la secuencia. Los errores pueden ser corregidos usando getbatcherrors().

Cuando es true, el parámetro arraydmlrowcounts permite que los recuentos de filas de DML se transfieran de Oracle una vez completado el método. Los recuentos de filas se pueden recuperar utilizando getarraydmlrowcounts().

Tanto el parámetro batcherrors como el parámetro arraydmlrowcounts solo pueden ser verdaderos al ejecutar una instrucción insert, update, delete o merge; en todos los demás casos se producirá un error.

Para una máxima eficiencia, es mejor usar el métodosetinputsizes() para especificar los tipos y tamaños de parámetros con anticipación; en particular, se asume que Ninguno es una cadena de longitud 1, por lo que cualquier valor que se vincule posteriormente como números o fechas aumentará una excepción de error de tipo.

Cursor.executemanyprepared(numIters)¶

Ejecutar la instrucción previamente preparada y enlazada el número de veces dado. Las variables que están enlazadas deben haberse establecido ya en el valor deseado antes de realizar esta llamada. Este método fue diseñado para el caso en el que se requiere un rendimiento óptimo, ya que se produce a expensas de la compatibilidad con la API de la base de datos.

Cursor.fetchall()¶

Obtenga todas las filas (restantes) de un resultado de consulta, devolviéndolas como una lista de sencillos. Se devuelve una lista vacía si no hay más filas disponibles. Tenga en cuenta que el atributo arraysize del cursor puede afectar el rendimiento de esta operación, ya que las lecturas internas de la base de datos se realizan en lotes que corresponden a la arraysize.

Se genera una excepción si la llamada anterior a execute()no produjo ningún conjunto de resultados o si aún no se emitió ninguna llamada.

Consulte Métodos de recuperación para ver un ejemplo.

Cursor.fetchmany()¶

Obtener el siguiente conjunto de filas de un resultado de consulta, devolviendo una lista de tuples.An se devuelve una lista vacía si no hay más filas disponibles. Tenga en cuenta que el atributo arraysize de thecursor puede afectar el rendimiento de esta operación.

El número de filas a obtener se especifica mediante el parámetro. Si no se otorga, el atributo arraysize del cursor determina el número de filas a marcar. Si el número de filas disponibles para obtener es menor que el número solicitado, se devolverán menos filas.

Se genera una excepción si la llamada anterior a execute()no produjo ningún conjunto de resultados o si aún no se emitió ninguna llamada.

Consulte Métodos de recuperación para ver un ejemplo.

Cursor.fetchone()¶

Obtenga la siguiente fila de un conjunto de resultados de consulta, devolviendo una sola tupla o Nonewhen cuando no haya más datos disponibles.

Se genera una excepción si la llamada anterior a execute()no produjo ningún conjunto de resultados o si aún no se emitió ninguna llamada.

Consulte Métodos de recuperación para ver un ejemplo.

Cursor.fetchraw()¶

Obtenga el siguiente conjunto de filas de un resultado de consulta en los búferes internos de las variables definidas para el cursor. Se devuelve el número de filas realmente obtenidas. Este método fue diseñado para el caso en el que se requiere un rendimiento óptimo, ya que se produce a expensas de la compatibilidad con la API de la base de datos.

Se genera una excepción si la llamada anterior a execute()no produjo ningún conjunto de resultados o si aún no se emitió ninguna llamada.

Cursor.fetchvars¶

Este atributo de solo lectura especifica la lista de variables creadas para la última consulta que se ejecutó en el cursor. Se debe tener cuidado al hacer referencia a este atributo. En particular, los elementos no deben eliminarse ni reemplazarse.

Cursor.getarraydmlrowcounts()¶

Recupere los recuentos de filas DML después de una llamada a executemany()con arraydmlrowcounts habilitado. Esto devolverá una lista de enteros que respondan al número de filas afectadas por la instrucción DML para cada elemento del array pasado a executemany().

Cursor.getbatcherrors()¶

Recupere las excepciones que tuvieron lugar después de una llamada aexecutemany() con batcherrors habilitado. Esto devolverá una lista a de objetos de error, un error por cada iteración que falló. El offset se puede determinar mirando el atributo offset del objeto error.

Cursor.getimplicitresults()¶

Devuelve una lista de cursores que corresponden a resultados implícitos disponibles desde un bloque o procedimiento PL/SQL sin el uso de parámetros de refcursor. El bloque o procedimiento PL/SQL abre los cursores y los marca para devolverlos al cliente utilizando proceduredbms_sql.return_result. Los cursores devueltos de esta manera no deben cerrarse. Se cerrarán automáticamente por el cursor padre cuando se cierre. Cerrar el cursor padre invalidará los cursores devueltos por este método.

Cursor.inputtypehandler¶

Este atributo de lectura y escritura especifica un método llamado para cada valor que se enlaza a una instrucción ejecutada en el cursor y anula el atributo con el mismo nombre en la conexión si se especifica. Se espera que la firma del método ishandler(cursor, value, arraysize) y el valor devuelto sean objeto variable o Ninguno, en cuyo caso se creará un objeto variable predeterminado. Si este atributo es None, se utiliza el valor del atributo con el mismo nombre en la conexión.

Cursor.__iter__

()¶

Devuelve el cursor para ser utilizado como un iterador.

Cursor.lastrowid¶

Este atributo de solo lectura devuelve el rowid de la última fila modificada por thecursor. Si no se modificó ninguna fila en la última operación realizada en elcursor, se devuelve el valor None.

Cursor.outputtypehandler¶

Este atributo de lectura y escritura especifica un método llamado para cada columna que se obtiene de este cursor. Se espera que la firma del método ishandler(cursor, nombre, tipo predeterminado, longitud, precisión, escala) y el valor de retorno sean un objeto variable o Ninguno, en cuyo caso se creará un objeto variable predeterminada. Si este atributo es None, en su lugar se utiliza el valor del atributo con el mismo nombre en la conexión.

Consulte Cambiar los Tipos de Datos Obtenidos con Controladores de Tipo de salida.

Cursor.parse(sentencia)¶

Esto se puede usar para analizar una sentencia sin ejecutarla (este paso se realiza automáticamente por Oracle cuando se ejecuta una sentencia).

Cursor.prefetchrows¶

Este atributo de lectura y escritura se puede usar para ajustar el número de filas que obtiene la biblioteca de cliente de theOracle cuando se ejecuta una instrucción SELECT. Este valor puede reducir el número de viajes de ida y vuelta a la base de datos que se requieren para obtener filas, pero a costa de memoria adicional. Establecer este valor en 0 puede ser útil cuando se debe controlar explícitamente el tiempo de las búsquedas.

Consulte Ajuste de rendimiento de recuperación para obtener más información.

Cursor.prepare(sentencia)¶

Esto se puede usar antes de una llamada a execute() para definir la declaración que se ejecutará. Cuando esto se hace, la fase de preparación no se realizará cuando la llamada a execute() se realice con uno o el mismo objeto de cadena que la instrucción. Si se especifica, la declaración se devolverá a la caché de instrucciones con la etiqueta dada. Consulte la documentación de Oracle para obtener más información sobre la caché de instrucciones.

Consulte Almacenamiento en caché de instrucciones para obtener más información.

Cursor.rowcount¶

Este atributo de solo lectura especifica el número de filas que se han obtenido actualmente del cursor (para sentencias select), que se han visto afectadas por la operación (para insert, update, delete y mergestatements) o el número de ejecuciones exitosas de la sentencia(para sentencias PL/SQL).

Cursor.rowfactory¶

Este atributo de lectura y escritura especifica un método para llamar a cada fila que se obtiene de la base de datos. Normalmente se devuelve una tupla para cada fila, pero si se establece este atributo, se llama al método con la tupla que normalmente se devolvería, y el resultado del método se devuelve en lugar.

Consulte Cambio de resultados de consulta con Fábricas de filas.

Cursor.scroll(valor = 0, modo = «relativo»)¶

Desplace el cursor en el conjunto de resultados a una nueva posición de acuerdo con el modo.

Si el modo es «relativo» (el valor predeterminado), el valor se toma como una compensación de la posición actual en el conjunto de resultados. Si se establece en «absoluto», el valor indica una posición de destino absoluta. Si se establece en «primero», el cursor se posiciona en la primera fila y si se establece en «último», el cursor se establece en la última fila del conjunto de resultados.

Se genera un error si el modo es «relativo» o «absoluto» y la operación de desplazamiento colocaría el cursor fuera del conjunto de resultados.

Cursor.scrollable¶

Este atributo booleano de lectura y escritura especifica si el cursor se puede desplazar o no. De forma predeterminada, los cursores no son desplazables, ya que los recursos del servidor y los tiempos de respuesta son mayores que los cursores no desplazables. Este atributo se comprueba y el modo correspondiente se establece en Oracle cuando se llama al método execute().

Cursor.setinputsizes(*args, * * keywordArgs)¶

Esto se puede usar antes de una llamada a execute(),callfunc() o callproc() para predefinir áreas de memoria para los parámetros de la operación. Cada parámetro debe ser atype objeto correspondiente a la entrada que se utiliza o debe ser aninteger especifica la longitud máxima de un parámetro de cadena. Utilice parámetros de palabras clave al enlazar por nombre y parámetros posicionales al enlazar por omisión. El singleton None se puede usar como parámetro cuando se usan parámetros de posición para indicar que no se debe reservar espacio para esa posición.

Cursor.setoutputsize(tamaño)¶

Este método no hace nada y se conserva únicamente por compatibilidad con la API DB. El módulo asigna automáticamente tanto espacio como sea necesario para obtener columnas CRUDAS LARGAS y LARGAS (o CLOB como cadena y BLOB como bytes).

Cursor.statement¶

Este atributo de solo lectura proporciona el objeto de cadena que se preparó previamente con prepare() o se ejecutó conexecute().

Cursor.var(Tipo de datos)¶

Crear una variable con las características especificadas. Este método fue diseñado para su uso con variables de entrada/salida PL/SQL donde la longitud o el tipo no se pueden determinar automáticamente a partir del objeto Python pasado o para su uso en controladores de tipo de entrada y salida definidos en cursores o conexiones.

El parámetro Tipo de datos especifica el tipo de datos que se deben almacenar en la variable. Debe ser una de las constantes de tipo de base de datos, constantes de API de base de datos, un tipo de objeto devuelto por el método Connection.gettype() o uno de los siguientes tipos de Python:

Tipo Python	Tipo de base de datos
bool	cx_Oracle.DB_TYPE_BOOLEAN
bytes	cx_Oracle.DB_TYPE_RAW
fecha y hora.fecha	cx_Oracle.DB_TYPE_DATE
datetime.datetime	cx_Oracle.DB_TYPE_DATE
datetime.timedelta	cx_Oracle.DB_TYPE_INTERVAL_DS
decimal.Decimal	cx_Oracle.DB_TYPE_NUMBER
flotador	cx_Oracle.DB_TYPE_NUMBER
int	cx_Oracle.DB_TYPE_NUMBER
str	cx_Oracle.DB_TYPE_VARCHAR

El tamaño del parámetro especifica la longitud de la cuerda y primas variables y isignored en todos los demás casos. Si no se especifica para variables de cadena y sin procesar,se utiliza el valor 4000.

El parámetro arraysize especifica el número de elementos que tendrá la variable. Si no se especifica, se utiliza el tamaño de la matriz de enlace (normalmente 1). Cuando se crea avariable en un controlador de tipo de salida, este parámetro debe establecerse en el tamaño de matriz del cursor.

Los parámetros inconverter y outconverter especifican los métodos utilizados para convertir valores a / desde la base de datos. Puede encontrar más información en la sección objetos variables.

El parámetro typename especifica el nombre de un tipo de objeto SQL y debe especificarse cuando se utiliza type cx_Oracle.OBJECT a menos que el objeto type se haya pasado directamente como primer parámetro.

El parámetro encodingErrors especifica lo que debe suceder cuando se decodifican cadenas de bytes recuperadas de la base de datos en cadenas. Debe ser uno de los valores anotados en la builtindecodefunction.