3. API: AqQueue Class

An AqQueue object is created by connection.getQueue(). It is used for enqueuing and dequeuing Oracle Advanced Queuing messages. Each AqQueue can be used for enqueuing, dequeuing, or for both.

See Oracle Advanced Queuing (AQ) for usage.

Added in version 4.0.

Changed in version 6.10: Support for AQ was added in node-oracledb Thin mode.

3.1. AqQueue Properties

aqQueue.name: This read-only property is a string containing the name of the queue specified in the connection.getQueue() call.

aqQueue.deqOptions

This property is an object specifying the Advanced Queuing options to use when dequeuing messages. Attributes can be set before each queue.deqOne() or queue.deqMany(), see Changing AQ options.

When a queue is created, the queue.deqOptions property is an AqDeqOptions object. AqDeqOptions objects cannot be created independently.

Table 3.3 AqDeqOptions Class Properties
Property Name	Data Type	Description
`condition`	String	This read/write property is the condition that must be satisfied in order for a message to be dequeued. The condition is a boolean expression similar to the WHERE clause of a SQL query. The boolean expression can include conditions on message properties, user data properties, and PL/SQL or SQL functions.
`consumerName`	String	This read/write property is the name of the consumer that is dequeuing messages. Only messages matching the consumer name will be accessed. If the queue is not set up for multiple consumers, then this attribute should not be set.
`correlation`	String	This read/write property is the correlation to use when dequeuing. Special pattern-matching characters, such as the percent sign (%) and the underscore (_), can be used. If multiple messages satisfy the pattern, the order of dequeuing is indeterminate.
`deliveryMode`	Integer	This write-only property is the delivery mode when dequeuing messages. It can be one of the following constants: oracledb.AQ_MSG_DELIV_MODE_PERSISTENT, oracledb.AQ_MSG_DELIV_MODE_BUFFERED, or oracledb.AQ_MSG_DELIV_MODE_PERSISTENT_OR_BUFFERED. Note that oracledb.AQ_MSG_DELIV_MODE_BUFFERED is not supported with JSON payloads. Added in version 6.10.
`mode`	Integer	This read/write property is the mode to use for dequeuing messages. It can be one of the following constants: oracledb.AQ_DEQ_MODE_BROWSE, oracledb.AQ_DEQ_MODE_LOCKED, oracledb.AQ_DEQ_MODE_REMOVE, oracledb.AQ_DEQ_MODE_REMOVE_NO_DATA.
`msgId`	Buffer	This read/write property is a unique identifier specifying the message to be dequeued.
`navigation`	Integer	This read/write property is the position in the queue of the message that is to be dequeued. It can be one of the following constants: oracledb.AQ_DEQ_NAV_FIRST_MSG, oracledb.AQ_DEQ_NAV_NEXT_TRANSACTION, oracledb.AQ_DEQ_NAV_NEXT_MSG.
`transformation`	String	This read/write property is the transformation that will take place on messages when they are dequeued. The transformation must be created using dbms_transform. This attribute is only supported in node-oracledb Thick mode and is not supported in Transactional Event Queues (TxEventQ).
`visibility`	Integer	This read/write property defines whether the dequeue occurs in the current transaction or as a separate transaction. It can be one of the following constants: oracledb.AQ_VISIBILITY_IMMEDIATE, oracledb.AQ_VISIBILITY_ON_COMMIT. Constant oracledb.AQ_VISIBILITY_IMMEDIATE can only be specified in `aqQueue.deqMany()` when using node-oracledb Thick mode.
`wait`	Integer	This read/write property is the number of seconds to wait for a message matching the search criteria to become available. It can alternatively be one of the following constants: oracledb.AQ_DEQ_NO_WAIT, oracledb.AQ_DEQ_WAIT_FOREVER.

See Oracle Advanced Queuing Documentation for more information about attributes.

aqQueue.enqOptions

This property is an object specifying the Advanced Queuing options to use when enqueuing messages. Attributes can be set before each queue.enqOne() or queue.enqMany() call to change the behavior of message delivery, see Changing AQ options.

When a queue is created, the queue.enqOptions property is an AqEnqOptions object. AqEnqOptions objects cannot be created independently.

