Improvements in documentation, tests and examples

Author: sharadraju

doc/src/_ext/table_with_summary.py

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2022, Oracle and/or its affiliates.
+# Copyright (c) 2022, 2024, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -51,6 +51,28 @@ def run(self):
 
 class HTMLTranslator(sphinx.writers.html5.HTML5Translator):
 
+    def visit_paragraph(self, node):
+        text_to_hide = [
+            "No optional parameters for this option value",
+            "No required parameters for this option value",
+            "No optional configuration for this option value",
+            "No relevant notes"
+        ]
+        children = node.children
+        if len(children) == 1 and children[0].astext() in text_to_hide:
+            atts = {
+                "style": "clip: rect(1px, 1px, 1px, 1px);"
+                "clip-path: inset(50%);"
+                "height: 1px;"
+                "overflow: hidden;"
+                "position: absolute;"
+                "white-space: nowrap;"
+                "width: 1px;"
+            }
+            self.body.append(self.starttag(node, "p", "", **atts))
+        else:
+            super().visit_paragraph(node)
+
     def visit_table(self, node):
         if version.parse(sphinx.__version__) > version.parse('4.2.0'):
             self._table_row_indices = [0]

doc/src/api_manual/oracledb.rst

@@ -208,43 +208,43 @@ for common :ref:`Oracle Database Type Constants <oracledbconstantsdbtype>`.
     * - ``oracledb.BFILE``
       - 2020
       - ``oracledb.DB_TYPE_BFILE``
-      -
+      - No relevant notes
     * - ``oracledb.BLOB``
       - 2019
       - ``oracledb.DB_TYPE_BLOB``
-      -
+      - No relevant notes
     * - ``oracledb.BUFFER``
       - 2006
       - ``oracledb.DB_TYPE_RAW``
-      -
+      - No relevant notes
     * - ``oracledb.CLOB``
       - 2017
       - ``oracledb.DB_TYPE_CLOB``
-      -
+      - No relevant notes
     * - ``oracledb.CURSOR``
       - 2021
       - ``oracledb.DB_TYPE_CURSOR``
-      -
+      - No relevant notes
     * - ``oracledb.DATE``
       - 2014
       - ``oracledb.DB_TYPE_TIMESTAMP_LTZ``
-      -
+      - No relevant notes
     * - ``oracledb.DEFAULT``
       - 0
       - NA
       - Used with ``fetchInfo`` to reset the fetch type to the database type.
     * - ``oracledb.NUMBER``
       - 2010
       - ``oracledb.DB_TYPE_NUMBER``
-      -
+      - No relevant notes
     * - ``oracledb.NCLOB``
       - 2018
       - ``oracledb.DB_TYPE_NCLOB``
       - .. versionadded:: 4.2
     * - ``oracledb.STRING``
       - 2001
       - ``oracledb.DB_TYPE_VARCHAR``
-      -
+      - No relevant notes
 
 .. _oracledbconstantsbinddir:
 

doc/src/user_guide/connection_handling.rst

@@ -4189,7 +4189,7 @@ corresponding option values are listed in the table below.
       - Optional Parameters for This Option Value
     * - Default Azure Credential
       - AZURE_DEFAULT (also used when the Authentication method is not set)
-      -
+      - No required parameters for this option value
       - AZURE_CLIENT_ID
 
         AZURE_CLIENT_SECRET
@@ -4206,19 +4206,19 @@ corresponding option values are listed in the table below.
         AZURE_CLIENT_SECRET
 
         AZURE_TENANT_ID
-      -
+      - No optional parameters for this option value
     * - Service Principal with client certificate
       - AZURE_SERVICE_PRINCIPAL
       - AZURE_CLIENT_ID
 
         AZURE_CLIENT_CERTIFICATE_PATH
 
         AZURE_TENANT_ID
-      -
+      - No optional parameters for this option value
     * - Managed Identity
       - AZURE_MANAGED_IDENTITY
       - AZURE_MANAGED_IDENTITY_CLIENT_ID - required only if user assigned
-      -
+      - No optional parameters for this option value
 
 Note that the Azure service principal with client certificate overrides Azure
 service principal with client secret.
@@ -4509,12 +4509,12 @@ corresponding option values are listed in the table below.
         OCI_PROFILE_PATH
     * - Instance Principal Authentication
       - OCI_INSTANCE_PRINCIPAL
-      -
-      -
+      - No optional configuration for this option value
+      - No optional parameters for this option value
     * - Resource Principal Authentication
       - OCI_RESOURCE_PRINCIPAL
-      -
-      -
+      - No optional configuration for this option value
+      - No optional parameters for this option value
 
 See `Authentication Parameters for OCI Object Storage <https://www.oracle.com/
 pls/topic/lookup?ctx=dblatest&id=GUID-EB94F084-0F3F-47B5-AD77-D111070F7E8D>`__

examples/vectortype2.js

