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.

The lob.chunkSize property returns undefined when a LOB is closed.

Changed in version 7.0: This property now returns undefined when a LOB is closed.

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).

Due to Node.js type limitations, the largest length value will be 2 ^ 32 - 1, even if the actual LOB length is larger. Larger values will wrap.

The lob.length property returns undefined when a LOB is closed.

Changed in version 7.0: This property now returns undefined when a LOB is closed.

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.

The lob.pieceSize property returns undefined when a LOB is closed.

Changed in version 7.0: This property now returns undefined when a LOB is closed.

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.fileExists()

Added in version 6.6.

Promise:

promise = fileExists();

Returns a boolean which indicates whether the file specified by the LOB exists in the directory alias or not. This method returns true if the file exists in the directory and false if it does not. If the directory that this method is trying to access does not exist, then this method returns an error. This method can only be used if the LOB type is BFILE. For all other LOB types, this method returns the NJS-156: operation is only supported on BFILE LOBs error.

Callback:

If you are using the callback programming style:

fileExists(function(Error error, Boolean val));

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

Callback Function Parameter	Description
Error `error`	If `fileExists()` succeeds, `error` is NULL. If an error occurs, then `error` contains the error message.
Boolean `val`	Indicates whether the file exists in the directory. This parameter will be true if the file exists in the directory and false if it does not.

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.

Due to Node.js type limitations, this method will work correctly only with LOBs of length less than 2 ^ 32.

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.

lob.getDirFileName()

Added in version 6.6.

getDirFileName();

This synchronous method returns an object containing the directory alias and file name of the LOB object. This method can only be used if the LOB type is BFILE. For all other LOB types, this method returns the NJS-156: operation is only supported on BFILE LOBs error.

lob.setDirFileName()

Added in version 6.6.

setDirFileName(Object dirFileName);

This synchronous method sets the directory alias and file name of the LOB. This method can only be used if the LOB type is BFILE. For all other LOB types, this method returns the NJS-156: operation is only supported on BFILE LOBs error.

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

Table 5.3 lob.setDirFileName() Parameters
Parameter	Data Type	Description
`dirFileName`	Object	This parameter contains the directory alias and file name of the BFILE type LOB.

Changed in version 6.9: Support for this method was added in node-oracledb Thick mode.

lob.trim()

Added in version 7.0.

Promise:

promise = trim(Number newSize);

Trims the non-BFILE LOB to the new size specified.

The parameters of lob.trim() are:

Table 5.4 lob.trim() Parameters
Parameter	Data Type	Description
`newSize`	Number	The size to which the LOB is to be trimmed. Due to Node.js type limitations, the `newSize` value should be set to less than 2 ^ 32. Using values greater than or equal to 2 ^ 32 will result in an error being raised. The default value is 0. If this parameter is not specified, then the LOB is trimmed to size 0 which is an empty LOB.

Callback:

If you are using the callback programming style:

trim(function(Error error){});

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

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