Documentation and Test case updates for the latest code changes

doc/src/api_manual/dbobject.rst

@@ -94,6 +94,14 @@ The properties of a DbObject object are listed below.
     This read-only property is a string which identifies the name of the
     Oracle Database object or collection.
 
+.. attribute:: dbObject.packageName
+
+    .. versionadded:: 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*.
+
 .. attribute:: dbObject.schema
 
     This read-only property is a string which identifies the schema owning

doc/src/api_manual/sodacollection.rst

@@ -52,51 +52,18 @@ SodaCollection Methods
 
         promise = createIndex(Object indexSpec);
 
-    Creates an index on a SODA collection, to improve the performance of
+    Creates an index on a SODA collection, to improve the performance of SODA
-    SODA query-by-examples (QBE) or enable text searches. An index is
+    query-by-examples (QBE) or enable text searches. See :ref:`sodaindexes`
-    defined by a specification, which is a JSON object that specifies how
+    for information on indexing.
-    particular QBE patterns are to be indexed for quicker matching.
 
     Note that a commit should be performed before attempting to create an
     index.
 
-    Different index types can be used:
-
-    - B-tree: used to speed up query-by-example (QBE)
-      :meth:`sodaOperation.filter()` searches.
-    - JSON search: required for text searches using the ``$contains``
-      operator in QBEs. Also improves QBE filter operation performance.
-      Note a B-tree index will perform better for non-text searches.
-    - GeoSpatial: for speeding up QBEs that do GeoJSON queries.
-
     If :attr:`oracledb.autoCommit` is *true*, and ``createIndex()`` succeeds,
     then any open user transaction is committed.
     Note SODA DDL operations do not commit an open transaction the way that
     SQL always does for DDL statements.
 
-    See `Overview of SODA
-    Indexing <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
-    4848E6A0-58A7-44FD-8D6D-A033D0CCF9CB>`__.
-
-    As an example, if a collection has these documents::
-
-        {"name": "Chris"}
-        {"name": "Venkat"}
-        {"name": "Srinath"}
-
-    Then a B-tree index could be created with:
-
-    .. code-block:: javascript
-
-        indexSpec = {name: "myIndex", fields: [{path: "name"}]};
-        await collection.createIndex(indexSpec);
-
-    This index would improve the performance of QBEs like:
-
-    .. code-block:: javascript
-
-        d = await collection.find().filter({name: "Venkat"}).getOne();
-
     The parameters of the ``sodaCollection.createIndex()`` method are:
 
     .. _sodacollcreateindexparams:
@@ -140,6 +107,8 @@ SodaCollection Methods
         * - Error ``error``
           - If ``createIndex()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
 
+    See :ref:`sodaindexes` for more information.
+
 .. method:: sodaCollection.drop()
 
     .. versionadded:: 3.0
@@ -276,6 +245,8 @@ SodaCollection Methods
         * - Object ``result``
           - If dropping the index succeeded, ``dropped`` will be *true*. If no index was found, ``dropped`` will be *false*.
 
+    See :ref:`sodaindexes` for an example.
+
 .. method:: sodaCollection.find()
 
     .. versionadded:: 3.0
@@ -302,6 +273,46 @@ SodaCollection Methods
     See :ref:`Simple Oracle Document Access (SODA) <sodaoverview>` for more
     examples.
 
+.. method:: sodaCollection.listIndexes()
+
+    .. versionadded:: 6.2
+
+    **Promise:**::
+
+        promise = listIndexes();
+
+    Retrieves all the indexes from a SODA collection. This method returns an
+    array of objects that contains the index specifications.
+
+    This method requires Oracle Client 21.3 or later (or Oracle Client 19 from
+    19.13).
+
+    **Callback:**
+
+    If you are using the callback programming style::
+
+        listIndexes(function(Error error, Array listIndexes){});
+
+    The parameters of the callback function
+    ``function(Error error, Array listIndexes)`` are:
+
+    .. list-table-with-summary::
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 15 30
+        :summary: The first column displays the callback function parameter.
+          The second column displays the description of the parameter.
+
+        * - Callback Function Parameter
+          - Description
+        * - Error ``error``
+          - If ``listIndexes()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
+        * - Array ``listIndexes``
+          - An array of objects, each containing the index specifications of the SODA collection.
+
+    See :ref:`Retrieving All Index Specifications <listindexes>` for an example.
+
 .. _sodaoperationclass:
 
 SodaOperation Class
