15. API: Pipeline Class

Pipeline objects represent a pipeline used to execute multiple database operations concurrently. This class can be used to create Pipeline objects.

Note

True pipelining is only supported in Oracle AI Database 26ai (or later) when using node-oracledb Thin mode.

See Pipelining Database Operations for more information.

Added in version 7.0.

15.1. Pipeline Methods

pipeline.addCommit()

addCommit();

This synchronous method adds a commit operation to the pipeline.

pipeline.addExecute()

addExecute(String statement [, Object parameters [, Object options]]);
addExecute(String statement [, Array parameters [, Object options]]);

This synchronous method adds a statement execution operation to the pipeline using the specified parameters.

Do not use this for queries that return rows. Instead use pipeline.addFetchAll(), pipeline.addFetchMany(), or pipeline.addFetchOne().

The parameters of the pipeline.addExecute() method are:

Table 15.1 pipeline.addExecute() Parameters
Parameter	Data Type	Description
`statement`	String	The SQL statement to be executed.
`parameters`	Object or Array	The values or variables to be bound to the executed statement. This parameter is needed if there are bind parameters in the SQL statement. It can either be an object that associates values or JavaScript variables to the statement’s bind variables by name, or an array of values or JavaScript variables that associate to the statement’s bind variables by their relative positions. See Bind Parameters for Prepared Statements for more details on binding. If a bind value is an object, this parameter may have properties similar to the bindParams of `connection.execute()`. For more information on these properties, see bindParams Parameter Properties.
`options`	Object	The optional parameter that may be used to control statement execution. The properties that can be specified in this parameter are `autoCommit`, `fetchArraySize`, `maxRows`, `outFormat`, and `prefetchRows`. For more information on these properties, see execute(): options Parameter Properties. Using an option that is not supported in `addExecute()` will raise the `NJS-182 - Execute option '<option-name>' is not supported in pipeline mode` error.

pipeline.addExecuteMany()

addExecuteMany(String statement, Array parameters [, Object options]);
addExecuteMany(String statement, Number numIterations [, Object options]);

This synchronous method adds a batch statement execution operation to the pipeline using the specified 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.

The parameters of the pipeline.addExecuteMany() method are:

Table 15.2 pipeline.addExecuteMany() Parameters
Parameter	Data Type	Description
`statement`	String	The SQL or PL/SQL statement to be executed.
`parameters`	Array	The values or variables to be bound to the executed statement. It must be an array of arrays (for ‘bind by position’) or an array of objects whose keys match the bind variable names in the SQL statement (for ‘bind by name’).
`numIterations`	Number	The number of iterations. This parameter is used if there are no bind values, or values have been previously bound.
`options`	Object	The optional parameter that may be used to control statement execution. The properties that can be specified in this parameter are `autoCommit`, `fetchArraySize`, `maxRows`, `outFormat`, `prefetchRows`, and `bindDefs`. For more information on these properties, see executeMany(): options Parameter Properties. Using an option that is not supported in `addExecuteMany()` will raise the `NJS-182 - Execute option '<option-name>' is not supported in pipeline mode` error.

pipeline.addFetchAll()

addFetchAll(String statement [, Object parameters [, Object options [, Number fetchArraySize [, Boolean fetchLobs]]]]);
addFetchAll(String statement [, Array parameters [, Object options [, Number fetchArraySize [, Boolean fetchLobs]]]]);

This synchronous method adds a fetch operation to the pipeline that returns all of the rows.

The parameters of the pipeline.addFetchAll() method are:

