Documentation and Test case updates for the latest code changes
This commit is contained in:
parent
d045f4c368
commit
86b1c61ec8
|
@ -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
|
||||
|
|
|
@ -52,51 +52,18 @@ SodaCollection Methods
|
|||
|
||||
promise = createIndex(Object indexSpec);
|
||||
|
||||
Creates an index on a SODA collection, to 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.
|
||||
Creates an index on a SODA collection, to improve the performance of SODA
|
||||
query-by-examples (QBE) or enable text searches. See :ref:`sodaindexes`
|
||||
for information on indexing.
|
||||
|
||||
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
|
||||
19.11 (or later).
|
||||
This method requires Oracle Client 21.3 or later (or Oracle Client 19 from
|
||||
19.11).
|
||||
|
||||
.. method:: sodaOperation.skip()
|
||||
|
||||
|
|
|
@ -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
|
||||
a SODA collection.
|
||||
#) Added :meth:`sodaCollection.listIndexes()` method to fetch all the current
|
||||
indexes from a SODA collection.
|
||||
|
||||
#) Added :meth:`sodaOperation.lock()` method to disable modification of SODA
|
||||
documents by other connections.
|
||||
|
|
|
@ -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
|
||||
``address.city`` path to improve search performance.
|
||||
documents to be stored. A non-unique :ref:`B-tree index <sodaindexes>` is
|
||||
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
|
||||
|
|
|
@ -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.close();
|
||||
await conn.execute('SELECT 1 FROM DUAL');
|
||||
}
|
||||
|
||||
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
|
||||
|
||||
});
|
||||
|
|
Loading…
Reference in New Issue