@@ -481,8 +492,8 @@ with the key “c” is matched.
     If this method is specified in conjunction with a write operation, then
     this method is ignored.
 
-    This method is only supported in Oracle Client 21.3 and Oracle Client
+    This method requires Oracle Client 21.3 or later (or Oracle Client 19 from
-    19.11 (or later).
+    19.11).
 
 .. method:: sodaOperation.skip()
 

doc/src/release_notes.rst

@@ -10,6 +10,12 @@ For deprecated and desupported features, see :ref:`Deprecations and desupported
 node-oracledb `v6.2.0 <https://github.com/oracle/node-oracledb/compare/v6.1.0...v6.2.0>`__ (TBD)
 ------------------------------------------------------------------------------------------------
 
+Common Changes
+++++++++++++++
+
+#)  Added :attr:`~dbObject.packageName` property to
+    :ref:`DbObject Class<dbobjectclass>`.
+
 Thin Mode Changes
 ++++++++++++++++++
 
@@ -34,8 +40,6 @@ Thin Mode Changes
 Thick Mode Changes
 ++++++++++++++++++
 
-#)  Added ``packageName`` attribute to :ref:`DbObject Class<dbobjectclass>`.
-
 #)  Added new property :ref:`binaryDir <odbinitoracleclientattrsopts>` to the
     options passed to :meth:`~oracledb.initOracleClient()` which indicates the
     name of the directory that contains the node-oracledb :ref:`Thick mode
@@ -46,8 +50,8 @@ Thick Mode Changes
     property. See `node-oracledb public Slack channel
     <https://node-oracledb.slack.com/ archives/CCM8AMSF7/p1694544451676639>`__.
 
-#)  Added ``listIndexes()`` method to fetch all the current indexes from
+#)  Added :meth:`sodaCollection.listIndexes()` method to fetch all the current
-    a SODA collection.
+    indexes from a SODA collection.
 
 #)  Added :meth:`sodaOperation.lock()` method to disable modification of SODA
     documents by other connections.

doc/src/user_guide/soda.rst

@@ -223,8 +223,8 @@ Collections can be created like:
     }
 
 This example creates a collection that, by default, allows JSON
-documents to be stored. A non-unique B-tree index is created on the
+documents to be stored. A non-unique :ref:`B-tree index <sodaindexes>` is
-``address.city`` path to improve search performance.
+created on the ``address.city`` path to improve search performance.
 
 If the collection name passed to
 :meth:`sodaDatabase.createCollection()` already exists, it
@@ -244,7 +244,7 @@ metadata.
 
 .. _accessingsodadocuments:
 
-Creating and Accessing SODA documents
+Creating and Accessing SODA Documents
 =====================================
 
 To insert a document into an opened collection, a JavaScript object that
@@ -558,6 +558,137 @@ Some QBE examples are:
   See `Overview of QBE Spatial Operators <https://www.oracle.com/pls/topic/
   lookup?ctx=dblatest&id=GUID-12994E27-DA98-40C7-8D4F-84341106F8D9>`__.
 
