Add dbColumnName property to metadata in query

Author: sharadraju

doc/src/api_manual/connection.rst

@@ -1369,6 +1369,7 @@ Connection Methods
 
             - ``annotations``: The `annotations <https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/annotations_clause.html#GUID-1AC16117-BBB6-4435-8794-2B99F8F68052>`__ object associated with the fetched column. If the column has no associated annotations, this attribute value is `undefined`. Annotations are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
             - ``byteSize``: The database byte size. This is only set for ``oracledb.DB_TYPE_VARCHAR``, ``oracledb.DB_TYPE_CHAR`` and ``oracledb.DB_TYPE_RAW`` column types.
+            - ``dbColumnName``: The actual database column name. This is to distinguish from the ``name`` attribute as the duplicate columns in the query will have the same value for this attribute.
             - ``dbType``: one of the :ref:`Oracle Database Type Constant <oracledbconstantsdbtype>` values.
             - ``dbTypeClass``: The class associated with the database type. This is only set if the database type is an object type.
             - ``dbTypeName``: The name of the database type, such as “NUMBER” or “VARCHAR2”. For object types, this will be the object name.
@@ -1385,6 +1386,10 @@ Connection Methods
             - ``vectorDimensions``: The number of dimensions of the VECTOR column. If the column is not a VECTOR column or allows for any number of dimensions, then the value of this attribute is *undefined*.
             - ``vectorFormat``: The storage format of each dimension value in the VECTOR column. If the column is not a VECTOR column or allows for any storage format, then the value of this attribute is *undefined*.
 
+            .. versionchanged:: 6.10
+
+                The ``dbColumnName`` information attribute was added.
+
             .. versionchanged:: 6.8
 
                 The ``isSparseVector`` information attribute was added.

doc/src/release_notes.rst

@@ -35,6 +35,11 @@ Common Changes
 #)  Added error ``NJS-174`` which is thrown if payload type does not match the
     queue type in :ref:`Advanced Queuing <aq>`.
 
+#)  Added a new extended :ref:`metadata <execmetadata>` information attribute
+    ``dbColumnName`` for a fetched column which provides the actual database
+    column name as opposed to the unique column name provided by the ``name``
+    information attribute.
+
 #)  Fixed bug when attempting to use collection-specific methods for
     :ref:`database objects <dbobjectclass>` which is not actually a collection.
 

lib/thin/protocol/messages/withData.js

