4. API: DbObject Class

Calling connection.getDbObjectClass() returns a prototype object representing a named Oracle Database object or collection. Use dbObject.prototype on the class to see the available attributes.

Objects of a named DbObject type are:

created from a DbObject prototype by calling new()
returned by queries
returned when using BIND_OUT for an Oracle Database object

See Oracle Database Objects and Collections for more information.

The DbObject class was added in node-oracledb 4.0.

4.1. DbObject Properties

The properties of a DbObject object are listed below.

dbObject.attributes

This read-only property is an object. When dbObject.isCollection is false, this will be an object containing attributes corresponding to the Oracle Database object attributes. The name of each attribute follows normal Oracle casing semantics.

Each attribute will have an object that contains:

type: the value of one of the Oracle Database Type Constants, such as 2010 for oracledb.DB_TYPE_NUMBER and 2023 for oracledb.DB_TYPE_OBJECT.
typeName: a string corresponding to the type, such as “VARCHAR2” or “NUMBER”. When the attribute is a DbObject, it will contain the name of the object.
typeClass: set if the value of type is a DbObject. It is the DbObject class for the attribute.

For example:

attributes: {
  STREET_NUMBER: { type: 2, typeName: 'NUMBER' },
  LOCATION: {
    type: 2023,
    typeName: 'MDSYS.SDO_POINT_TYPE',
    typeClass: [Function]
  }
}

dbObject.elementType: This read-only property is a number. When dbObject.isCollection is true, this will have a value corresponding to one of the Oracle Database Type Constants.

dbObject.elementTypeClass: This read-only property is an object. When dbObject.isCollection is true and the elements in the collection refer to database objects, this property provides the type class information of the elements.

dbObject.elementTypeName: This read-only property is a string. When dbObject.isCollection is true, this will have the name of the element type, such as “VARCHAR2” or “NUMBER”.

dbObject.fqn: This read-only property is a string which specifies the fully qualified name of the Oracle Database object or collection.

dbObject.isCollection: This read-only property is a boolean value. It is true if the Oracle object is a collection and false otherwise.

dbObject.length: This read-only property is a number. When dbObject.isCollection is true, this will have the number of elements in the collection. It is undefined for non-collections.

dbObject.name: This read-only property is a string which identifies the name of the Oracle Database object or collection.

dbObject.packageName: Added in version 6.2.

This read-only property is a string which identifies the name of the package, if the type refers to a PL/SQL type. Otherwise, it returns undefined.

dbObject.schema: This read-only property is a string which identifies the schema owning the Oracle Database object or collection.

4.2. DbObject Methods

4.2.1. DbObject Methods for Collections

These methods can be used on Oracle Database collections, identifiable when dbObject.isCollection is true. When collections are fetched from the database, altered, and then passed back to the database, it may be more efficient to use these methods directly on the retrieved DbObject than it is to convert that DbObject to and from a JavaScript object.

dbObject.append(value): Adds the given value to the end of the collection. If no elements exist in the collection, this creates an element at index 0. Otherwise, it creates an element at the index position immediately following the highest index available in the collection.

dbObject.deleteElement(Number index): Deletes the value from collection at the given index.

dbObject.getElement(Number index): Returns the value associated with the given index. If no element exists at that index, an exception is raised.

dbObject.getFirstIndex(): Returns the first index for later use to obtain the value.

dbObject.getKeys(): Returns a JavaScript array containing the ‘index’ keys.

dbObject.getLastIndex(): To obtain the last index for later use to obtain a value.

dbObject.getNextIndex(Number index)

Returns the next index value for later use to obtain a value. If there are no elements in the collection following the specified index, it returns undefined.

If the passed-in index parameter is not found in the associative array collection types indexed by integers, then this method returns the next available higher index found in the associative array.

dbObject.getPrevIndex(Number index)

Returns the previous index for later use to obtain the value. If there are no elements in the collection preceding the specified index, it returns undefined.

If the passed-in index parameter is not found in the associative array collection types indexed by integers, then this method returns the next available lower index found in the associative array.

dbObject.hasElement(Number index): Returns true if an element exists in the collection at the given index. Returns false otherwise.

dbObject.setElement(Number index, value): To set the given value at the position of the given index.

dbObject.getValues(): Returns an array of element values as a JavaScript array in key order.

dbObject.toMap(): Returns a map object for the collection types indexed by PLS_INTEGER where the collection’s indexes are the keys and the elements are its values. See Associative Array Indexed By PLS_INTEGER for example.

Added in version 6.4.

dbObject.copy(): Creates a copy of the object and returns it. For Thick mode, this method requires Oracle Client libraries 12.2 or higher, if you are copying PL/SQL collection VARRAY types.

Added in version 6.8.

dbObject.trim(count): Trims the specified number of elements from the end of the collection.