+.. _sodaindexes:
+
+Creating and Dropping SODA Indexes
+==================================
+
+Indexing can improve the performance of SODA query-by-examples (QBE) or enable
+text searches. An index is defined by a specification, which is a JSON object
+that specifies how particular QBE patterns are to be indexed for quicker
+matching.
+
+Note that a commit should be performed before attempting to create an
+index.
+
+Each index specification is uniquely identified by the ``name`` field. The
+different index types that you can specify are:
+
+- B-tree: Used to speed up query-by-example (QBE)
+  :meth:`sodaOperation.filter()` searches. For this index type, you must
+  specify the ``fields`` field in the index specification.
+
+- GeoSpatial: Used for speeding up QBEs that do GeoJSON queries. For this
+  index type, you must specify the ``spatial`` field in the index
+  specification.
+
+- JSON search: Required for text searches using the ``$contains``
+  operator in QBEs. Also, improves QBE filter operation performance. For this
+  index type, you must not specify the ``fields`` and ``spatial`` fields in
+  the index specification. Note that a B-tree index will perform better for
+  non-text searches.
+
+See `Overview of SODA Indexing <https://www.oracle.com/pls/topic/lookup?ctx=
+dblatest&id=GUID-4848E6A0-58A7-44FD-8D6D-A033D0CCF9CB>`__.
+
+As an example, if a collection has these documents::
+
+    {"name": "Chris"}
+    {"name": "Venkat"}
+    {"name": "Srinath"}
+
+You must first specify the type of index that you want by creating a SODA
+index specification. For example, to create a B-tree index specification, you
+need to specify the ``fields`` field:
+
+.. code-block:: javascript
+
+    indexSpec = {name: "myIndex", fields: [{path: "name"}]};
+
+Then use that index specification to create the B-tree index using
+:meth:`sodaCollection.createIndex()`:
+
+.. code-block:: javascript
+
+    await collection.createIndex(indexSpec);
+
+This index would improve the performance of QBEs like:
+
+.. code-block:: javascript
+
+    d = await collection.find().filter({name: "Venkat"}).getOne();
+
+To drop a specific index on a SODA collection, use
+:meth:`sodaCollection.dropIndex()`:
+
+.. code-block:: javascript
+
+    await collection.dropIndex("myIndex");
+
+.. _listindexes:
+
+Retrieving All Index Specifications in a Collection
+---------------------------------------------------
+
+You can retrieve all the index specifications defined for the documents in a
+collection using :meth:`sodaCollection.listIndexes()`. For example:
+
+.. code-block:: javascript
+
+    // Create a new SODA collection
+    const collection = await soda.createCollection("mycollection");
+
+    // Create new index specifications
+    const indexArr = [
+      {
+        "name": "HOME_IDX",
+        "fields": [
+          {
+            "path": "home",
+            "datatype": "string",
+            "order": "asc"
+          }
+        ]
+      },
+      {
+        "name": "OFFICE_IDX",
+        "fields": [
+          {
+            "path": "office",
+            "datatype": "string",
+            "order": "asc"
+          }
+        ]
+      }
+    ];
+
+To create new indexes for each of the index specifications in ``IndexArr``:
+
+.. code-block:: javascript
+
+    await collection.createIndex(indexArr[0]);
+    await collection.createIndex(indexArr[1]);
+
+To retrieve all the index specifications in the collection:
+
+.. code-block:: javascript
+
+    // Retrieve list of indexes in a collection
+    const fetchedIndexArr  = await collection.listIndexes();
+
+    //  Sort the index specification names in alphabetical order
+    fetchedIndexArr.sort(function(a, b) {
+      return a.name.localeCompare(b.name);
+    });
+
+    console.log ("fetchIndexArr-0 " + JSON.stringify(fetchedIndexArr[0]));
+    console.log ("fetchIndexArr-1 " + JSON.stringify(fetchedIndexArr[1]));
+
+This prints an output such as::
+
+    fetchIndexArr-0 {"name":"HOME_IDX","schema":"SCOTT","tableName":"MYCOLLECTION","tableSchemaName":"SCOTT","indexNulls":false,"unique":false,"lax":false,"scalarRequired":false,"fields":[{"path":"home","dataType":"VARCHAR2","maxLength":2000,"order":"ASC"}]}
+    fetchIndexArr-1 {"name":"OFFICE_IDX","schema":"SCOTT","tableName":"MYCOLLECTION","tableSchemaName":"SCOTT","indexNulls":false,"unique":false,"lax":false,"scalarRequired":false,"fields":[{"path":"office","dataType":"VARCHAR2","maxLength":2000,"order":"ASC"}]}
+
 .. _sodatextsearches:
 
 SODA Text Searches

test/currentSchema.js

@@ -83,14 +83,13 @@ describe('191. currentSchema.js', function() {
   }); // 191.2
 
   it('191.3 Negative - can not set non-existent schema', async () => {
-
+    let conn;
     async function setInvalidSchema() {
-      const conn = await oracledb.getConnection(dbConfig);
+      conn = await oracledb.getConnection(dbConfig);
 
       const schema = "foo";
       conn.currentSchema = schema;
-
+      await conn.execute('SELECT 1 FROM DUAL');
-      await conn.close();
     }
 
     await assert.rejects(
@@ -100,6 +99,7 @@ describe('191. currentSchema.js', function() {
     // ORA-01435: user does not exist
     // ORA-28726: set current schema operation failed
 
+    await conn.close();
   }); // 191.3
 
 });