@@ -236,6 +236,7 @@ class MessageWithData extends Message {
     // build metadata
     const fetchInfo = {
       name: name,
+      dbColumnName: name,
       dbType: types.getTypeByOraTypeNum(dataType, csfrm),
       nullable: nullable
     };

src/njsVariable.c

@@ -271,10 +271,12 @@ bool njsVariable_getMetadataOne(njsVariable *var, napi_env env,
     // create object to store metadata on
     NJS_CHECK_NAPI(env, napi_create_object(env, metadata))
 
-    // store name
+    // store name in "name" and "dbColumnName" properties initially
     NJS_CHECK_NAPI(env, napi_create_string_utf8(env, var->name,
             var->nameLength, &temp))
     NJS_CHECK_NAPI(env, napi_set_named_property(env, *metadata, "name", temp))
+    NJS_CHECK_NAPI(env, napi_set_named_property(env, *metadata,
+            "dbColumnName", temp))
 
     // store database type, name and class, as needed
     if (!njsUtils_addTypeProperties(env, *metadata, "dbType",

test/binding.js

@@ -913,6 +913,7 @@ describe('4. binding.js', function() {
       const expectedBind = {
         name: "STRINGVALUE",
         fetchType: oracledb.DB_TYPE_CHAR,
+        dbColumnName: "STRINGVALUE",
         dbType: oracledb.DB_TYPE_CHAR,
         dbTypeName: "CHAR",
         nullable: true,

test/columnMetadata.js

@@ -394,7 +394,9 @@ describe('9. columnMetadata.js', function() {
     it('9.5.1 works when using duplicate column alias', async function() {
       const result = await connection.execute("SELECT 1 a, 'abc' a FROM dual");
       assert.strictEqual(result.metaData[0].name, 'A');
+      assert.strictEqual(result.metaData[0].dbColumnName, 'A');
       assert.strictEqual(result.metaData[1].name, 'A_1');
+      assert.strictEqual(result.metaData[1].dbColumnName, 'A');
     });
   });
 

test/dataTypeVector7.js

@@ -45,6 +45,7 @@ describe('309. dataTypeVector7.js', function() {
   const metaDataFloat64 = {
     name: "SPARSEVECTOR64COL",
     dbType: oracledb.DB_TYPE_VECTOR,
+    dbColumnName: "SPARSEVECTOR64COL",
     nullable: true,
     isJson: false,
     isOson: false,
@@ -57,6 +58,7 @@ describe('309. dataTypeVector7.js', function() {
 
   const metaDataFloat64Flex = {
     name: "SPARSEVECTORFLEX64COL",
+    dbColumnName: "SPARSEVECTORFLEX64COL",
     dbType: oracledb.DB_TYPE_VECTOR,
     nullable: true,
     isJson: false,
@@ -69,6 +71,7 @@ describe('309. dataTypeVector7.js', function() {
 
   const metaDataFloat32 = {
     name: "SPARSEVECTOR32COL",
+    dbColumnName: "SPARSEVECTOR32COL",
     dbType: oracledb.DB_TYPE_VECTOR,
     nullable: true,
     isJson: false,
@@ -82,6 +85,7 @@ describe('309. dataTypeVector7.js', function() {
 
   const metaDataFloat32Flex = {
     name: "SPARSEVECTORFLEX32COL",
+    dbColumnName: "SPARSEVECTORFLEX32COL",
     dbType: oracledb.DB_TYPE_VECTOR,
     nullable: true,
     isJson: false,
@@ -94,6 +98,7 @@ describe('309. dataTypeVector7.js', function() {
 
   const metaDataInt8Flex = {
     name: "SPARSEVECTORFLEX8COL",
+    dbColumnName: "SPARSEVECTORFLEX8COL",
     dbType: oracledb.DB_TYPE_VECTOR,
     nullable: true,
     isJson: false,
@@ -106,6 +111,7 @@ describe('309. dataTypeVector7.js', function() {
 
   const metaDataInt8 = {
     name: "SPARSEVECTOR8COL",
+    dbColumnName: "SPARSEVECTOR8COL",
     dbType: oracledb.DB_TYPE_VECTOR,
     nullable: true,
     isJson: false,

test/dupColNames1.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2021, 2022, Oracle and/or its affiliates. */
+/* Copyright (c) 2021, 2025, Oracle and/or its affiliates. */
 
 /******************************************************************************
  *
@@ -152,9 +152,13 @@ describe('246. dupColNames1.js', function() {
 
       const result = await connection.execute(sql);
       assert.equal(result.metaData[0].name, "EMPLOYEE_ID");
+      assert.equal(result.metaData[0].dbColumnName, "EMPLOYEE_ID");
       assert.equal(result.metaData[1].name, "DEPARTMENT_ID");
+      assert.equal(result.metaData[1].dbColumnName, "DEPARTMENT_ID");
       assert.equal(result.metaData[2].name, "DEPARTMENT_ID_1");
+      assert.equal(result.metaData[2].dbColumnName, "DEPARTMENT_ID");
       assert.equal(result.metaData[3].name, "DEPARTMENT_NAME");
+      assert.equal(result.metaData[3].dbColumnName, "DEPARTMENT_NAME");
       assert.equal(result.rows[0].EMPLOYEE_ID, 1001);
       assert.equal(result.rows[0].DEPARTMENT_ID, 101);
       assert.equal(result.rows[1].DEPARTMENT_ID_1, 201);
@@ -192,9 +196,13 @@ describe('246. dupColNames1.js', function() {
 
       const result = await connection.execute(sql);
       assert.equal(result.metaData[0].name, "EMPLOYEE_ID");
+      assert.equal(result.metaData[0].dbColumnName, "EMPLOYEE_ID");
       assert.equal(result.metaData[1].name, "DEPARTMENT_ID");
+      assert.equal(result.metaData[1].dbColumnName, "DEPARTMENT_ID");
       assert.equal(result.metaData[2].name, "DEPARTMENT_ID_2");
+      assert.equal(result.metaData[2].dbColumnName, "DEPARTMENT_ID");
       assert.equal(result.metaData[3].name, "DEPARTMENT_ID_1");
+      assert.equal(result.metaData[3].dbColumnName, "DEPARTMENT_ID_1");
       assert.equal(result.rows[0].EMPLOYEE_ID, 1001);
       assert.equal(result.rows[0].DEPARTMENT_ID, 101);
       assert.equal(result.rows[0].DEPARTMENT_ID_1, 101);

test/getStmtInfo.js

@@ -66,6 +66,7 @@ describe('162. getStmtInfo.js', function() {
             dbTypeName: "NUMBER",
             fetchType: oracledb.DB_TYPE_NUMBER,
             name: "COL",
+            dbColumnName: "COL",
             nullable: true,
             precision: 0,
             scale: -127,
@@ -500,7 +501,9 @@ describe('162. getStmtInfo.js', function() {
 
     const info = await conn.getStatementInfo(sql);
     assert.strictEqual(info.metaData[0].name, 'A');
+    assert.strictEqual(info.metaData[0].dbColumnName, 'A');
     assert.strictEqual(info.metaData[1].name, 'A_1');
+    assert.strictEqual(info.metaData[1].dbColumnName, 'A');
     const result = await conn.execute(sql);
     assert.deepStrictEqual(result.rows[0], [1, 'abc']);
   });
@@ -510,23 +513,30 @@ describe('162. getStmtInfo.js', function() {
 
     const info = await conn.getStatementInfo(sql);
     assert.strictEqual(info.metaData[0].name, 'NUM');
+    assert.strictEqual(info.metaData[0].dbColumnName, 'NUM');
     assert.strictEqual(info.metaData[1].name, 'CONTENT');
+    assert.strictEqual(info.metaData[1].dbColumnName, 'CONTENT');
   });
 
   it('162.39 Mixed aliases and table columns', async function() {
     const sql = `SELECT num, content AS value, 'literal' AS lit FROM ${tableName}`;
 
     const info = await conn.getStatementInfo(sql);
     assert.strictEqual(info.metaData[0].name, 'NUM');
+    assert.strictEqual(info.metaData[0].dbColumnName, 'NUM');
     assert.strictEqual(info.metaData[1].name, 'VALUE');
+    assert.strictEqual(info.metaData[1].dbColumnName, 'VALUE');
     assert.strictEqual(info.metaData[2].name, 'LIT');
+    assert.strictEqual(info.metaData[2].dbColumnName, 'LIT');
   });
 
   it('162.40 Very long column alias names', async function() {
     const longName = 'A'.repeat(30);
 
     const sql = `SELECT 1 AS "${longName}", 2 AS "${longName}" FROM dual`;
     const info = await conn.getStatementInfo(sql);
+    assert.strictEqual(info.metaData[0].dbColumnName, longName);
+    assert.strictEqual(info.metaData[1].dbColumnName, longName);
     assert.notStrictEqual(info.metaData[0].name, info.metaData[1].name);
   });
 
@@ -535,23 +545,29 @@ describe('162. getStmtInfo.js', function() {
 
     const info = await conn.getStatementInfo(sql);
     assert.strictEqual(info.metaData[0].name, 'A');
+    assert.strictEqual(info.metaData[0].dbColumnName, 'A');
     assert.strictEqual(info.metaData[1].name, 'A_1');
+    assert.strictEqual(info.metaData[1].dbColumnName, 'A');
   });
 
   it('162.42 Numeric aliases converted to strings', async function() {
     const sql = `SELECT 1 AS "1", 2 AS "1" FROM dual`;
 
     const info = await conn.getStatementInfo(sql);
     assert.strictEqual(info.metaData[0].name, '1');
+    assert.strictEqual(info.metaData[0].dbColumnName, '1');
     assert.strictEqual(info.metaData[1].name, '1_1');
+    assert.strictEqual(info.metaData[1].dbColumnName, '1');
   });
 
   it('162.43 Special character aliases', async function() {
     const sql = `SELECT 1 AS "@#$", 2 AS "@#$" FROM dual`;
 
     const info = await conn.getStatementInfo(sql);
     assert.strictEqual(info.metaData[0].name, '@#$');
+    assert.strictEqual(info.metaData[0].dbColumnName, '@#$');
     assert.strictEqual(info.metaData[1].name, '@#$_1');
+    assert.strictEqual(info.metaData[1].dbColumnName, '@#$');
   });
 
   it('162.44 Metadata consistency between output formats - duplicate aliases', async function() {
@@ -569,6 +585,8 @@ describe('162. getStmtInfo.js', function() {
     assert.deepStrictEqual(resultArray.metaData, resultObject.metaData);
 
     assert.strictEqual(infoArray.metaData[0].name, 'A');
+    assert.strictEqual(infoArray.metaData[0].dbColumnName, 'A');
     assert.strictEqual(infoArray.metaData[1].name, 'A_1');
+    assert.strictEqual(infoArray.metaData[1].dbColumnName, 'A');
   });
 });

test/nestedCursor05.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2020, 2023, Oracle and/or its affiliates. */
+/* Copyright (c) 2020, 2025, Oracle and/or its affiliates. */
 
 /******************************************************************************
  *
@@ -223,6 +223,7 @@ describe('236. nestedCursor05.js', () => {
     const stringMetaData = {
       name: 'DESCRIPTION',
       fetchType: oracledb.DB_TYPE_VARCHAR,
+      dbColumnName: 'DESCRIPTION',
       dbType: oracledb.DB_TYPE_VARCHAR,
       dbTypeName: 'VARCHAR2',
       nullable: true,
@@ -233,13 +234,16 @@ describe('236. nestedCursor05.js', () => {
     assert.deepStrictEqual(result.metaData[0], stringMetaData);
     assert.strictEqual(result.metaData[1].name, 'CHILDREN');
     assert.strictEqual(result.metaData[1].fetchType, oracledb.DB_TYPE_CURSOR);
+    assert.strictEqual(result.metaData[1].dbColumnName, 'CHILDREN');
     assert.strictEqual(result.metaData[1].dbType, oracledb.DB_TYPE_CURSOR);
     assert.strictEqual(result.metaData[1].dbTypeName, 'CURSOR');
 
     assert.deepStrictEqual(result.metaData[1].metaData[0], stringMetaData);
     assert.strictEqual(result.metaData[1].metaData[1].name, 'GRANDCHILDREN');
     assert.strictEqual(result.metaData[1].metaData[1].fetchType,
       oracledb.DB_TYPE_CURSOR);
+    assert.strictEqual(result.metaData[1].metaData[1].dbColumnName,
+      'GRANDCHILDREN');
     assert.strictEqual(result.metaData[1].metaData[1].dbType,
       oracledb.DB_TYPE_CURSOR);
     assert.strictEqual(result.metaData[1].metaData[1].dbTypeName, 'CURSOR');