Table 3.4 AqEnqOptions Class Properties
Property Name	Data Type	Description
`deliveryMode`	Integer	This read/write property is the delivery mode when enqueuing messages. It can be one of the following constants: oracledb.AQ_MSG_DELIV_MODE_PERSISTENT, oracledb.AQ_MSG_DELIV_MODE_BUFFERED, oracledb.AQ_MSG_DELIV_MODE_PERSISTENT_OR_BUFFERED. Note that oracledb.AQ_MSG_DELIV_MODE_BUFFERED is not supported with JSON payloads.
`transformation`	String	This read/write property is the transformation that will take place when messages are enqueued. The transformation must be created using dbms_transform. This attribute is only supported in node-oracledb Thick mode and is not supported in Transactional Event Queues (TxEventQ).
`visibility`	Integer	This read/write property defines whether the enqueue occurs in the current transaction or as a separate transaction. It can be one of the following constants: oracledb.AQ_VISIBILITY_IMMEDIATE, oracledb.AQ_VISIBILITY_ON_COMMIT. Constant oracledb.AQ_VISIBILITY_IMMEDIATE can only be specified in `aqQueue.enqMany()` when using node-oracledb Thick mode.

See Oracle Advanced Queuing Documentation for more information about attributes.

aqQueue.payloadType: This read-only property is one of the oracledb.DB_TYPE_RAW or oracledb.DB_TYPE_OBJECT, or oracledb.DB_TYPE_JSON constants.

Changed in version 6.1: Added oracledb.DB_TYPE_JSON constant.

aqQueue.payloadTypeClass

This read-only property is the DbObject Class corresponding to the payload type specified when the queue was created.

This is defined only if the payloadType property has the value oracledb.DB_TYPE_OBJECT.

aqQueue.payloadTypeName: This read-only property is a string and it can either be the string “RAW” or the name of the Oracle Database object type identified when the queue was created.

3.2. AqQueue Methods

aqQueue.deqMany()

Promise:

promise = deqMany(Number maxMessages);

Dequeues up to the specified number of messages from an Oracle Advanced Queue.

The parameters of the aqQueue.deqMany() method are:

Table 3.5 aqQueue.deqMany() Parameters
Parameter	Data Type	Description
`maxMessages`	Number	Dequeue at most this many messages. Depending on the dequeue options, the number of messages returned will be between zero and `maxMessages`.

Callback:

If you are using the callback programming style:

deqMany(Number maxMessages, function(Error error, Array messages));

See aqQueue.deqMany() Parameters for information on the maxMessages parameter.

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

Callback Function Parameter	Description
Array `messages`	An array of AqMessage objects.
Error `error`	If `deqMany()` succeeds, `error` is NULL. If an error occurs, then `error` contains the error message.

aqQueue.deqOne()

Promise:

promise = deqOne();

Dequeues a single message from an Oracle Advanced Queue. Depending on the dequeue options, the message may also be returned as undefined if no message is available.

Callback:

If you are using the callback programming style:

deqOne(function(Error error, AqMessage message));

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

Callback Function Parameter	Description
Error `error`	If `deqOne()` succeeds, `error` is NULL. If an error occurs, then `error` contains the error message.
AqMessage `message`	The message that is dequeued. See AqMessage Class.

Dequeued messages are returned as AqMessage objects.

Table 3.6 AqMessage Class Attributes
Attribute Name	Data Type	Description
`correlation`	String	The correlation that was used during enqueue.
`delay`	Integer	The number of seconds the message was delayed before it could be dequeued.
`deliveryMode`	Integer	The delivery mode the messages was enqueued with.
`enqTime`	Object	A JavaScript Date object with a precision of seconds containing the timestamp of when the message was enqueued. The fractional seconds will be 0. For example, 2025-04-22T13:16:48.000Z. This is a read-only attribute. Added in version 6.9.
`exceptionQueue`	String	The name of the exception queue defined when the message was enqueued. Messages are moved if the number of unsuccessful dequeue attempts has exceeded the maximum number of retries or if the message has expired. The default value is the name of the exception queue associated with the queue table.
`expiration`	Integer	The number of seconds until expiration defined when the message was enqueued. This attribute is an offset from the `delay` attribute. Expiration process requires the queue monitor to be running.
`msgId`	Buffer	The unique identifier of the message.
`numAttempts`	Integer	The number of attempts that were made to dequeue the message.
`originalMsgId`	Buffer	The unique identifier of the message in the last queue that generated it.
`payload`	Buffer or DbObject	The payload of the message, depending on the value of `aqQueue.payloadType`. Note that enqueued Strings are returned as UTF-8 encoded Buffers.
`priority`	Integer	The priority of the message when it was enqueued. A smaller number indicates a higher priority. The priority can be any integer, including negative numbers.
`state`	Integer	The state of the message at the time of the dequeue. It is one of the following constants: oracledb.AQ_MSG_STATE_READY, oracledb.AQ_MSG_STATE_WAITING, oracledb.AQ_MSG_STATE_PROCESSED, or oracledb.AQ_MSG_STATE_EXPIRED.