Table 15.3 pipeline.addFetchAll() Parameters
Parameter	Data Type	Description
`statement`	String	The SQL or PL/SQL statement to be executed.
`parameters`	Object or Array	The values or variables to be bound to the executed statement. This parameter is needed if there are bind parameters in the SQL statement. It can either be an object that associates values or JavaScript variables to the statement’s bind variables by name, or an array of values or JavaScript variables that associate to the statement’s bind variables by their relative positions. See Bind Parameters for Prepared Statements for more details on binding. If a bind value is an object, this parameter may have properties similar to the bindParams of `connection.execute()`. For more information on these properties, see bindParams Parameter Properties.
`options`	Object	The optional parameter that may be used to control statement execution. The properties that can be specified in this parameter are `autoCommit`, `fetchArraySize`, `maxRows`, `outFormat`, and `prefetchRows`. For more information on these properties, see execute(): options Parameter Properties. Using an option that is not supported in `addFetchAll()` will raise the `NJS-182 - Execute option '<option-name>' is not supported in pipeline mode` error.
`fetchArraySize`	Number	The size of an internal buffer that is used for fetching query rows from Oracle Database.
`fetchLobs`	Boolean	Determines whether to return LOB objects, or string or buffer value when fetching LOB columns. The default value is true.

pipeline.addFetchMany()

addFetchMany(String statement [, Object parameters [, Object options [, Number numRows [, Boolean fetchLobs]]]]);
addFetchMany(String statement [, Array parameters [, Object options [, Number numRows [, Boolean fetchLobs]]]]);

This synchronous method adds a fetch operation to the pipeline that returns up to the specified number of rows.

The parameters of the pipeline.addFetchMany() method are:

Table 15.4 pipeline.addFetchMany() Parameters
Parameter	Data Type	Description
`statement`	String	The SQL or PL/SQL statement to be executed.
`parameters`	Object or Array	The values or variables to be bound to the executed statement. This parameter is needed if there are bind parameters in the SQL statement. It can either be an object that associates values or JavaScript variables to the statement’s bind variables by name, or an array of values or JavaScript variables that associate to the statement’s bind variables by their relative positions. See Bind Parameters for Prepared Statements for more details on binding. If a bind value is an object, this parameter may have properties similar to the bindParams of `connection.execute()`. For more information on these properties, see bindParams Parameter Properties.
`options`	Object	The optional parameter that may be used to control statement execution. The properties that can be specified in this parameter are `autoCommit`, `fetchArraySize`, `maxRows`, `outFormat`, and `prefetchRows`. For more information on these properties, see execute(): options Parameter Properties. Using an option that is not supported in `addFetchMany()` will raise the `NJS-182 - Execute option '<option-name>' is not supported in pipeline mode` error.
`numRows`	Number	The number of rows to be fetched when performing a query of a specific number of rows. The default value is the value of `oracledb.fetchArraySize`.
`fetchLobs`	Boolean	Determines whether to return LOB objects, or string or buffer value when fetching LOB columns. The default value is true.

pipeline.addFetchOne()

addFetchOne(String statement [, Object parameters [, Object options [, Boolean fetchLobs]]]);
addFetchOne(String statement [, Array parameters [, Object options [, Boolean fetchLobs]]]);

This synchronous method adds a fetch operation to the pipeline that returns at most one row.

The parameters of the pipeline.addFetchOne() method are:

Table 15.5 pipeline.addFetchOne() Parameters
Parameter	Data Type	Description
`statement`	String	The SQL or PL/SQL statement to be executed.
`parameters`	Object or Array	The values or variables to be bound to the executed statement. This parameter is needed if there are bind parameters in the SQL statement. It can either be an object that associates values or JavaScript variables to the statement’s bind variables by name, or an array of values or JavaScript variables that associate to the statement’s bind variables by their relative positions. See Bind Parameters for Prepared Statements for more details on binding. If a bind value is an object, this parameter may have properties similar to the bindParams of `connection.execute()`. For more information on these properties, see bindParams Parameter Properties.
`options`	Object	The optional parameter that may be used to control statement execution. The properties that can be specified in this parameter are `autoCommit`, `fetchArraySize`, `maxRows`, `outFormat`, and `prefetchRows`. For more information on these properties, see execute(): options Parameter Properties. Using an option that is not supported in `addFetchOne()` will raise the `NJS-182 - Execute option '<option-name>' is not supported in pipeline mode` error.
`fetchLobs`	Boolean	Determines whether to return LOB objects, or string or buffer value when fetching LOB columns. The default value is true.