5. API: LOB Class

Lob objects can be used to access Oracle Database CLOB and BLOB data.

A Lob object implements the Node.js Stream interface.

See Working with CLOB, NCLOB and BLOB Data and LOB Bind Parameters for more information.

5.1. Lob Properties

The properties of a Lob object are listed below.

lob.chunkSize: This read-only property is a number which corresponds to the size used by the Oracle LOB layer when accessing or modifying the LOB value.

lob.length: This read-only property is a number which specifies the length of a queried LOB in bytes (for BLOBs) or characters (for CLOBs and NCLOBs).

lob.pieceSize

This read-only property is a number which specifies the number of bytes (for BLOBs) or characters (for CLOBs and NCLOBs) to read for each Stream data event of a queried LOB.

The default value is chunkSize.

For efficiency, it is recommended that pieceSize be a multiple of chunkSize.

The property should not be reset in the middle of streaming since data will be lost when internal buffers are resized.

The maximum value for pieceSize is limited to the value of UINT_MAX.

lob.type: This read-only attribute is a number that shows the type of Lob being used. It will have the value of one of the constants oracledb.BLOB, oracledb.CLOB or oracledb.NCLOB. The value is derived from the bind type when using LOB bind variables, or from the column type when a LOB is returned by a query.

5.2. Lob Methods

lob.close()

Deprecated since version 4.2: Use lob.destroy() instead.

Promise:

promise = close();

Explicitly closes a Lob.

Lobs created with connection.createLob() should be explicitly closed when no longer needed. This frees resources in node-oracledb and in Oracle Database.

Persistent or temporary Lobs returned from the database may also be closed as long as streaming is not currently happening. Note these Lobs are automatically closed when streamed to completion or used as the source for an IN OUT bind. If you try to close a Lob being used for streaming you will get the error NJS-023: concurrent operations on a Lob are not allowed.

The lob.close() method emits the Node.js Stream close event unless the Lob has already been explicitly or automatically closed.

The connection must be open when calling lob.close() on a temporary LOB, such as those created by createLob().

Once a Lob is closed, it cannot be bound.

See Closing Lobs for more information.

Callback:

If you are using the callback programming style:

close(function(Error error){});

The parameters of the callback function function(Error error) are:

Callback Function Parameter	Description
Error `error`	If `close()` succeeds, `error` is NULL. If an error occurs, then `error` contains the error message.

lob.destroy()

destroy([Error error]);

This synchronous method explicitly destroys a Lob.

Lobs created with connection.createLob() should be explicitly closed with lob.destroy() when no longer needed. This frees resources in node-oracledb and in Oracle Database.

Persistent or temporary Lobs returned from the database may also be closed with lob.destroy(). Note these Lobs are automatically closed when streamed to completion or used as the source for an IN OUT bind.

The lob.destroy() method emits the Node.js Stream close event.

Once a Lob is destroyed, it cannot be used.

See Closing Lobs for more information.

The parameters of the lob.destroy() method are:

Table 5.1 lob.destroy() Parameters
Parameter	Description
Error `error`	This optional parameter is used for the error emitted in an `error` event.

lob.getData()

Added in version 4.0.

Promise:

promise = getData(Number offset, Number amount);

Returns a portion (or all) of the data in the LOB.

The parameters of lob.getData() are:

Table 5.2 lob.getData() Parameters
Parameter	Data Type	Description
`offset`	Number	For LOBs of type CLOB and NCLOB, the offset is the position from which the data is to be fetched, in UCS-2 code points. UCS-2 code points are equivalent to characters for all but supplemental characters. If supplemental characters are in the LOB, the offset and amount will have to be chosen carefully to avoid splitting a character. For LOBs of type BLOB and BFILE, the offset is the position of the byte from which the data is to be fetched. The default is 1. The value of `offset` must be greater than or equal to 1. If the `offset` specified in `lob.getData()` exceeds the length of the LOB, then the value null is returned.
`amount`	Number	For LOBs of type CLOB and NCLOB, the amount is the number of UCS-2 code points to be read from the absolute offset of the CLOB or NCLOB. For LOBs of type BLOB and BFILE, the amount is the number of bytes to be read from the absolute offset of the BLOB or BFILE. The default is the length of the LOB. The value of `amount` must be greater than 0. If the `amount` specified in `lob.getData()` exceeds the length of the LOB, then only the data starting from the offset to the end of the LOB is returned. If the `amount` specified in `lob.getData()` is 0, then you will get the error `NJS-005: invalid value for parameter 2`.

For queries returning LOB columns, it can be more efficient to use fetchAsString, fetchAsBuffer, or fetchInfo instead of lob.getData().

Note that it is an asynchronous method and requires a round-trip to the database.

const data = await myLob.getData(offset, amount);

Changed in version 6.4: The offset and amount parameters were added.

Callback:

If you are using the callback programming style:

getData(function(Error error, String data));
getData(function(Error error, Buffer data));

The parameters of the callback function function(Error error, String data) are:

Callback Function Parameter	Description
Error `error`	If `getData()` succeeds, `error` is NULL. If an error occurs, then `error` contains the error message.
String `data` or Buffer `data`	The value of the LOB.