Pipeline Objects — python-oracledb 3.2.0b1 documentation (original) (raw)
22. API: Pipeline Objects
Pipelining is only supported in python-oracledb Thin mode withasyncio. See Pipelining Database Operations for more information about pipelining.
Note
True pipelining is only available when connected to Oracle Database 23ai.
Added in version 2.4.0.
Pipeline objects represent a pipeline used to execute multiple database operations. A Pipeline object is created by callingoracledb.create_pipeline().
22.1.1. Pipeline Methods
Pipeline.add_callfunc(name, return_type, parameters=None, keyword_parameters=None)
Adds an operation to the pipeline that calls a stored PL/SQL function with the given parameters and return type. The createdPipelineOp object is also returned from this function. PipelineOp Attributes can be used to examine the operation, if needed.
When the Pipeline is executed, thePipelineOpResult object that is returned for this operation will have the return_valueattribute populated with the return value of the PL/SQL function if the call completes successfully.
Pipeline.add_callproc(name, parameters=None, keyword_parameters=None)
Adds an operation that calls a stored procedure with the given parameters. The created PipelineOp object is also returned from this function. PipelineOp Attributes can be used to examine the operation, if needed.
Pipeline.add_commit()
Adds an operation that performs a commit.
Pipeline.add_execute(statement, parameters=None)
Adds an operation that executes a statement with the given parameters. The created PipelineOp object is also returned from this function. PipelineOp Attributes can be used to examine the operation, if needed.
Do not use this for queries that return rows. Instead usePipeline.add_fetchall(), Pipeline.add_fetchmany(), orPipeline.add_fetchone().
Pipeline.add_executemany(statement, parameters)
Adds an operation that executes a SQL statement once using all bind value mappings or sequences found in the sequence parameters. This can be used to insert, update, or delete multiple rows in a table. It can also invoke a PL/SQL procedure multiple times. See Executing Batch Statements and Bulk Loading.
The created PipelineOp object is also returned from this function. PipelineOp Attributes can be used to examine the operation, if needed.
The parameters parameter can be a list of tuples, where each tuple item maps to one bind variable placeholder in statement. It can also be a list of dictionaries, where the keys match the bind variable placeholder names in statement. If there are no bind values, or values have previously been bound, the parameters value can be an integer specifying the number of iterations.
Pipeline.add_fetchall(statement, parameters=None, arraysize=None, rowfactory=None)
Adds an operation that executes a query and returns all of the rows from the result set. The created PipelineOp object is also returned from this function. PipelineOp Attributes can be used to examine the operation, if needed.
When the Pipeline is executed, the PipelineOpResult object that is returned for this operation will have the rows attribute populated with the list of rows returned by the query.
The default value for arraysize is defaults.arraysize.
Internally, this operation’s Cursor.prefetchrows size is set to the value of the explicit or default arraysize parameter value.
Pipeline.add_fetchmany(statement, parameters=None, num_rows=None, rowfactory=None)
Adds an operation that executes a query and returns up to the specified number of rows from the result set. The createdPipelineOp object is also returned from this function. PipelineOp Attributes can be used to examine the operation, if needed.
When the Pipeline is executed, thePipelineOpResult object that is returned for this operation will have the rows attribute populated with the list of rows returned by the query.
The default value for num_rows is the value ofdefaults.arraysize.
Internally, this operation’s Cursor.prefetchrows size is set to the value of the explicit or default num_rows parameter, allowing all rows to be fetched in one round-trip
Since only one fetch is performed for a query operation, consider adding aFETCH NEXT clause to the statement to prevent the database processing rows that will never be fetched, see Limiting Rows.
Pipeline.add_fetchone(statement, parameters=None, rowfactory=None)
Adds an operation that executes a query and returns the first row of the result set if one exists. The createdPipelineOp object is also returned from this function. PipelineOp Attributes can be used to examine the operation, if needed.
When the Pipeline is executed, thePipelineOpResult object that is returned for this operation will have the rows attribute populated with this row if the query is performed successfully.
Internally, this operation’s Cursor.prefetchrows andCursor.arraysize sizes will be set to 1.
Since only one fetch is performed for a query operation, consider adding aWHERE condition or using a FETCH NEXT clause in the statement to prevent the database processing rows that will never be fetched, seeLimiting Rows.
22.1.2. Pipeline Attributes
Pipeline.operations
This read-only attribute returns the list of operations associated with the pipeline.
22.2. PipelineOp Objects
PipelineOp objects are created by calling the methods in thePipeline class.
22.2.1. PipelineOp Attributes
PipelineOp.arraysize
This read-only attribute returns the array size that will be used when fetching query rows with Pipeline.add_fetchall(). For all other operations, the value returned is 0.
PipelineOp.keyword_parameters
This read-only attribute returns the keyword parameters to the stored procedure or function being called by the operation, if applicable.
PipelineOp.name
This read-only attribute returns the name of the stored procedure or function being called by the operation, if applicable.
PipelineOp.num_rows
This read-only attribute returns the number of rows to fetch when performing a query of a specific number of rows. For all other operations, the value returned is 0.
PipelineOp.op_type
This read-only attribute returns the type of operation that is taking place. See Pipeline Operation Types for types of operations.
PipelineOp.parameters
This read-only attribute returns the parameters to the stored procedure or function or the parameters bound to the statement being executed by the operation, if applicable.
PipelineOp.return_type
This read-only attribute returns the return type of the stored function being called by the operation, if applicable.
PipelineOp.rowfactory
This read-only attribute returns the row factory callable function to be used in a query executed by the operation, if applicable.
PipelineOp.statement
This read-only attribute returns the statement being executed by the operation, if applicable.
22.3. PipelineOpResult Objects
When AsyncConnection.run_pipeline() is called, it returns a list of PipelineOpResult objects. These objects contain the results of the executedPipelineOp objects operations.
22.3.1. PipelineOpResult Attributes
PipelineOpResult.columns
This read-only attribute is a list of FetchInfoobjects. This attribute will be None for operations that do not return rows.
Added in version 2.5.0.
PipelineOpResult.error
This read-only attribute returns the error that occurred when running this operation. If no error occurred, then the value None is returned.
PipelineOpResult.operation
This read-only attribute returns the PipelineOpoperation object that generated the result.
PipelineOpResult.return_value
This read-only attribute returns the return value of the called PL/SQL function, if a function was called for the operation.
PipelineOpResult.rows
This read-only attribute returns the rows that were fetched by the operation, if a query was executed.
PipelineOpResult.warning
This read-only attribute returns any warning that was encountered when running this operation. If no warning was encountered, then the value_None_ is returned. See PL/SQL Compilation Warnings.
Added in version 2.5.0.