@@ -87,8 +87,8 @@ async function run() {
     let i = 0;
     const binds = [], num = 4;
     const expectedArrays = [
-      [1, 2, 3],
       [4, 5, 6],
+      [1, 2, 3],
       [42, 52, 613],
       [-1, -2, -3]
     ];
@@ -116,13 +116,14 @@ async function run() {
 
     // Calculate distance to a given embedding
     const vecQuery = new Float64Array([3, 1, 2]);
-    let expectedValues = [6, 33, 377443, 50];
+    let expectedValues = ['0.1167', '0.2143', '0.3915', '1.7857'];
     result = await connection.execute(
       `select vector_distance (embedding, :1) from ${tableName}`, [vecQuery]);
     console.log(`Distance from Input Embedding `, [3, 1, 2]);
     console.log(result.rows);
+    console.log(result.rows[0]['VECTOR_DISTANCE(EMBEDDING,:1)']);
     for (i = 0; i < num; i++) {
-      assert.deepStrictEqual(result.rows[i], {"VECTOR_DISTANCE(EMBEDDING,:1)": expectedValues[i]});
+      assert.deepStrictEqual(result.rows[i]['VECTOR_DISTANCE(EMBEDDING,:1)'].toFixed(4), expectedValues[i]);
     }
 
     // Calculate top 3 similarity search to a given embedding
@@ -133,35 +134,35 @@ async function run() {
     console.log(result.rows);
     assert.deepStrictEqual(result.rows[0].EMBEDDING, expectedArrays[0]);
     assert.deepStrictEqual(result.rows[1].EMBEDDING, expectedArrays[1]);
-    assert.deepStrictEqual(result.rows[2].EMBEDDING, expectedArrays[3]);
+    assert.deepStrictEqual(result.rows[2].EMBEDDING, expectedArrays[2]);
 
     // Nearest Neighbours (distance < 34) for a given embedding [3,1,2]
     // gives [1,2,3] and [4,5,6]
     console.log('Nearest Neighbours with distance < 34:');
     result = await connection.execute(
-      `select * from ${tableName} where vector_distance (embedding, vector('[3,1,2]', 3)) < 34 `);
+      `select * from ${tableName} where vector_distance (embedding, vector('[3,1,2]', 3, float64)) < 34 `);
     console.log(result.rows);
     assert.deepStrictEqual(result.rows[0].EMBEDDING, expectedArrays[0]);
     assert.deepStrictEqual(result.rows[1].EMBEDDING, expectedArrays[1]);
 
     // Cosine Distance
     result = await connection.execute(
-      `select cosine_distance (embedding, vector('[3,1,2]', 3)) as cosdistance from ${tableName}`);
-    expectedValues = [0.2142857142857143, 0.11673988938389968, 0.3914785344302253, 1.7857142857142856];
+      `select cosine_distance (embedding, vector('[3,1,2]', 3, float64)) as cosdistance from ${tableName}`);
+    expectedValues = ['0.1167', '0.2143',  '0.3915', '1.7857'];
     for (i = 0; i < num; i++) {
-      assert.deepStrictEqual(result.rows[i], {"COSDISTANCE": expectedValues[i]});
+      assert.deepStrictEqual(result.rows[i]['COSDISTANCE'].toFixed(4), expectedValues[i]);
     }
     console.log(`Cosine Distance from Input Embedding `, [3, 1, 2]);
     console.log(result.rows);
 
     // inner product
     result = await connection.execute(
-      `select inner_product (embedding, vector('[3,1,2]', 3)) from ${tableName}`);
+      `select inner_product (embedding, vector('[3,1,2]', 3, float64)) from ${tableName}`);
     console.log(`Inner product with Input Embedding `, [3, 1, 2]);
     console.log(result.rows);
-    expectedValues = [11, 29, 1404, -11];
+    expectedValues = [29, 11, 1404, -11];
     for (i = 0; i < num; i++) {
-      assert.deepStrictEqual(result.rows[i], {"INNER_PRODUCT(EMBEDDING,VECTOR('[3,1,2]',3))": expectedValues[i]});
+      assert.deepStrictEqual(result.rows[i], {"INNER_PRODUCT(EMBEDDING,VECTOR('[3,1,2]',3,FLOAT64))": expectedValues[i]});
     }
   } catch (err) {
     console.error(err);

test/dataTypeVector1.js

@@ -396,6 +396,8 @@ describe('294. dataTypeVector1.js', function() {
   }); // 294.13
 
   it('294.14 insert uint8 typed array to float64 vector column', async function() {
+    if (!isVectorBinaryRunnable) this.skip();
+
     // Create an UInt8Array
     const uInt8Arr = new Uint8Array([3, 2, 3, 4, 5, 6, 3, 4, 5, 5]);
     // Bind the UInt8Array using oracledb.DB_TYPE_VECTOR
@@ -417,6 +419,8 @@ describe('294. dataTypeVector1.js', function() {
   }); // 294.14
 
   it('294.15 insert uint8arr typed array to flex vector column', async function() {
+    if (!isVectorBinaryRunnable) this.skip();
+
     // Create an UInt8Array
     const uInt8Arr = new Uint8Array([126, 125, -126, -23, 11, 12, -11, -12, 10, 10]);
 
@@ -434,6 +438,8 @@ describe('294. dataTypeVector1.js', function() {
   }); // 294.15
 
   it('294.16 insert uInt8arr typed array to float32 vector column', async function() {
+    if (!isVectorBinaryRunnable) this.skip();
+
     // Create an UInt8Array
     const Uint8arr = new Uint8Array([3]);
 

test/dataTypeVector2.js

@@ -79,7 +79,7 @@ describe('295. dataTypeVector2.js', function() {
   });
 
   beforeEach(async function() {
-    await connection.execute(`TRUNCATE TABLE ${tableName}`);
+    await connection.execute(`DELETE FROM ${tableName}`);
     oracledb.fetchTypeHandler = function(metadata) {
       if (metadata.dbType === oracledb.DB_TYPE_VECTOR) {
         const myConverter = (v) => {