See Oracle Advanced Queuing Documentation for more information about attributes.

aqQueue.enqMany()

Promise:

promise = enqMany();

Enqueues multiple messages to an Oracle Advanced Queue.

Warning

Calling enqMany() in parallel on different connections acquired from the same pool may cause a problem with older versions of Oracle (see Oracle bug 29928074). Ensure that enqMany() is not run in parallel. Instead, use standalone connections or make multiple calls to enqOne(). The deqMany() method is not affected.

Callback:

If you are using the callback programming style:

enqMany(Array messages, function(Error error));

The parameters of the aqQueue.enqMany() method are:

Table 3.7 aqQueue.enqMany() Parameters
Parameter	Data Type	Description
`messages`	Array	Each element of the array must be a String, a Buffer, a DbObject, or a JavaScript Object as used by `enqOne()`.

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

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

The aqQueue.enqMany() method returns an array of AqMessage objects.

Changed in version 6.1: Previously, aqQueue.enqMany() did not return any value. Now, this method returns an array of AqMessage objects.

aqQueue.enqOne()

Promise:

promise = enqOne();

Enqueues a single message to an Oracle Advanced Queue. The message may be a String, or a Buffer, or a DbObject. It may also be a JavaScript Object containing the actual message and some attributes controlling the behavior of the queued message.

Callback:

If you are using the callback programming style:

enqOne(String message, function(Error error));
enqOne(Buffer message, function(Error error));
enqOne(DbObject message, function(Error error));
enqOne(Object message, function(Error error));

The parameters of the aqQueue.enqOne() method are:

Table 3.8 aqQueue.enqOne() Parameters
Parameter	Data Type	Description
`message`	String, Buffer, DbObject, or Object	String: If the message is a String, it will be converted to a buffer using the UTF-8 encoding. Buffer: If the message is a Buffer, it will be transferred as it is. DbObject: An object of the DbObject Class. Object message: A JavaScript object can be used to alter the message properties. It must contain a `payload` property with the actual message content. It may contain other attributes as noted in the Object Message Attributes table.

Table 3.9 Object Message Attributes
Message Attribute	Data Type	Description
`correlation`	String	The correlation of the message to be enqueued.
`delay`	Number	The number of seconds to delay the message before it can be dequeued.
`exceptionQueue`	String	The name of an exception queue in which to place the message if an exception takes place.
`expiration`	Number	The number of seconds the message is available to be dequeued before it expires. This attribute is an offset from the `delay` attribute. Expiration processing requires the queue monitor to be running.
`payload`	String, Buffer, DbObject, Object	The actual message to be queued. This property must be specified. When enqueuing, the value is checked to ensure that it conforms to the type expected by that queue.
`priority`	Integer	An integer priority of the message. A smaller number indicates a higher priority. The priority can be any integer, including negative numbers.
`recipients`	Array of strings	An array of strings where each string is a recipients name. This allows a limited set of recipients to dequeue each message. The recipients associated with the message overrides the queue subscriber list, if there is one. The recipient names need not be in the subscriber list but can be, if desired. To dequeue a message, the `consumerName` attribute can be set to one of the recipient names. The original message recipient list is not available on dequeued messages. All recipients have to dequeue a message before it gets removed from the queue. Added in version 5.5.

See Oracle Advanced Queuing Documentation for more information about attributes.

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

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

Enqueued messages are returned as AqMessage objects.

Changed in version 6.1: Previously, aqQueue.enqOne() did not return any value. Now, this method returns an AqMessage object.