dnrops
/
node-oracledb
mirror of https://github.com/oracle/node-oracledb
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Copyright updates, documentation and test case additions

This commit is contained in:
Sharad Chandran R 2024-03-11 12:46:16 +05:30
parent b287d414cb
commit 4dd4721814
31 changed files with 989 additions and 973 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.npmignore
View File

@ -13,8 +13,6 @@ Makefile.win32
/examples/*
!/examples/example.js
!/examples/dbconfig.js
!/examples/vectortype1.js
!/examples/vectortype2.js
/test
/build/Release/oracledb.node
/build/oracledb.target.mk

534
doc/api.md
View File

File diff suppressed because it is too large Load Diff

687
doc/src/api_manual/sodacollection.rst
View File

@ -273,653 +273,6 @@ 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
===================
You can chain together SodaOperation methods to specify read or write
operations against a collection.
Non-terminal SodaOperation methods return the same object on which they
are invoked, allowing them to be chained together.
A terminal SodaOperation method always appears at the end of a method
chain to execute the operation.
A SodaOperation object is an internal object. You should not directly
modify its properties.
.. _sodaoperationclassnonterm:
Non-terminal SodaOperation Methods
----------------------------------
Non-terminal SodaOperation methods are chained together to set criteria
that documents must satisfy. At the end of the chain, a single terminal
method specifies the operation to be performed on the matching
documents.
When a non-terminal method is repeated, the last one overrides the
earlier one. For example if ``find().key("a").key("b")...`` was used,
then only documents with the key “b” are matched. If
``find().keys(["a","b"]).key("c")...`` is used, then only the document
with the key “c” is matched.
.. method:: sodaOperation.fetchArraySize()
.. versionadded:: 5.0
.. code-block:: javascript
fetchArraySize(Number size)
Sets the size of an internal buffer used for fetching
documents from a collection with the terminal SodaOperation methods
:meth:`~sodaOperation.getCursor()` and
:meth:`~sodaOperation.getDocuments()`. Changing
``size`` may affect performance but does not affect how many documents
are returned.
If ``fetchArraySize()`` is not used, the size defaults to the current
value of :attr:`oracledb.fetchArraySize`.
For node-oracledb examples, see :ref:`SODA Query-by-Example Searches for
JSON Documents <sodaqbesearches>`.
It requires Oracle Client 19.5 or later, and Oracle Database 18.3 or later.
.. method:: sodaOperation.filter()
.. versionadded:: 3.0
.. code-block:: javascript
filter(Object filterSpec)
Sets a filter specification for the operation, allowing for complex
document queries and ordering of JSON documents. Filter specifications
can include comparisons, regular expressions, logical, and spatial
operators, among others. See `Overview of SODA Filter Specifications
(QBEs) <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
CB09C4E3-BBB1-40DC-88A8-8417821B0FBE>`__ and `SODA Filter Specifications
(Reference) <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
8DDB51EB-D80F-4476-9ABF-D6860C6214D1>`__.
For node-oracledb examples, see :ref:`SODA Query-by-Example Searches for JSON
Documents <sodaqbesearches>`.
.. method:: sodaOperation.hint()
.. versionadded:: 5.2
.. code-block:: javascript
hint(String hint)
The ``hint()`` value can be used to pass an Oracle hint to :ref:`terminal
SodaOperation Methods <sodaoperationclassterm>`. It is string in the
same format as a `SQL
hint <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
C558F7CF-446E-4078-B045-0B3BB026CB3C>`__
but without any comment characters, for example ``hint("MONITOR")``.
Pass only the hint ``"MONITOR"`` (turn on monitoring) or
``"NO_MONITOR"`` (turn off monitoring). See the Oracle Database SQL
Tuning Guide documentation `MONITOR and NO_MONITOR
Hints <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
19E0F73C-A959-41E4-A168-91E436DEE1F1>`__ and `Monitoring Database
Operations <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID
-C941CE9D-97E1-42F8-91ED-4949B2B710BF>`__ for more information.
It requires Oracle Client 21.3 or higher (or Oracle Client 19 from
19.11).
.. method:: sodaOperation.key()
.. versionadded:: 3.0
.. code-block:: javascript
key(String value)
Sets the key value to be used to match a document for the operation. Any
previous calls made to this method or :meth:`~sodaOperation.keys()`
will be ignored.
SODA document keys are unique.
.. method:: sodaOperation.keys()
.. versionadded:: 3.0
.. code-block:: javascript
keys(Array value)
Sets the keys to be used to match multiple documents for the operation.
Any previous calls made to this method or :meth:`sodaOperation.key()`
will be ignored.
SODA document keys are unique.
A maximum of 1000 keys can be used.
.. method:: sodaOperation.limit()
.. versionadded:: 3.0
.. code-block:: javascript
limit(Number n)
Sets the maximum number of documents that a terminal method will apply
to. The value of ``n`` must be greater than 0. The limit is applied to
documents that match the other SodaOperation criteria. The ``limit()``
method only applies to SodaOperation read operations like
``getCursor()`` and ``getDocuments()``. If a filter ``$orderby`` is not
used, the document order is internally defined.
The ``limit()`` method cannot be used in conjunction with
:meth:`~sodaOperation.count()`.
.. method:: sodaOperation.lock()
.. versionadded:: 6.2
.. code-block:: javascript
lock()
Locks the documents fetched from the collection.
Using ``lock()`` allows for pessimistic locking, that is, only the current
user that performed the lock can modify the documents in the collection.
Other users can only perform operations on these documents once they are
unlocked. The functionality of this method is equivalent to the
``SELECT FOR UPDATE`` clause.
The documents can be unlocked with an explicit call to
:meth:`~connection.commit()` or :meth:`~connection.rollback()` on the
connection. Ensure that the :attr:`oracledb.autoCommit` is
set to *false* for the connection. Otherwise, the documents will be
unlocked immediately after the operation is complete.
This method should only be used with read operations (other than
:meth:`~sodaOperation.count()`), and should not be used in conjunction
with non-terminal methods :meth:`~sodaOperation.skip()` and
:meth:`~sodaOperation.limit()`.
If this method is specified in conjunction with a write operation, then
this method is ignored.
This method requires Oracle Client 21.3 or later (or Oracle Client 19 from
19.11).
.. method:: sodaOperation.skip()
.. versionadded:: 3.0
.. code-block:: javascript
skip(Number n)
Sets the number of documents that will be skipped before the terminal
method is applied. The value of ``n`` must be greater or equal to 0. The
skip applies to documents that match the other SodaOperation criteria.
If a filter ``$orderby`` is not used, the document order (and hence
which documents are skipped) is internally defined.
The ``skip()`` method only applies to SodaOperation read operations like
``getDocuments()``. It cannot be used with
:meth:`~sodaOperation.count()`.
.. method:: sodaOperation.version()
.. versionadded:: 3.0
.. code-block:: javascript
version(String value)
Sets the document version that documents must have.
This is typically used in conjunction with a key, for example
``collection.find().key("k").version("v").replaceOne(doc)``.
Using ``version()`` allows for optimistic locking, so that the
subsequent SodaOperation terminal method does not affect a document that
someone else has already modified. If the requested document version is
not matched, then your terminal operation will not impact any document.
The application can then query to find the latest document version and
apply any desired change.
.. _sodaoperationclassterm:
Terminal SodaOperation Methods
------------------------------
A terminal SodaOperation method operates on the set of documents that
satisfy the criteria specified by previous non-terminal methods in the
method chain. Only one terminal method can be used in each chain.
.. method:: sodaOperation.count()
.. versionadded:: 3.0
**Promise**::
promise = count();
Finds the number of documents matching the given SodaOperation query
criteria.
If ``skip()`` or ``limit()`` are set, then ``count()`` will return an
error.
If :attr:`oracledb.autoCommit` is *true*, and ``count()`` succeeds,
then any open transaction on the connection is committed.
**Callback**:
If you are using the callback programming style::
count(function (Error error, Object result){});
The parameters of the callback function
``function (Error error, Object result)`` 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 ``count()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
* - Object ``result``
- The `result` object contains one attribute::
Number count
The number of documents matching the SodaOperation criteria.
Due to Node.js type limitations, the largest ``count`` value will be 232 - 1, even if more rows exist. Larger values will wrap.
.. method:: sodaOperation.getCursor()
.. versionadded:: 3.0
**Promise**::
promise = getCursor()
Returns a :ref:`SodaDocumentCursor <sodadocumentcursorclass>` for
documents that match the SodaOperation query criteria. The cursor can be
iterated over with :meth:`sodaDocumentCursor.getNext()` to access
each :ref:`SodaDocument <sodadocumentclass>`.
When the application has completed using the cursor it must be closed
with :meth:`sodaDocumentCursor.close()`.
If the number of documents is known to be small, it is recommended to
use :meth:`sodaOperation.getDocuments()` instead.
If :attr:`oracledb.autoCommit` is *true*, and
``getCursor()`` succeeds, then any open transaction on the connection is
committed.
**Callback**:
If you are using the callback programming style::
getCursor(function(Error error, SodaDocumentCursor cursor){});
The parameters of the callback function
``function(Error error, SodaDocumentCursor cursor)`` 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 ``getCursor()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
* - SodaDocumentCursor ``cursor``
- A cursor that can be iterated over to access SodaDocument objects matching the SodaOperation search criteria.
.. method:: sodaOperation.getDocuments()
.. versionadded:: 3.0
**Promise**::
promise = getDocuments();
Gets an array of :ref:`SodaDocuments <sodadocumentclass>` matching the
SodaOperation query criteria. An empty array will be returned when no
documents match.
Where the number of matching documents is known to be small, this API
should be used in preference to :meth:`sodaOperation.getCursor()`.
If :attr:`oracledb.autoCommit` is *true*, and ``getDocuments()``
succeeds, then any open transaction on the connection is committed.
**Callback**:
If you are using the callback programming style::
getDocuments(function(Error error, Array documents){});
The parameters of the callback function
``function(Error error, Array documents)`` 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 ``getDocuments()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
* - Array ``documents``
- An array of SodaDocuments that match the SodaOperation query criteria.
.. method:: sodaOperation.getOne()
.. versionadded:: 3.0
**Promise**::
promise = getOne();
Obtains one document matching the SodaOperation query criteria. If the
criteria match more than one document, then only the first is returned.
Typically ``getone()`` should be used with ``key(k)`` or
``key(k).version(v)`` to ensure only one document is matched.
If :attr:`oracledb.autoCommit` is *true*, and ``getOne()`` succeeds, then
any open transaction on the connection is committed.
**Callback**:
If you are using the callback programming style::
getOne(function(Error error, SodaDocument document){});
The parameters of the callback function
``function(Error error, SodaDocument document)`` 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 ``getOne()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
* - SodaDocument ``document``
- One SodaDocument that matches the sodaOperation query criteria. If no document is found, then ``document`` will be undefined.
.. method:: sodaOperation.remove()
.. versionadded:: 3.0
**Promise**::
promise = remove();
Removes a set of documents matching the SodaOperation query criteria.
Note settings from ``skip()`` and ``limit()`` non-terminals are ignored
because they only apply to read operations.
If :attr:`oracledb.autoCommit` is *true*, and ``remove()`` succeeds, then
removal and any open transaction on the connection is committed.
**Callback**:
If you are using the callback programming style::
remove(function(Error error, Object result){});
The parameters of the callback function
``function(Error error, Object result)`` 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 ``remove()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
* - Object ``result``
- The `result` object contains one attribute::
result.count
The number of documents removed from the collection.
Due to Node.js type limitations, the largest ``count`` value will be 232 - 1, even if Oracle Database removed more rows. Larger values will wrap.
.. method:: sodaOperation.replaceOne()
.. versionadded:: 3.0
**Promise**::
promise = replaceOne(Object newDocumentContent);
promise = replaceOne(SodaDocument newSodaDocument);
Replaces a document in a collection. The input document can be either a
JavaScript object representing the data content, or it can be an
existing :ref:`SodaDocument <sodadocumentclass>`.
The ``mediaType`` document component and content of the document that
matches the SodaOperation query criteria will be replaced by the content
and any ``mediaType`` document component of the new document. Any other
document components will not be affected. The ``lastModified`` and
``version`` document components of the replaced document will be
updated.
The ``key()`` non-terminal must be used when using ``replaceOne()``.
No error is reported if the operation criteria do not match any
document.
Note settings from ``skip()`` and ``limit()`` non-terminals are ignored
because they only apply to read operations.
If :attr:`oracledb.autoCommit` is *true*, and ``replaceOne()`` succeeds,
then any open transaction on the connection is committed.
The parameters of the ``sodaOperation.replaceOne()`` method are:
.. _replaceone:
.. list-table-with-summary:: sodaOperation.replaceOne() Parameters
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the parameter. The second column
displays the data type of the parameter. The third column displays
the description of the parameter.
* - Parameter
- Data Type
- Description
* - ``newDocumentContent`` or ``newSodaDocument``
- Object or SodaDocument
- The new document. See :meth:`sodaCollection.insertOne()`, which has the same semantics for the document.
**Callback**:
If you are using the callback programming style::
replaceOne(Object newDocumentContent, function(Error error, Object result){});
replaceOne(SodaDocument newSodaDocument, function(Error error, Object result){});
See :ref:`replaceone` for information on the parameters.
The parameters of the callback function
``function(Error error, Object result)`` 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 ``replaceOne()`` succeeds, ``error`` is NULL. It is not an error if no document is replaced. If an error occurs, then ``error`` contains the error message.
* - Object ``result``
- The `result` object contains one attribute::
result.replaced
This attribute will be *true* if the document was successfully replaced, *false* otherwise.
.. method:: sodaOperation.replaceOneAndGet()
.. versionadded:: 3.0
**Promise**::
promise = replaceOneAndGet(Object newDocumentContent);
promise = replaceOneAndGet(SodaDocument newSodaDocument);
Replaces a document in a collection similar to
:meth:`sodaOperation.replaceOne()`, but also returns
the result document which contains all :ref:`SodaDocument
<sodadocumentclass>` components (key, version, etc.)
except for content. Content itself is not returned for performance
reasons. The result document has new values for components that are
updated as part of the replace operation (such as version, last-modified
timestamp, and media type)
If :attr:`oracledb.autoCommit` is *true*, and ``replaceOneAndGet()``
succeeds, then any open transaction on the connection is committed.
The parameters of the ``sodaOperation.replaceOneAndGet()`` method are:
.. _replaceoneandget:
.. list-table-with-summary:: sodaOperation.replaceOneAndGet() Parameters
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the parameter. The second column
displays the data type of the parameter. The third column displays
the description of the parameter.
* - Parameter
- Data Type
- Description
* - ``newDocumentContent`` or ``newSodaDocument``
- Object or SodaDocument
- The new document. See :meth:`sodaCollection.insertOne()`, which has the same semantics for the document.
**Callback**:
If you are using the callback programming style::
replaceOneAndGet(Object newDocumentContent, function(Error error, SodaDocument updatedDocument){});
replaceOneAndGet(SodaDocument newSodaDocument, function(Error error, SodaDocument updatedDocument){});
See :ref:`replaceoneandget` for information on the parameters.
The parameters of the callback function
``function(Error error, SodaDocument updatedDocument)`` 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 ``replaceOneAndGet()`` succeeds, ``error`` is NULL. It is not an error if no document is replaced. If an error occurs, then ``error`` contains the error message.
* - SodaDocument ``updatedDocument``
- The updated :ref:`SodaDocument <sodadocumentclass>` if replacement was successful, otherwise ``updatedDocument`` will be undefined.
The ``lastModified`` and ``version`` attributes of the stored SodaDocument will be updated. The ``mediaType`` attribute and the content will be replaced. Other attributes of ``newSodaDocument`` are ignored.
Note for performance reasons, ``updatedDocument`` will not have document content and cannot itself be passed directly to SODA insert or replace methods.
.. method:: sodaCollection.getDataGuide()
.. versionadded:: 3.0
@ -1207,6 +560,46 @@ method chain. Only one terminal method can be used in each chain.
Note for performance reasons, ``document`` will not have document content and cannot itself be passed directly to SODA insert or replace methods.
.. 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.
.. method:: sodaCollection.save()
.. versionadded:: 5.0

616
doc/src/api_manual/sodaoperation.rst Normal file
View File

@ -0,0 +1,616 @@
.. _sodaoperationclass:
************************
API: SodaOperation Class
************************
You can chain together SodaOperation methods to specify read or write
operations against a collection.
.. note::
In this release, SODA is only supported in the node-oracledb Thick mode.
See :ref:`enablingthick`.
SODA can be used with Oracle Database 18.3 and above, when node-oracledb
uses Oracle Client 18.5 or Oracle Client 19.3, or later.
:ref:`Non-terminal SodaOperation methods <sodaoperationclassnonterm>` return
the same object on which they are invoked, allowing them to be chained
together.
A :ref:`terminal SodaOperation method <sodaoperationclassterm>` always appears
at the end of a method chain to execute the operation.
A SodaOperation object is an internal object. You should not directly
modify its properties.
.. _sodaoperationclassnonterm:
Non-terminal SodaOperation Methods
==================================
Non-terminal SodaOperation methods are chained together to set criteria
that documents must satisfy. At the end of the chain, a single terminal
method specifies the operation to be performed on the matching
documents.
When a non-terminal method is repeated, the last one overrides the
earlier one. For example if ``find().key("a").key("b")...`` was used,
then only documents with the key “b” are matched. If
``find().keys(["a","b"]).key("c")...`` is used, then only the document
with the key “c” is matched.
.. method:: sodaOperation.fetchArraySize()
.. versionadded:: 5.0
.. code-block:: javascript
fetchArraySize(Number size)
Sets the size of an internal buffer used for fetching
documents from a collection with the terminal SodaOperation methods
:meth:`~sodaOperation.getCursor()` and
:meth:`~sodaOperation.getDocuments()`. Changing
``size`` may affect performance but does not affect how many documents
are returned.
If ``fetchArraySize()`` is not used, the size defaults to the current
value of :attr:`oracledb.fetchArraySize`.
For node-oracledb examples, see :ref:`SODA Query-by-Example Searches for
JSON Documents <sodaqbesearches>`.
It requires Oracle Client 19.5 or later, and Oracle Database 18.3 or later.
.. method:: sodaOperation.filter()
.. versionadded:: 3.0
.. code-block:: javascript
filter(Object filterSpec)
Sets a filter specification for the operation, allowing for complex
document queries and ordering of JSON documents. Filter specifications
can include comparisons, regular expressions, logical, and spatial
operators, among others. See `Overview of SODA Filter Specifications
(QBEs) <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
CB09C4E3-BBB1-40DC-88A8-8417821B0FBE>`__ and `SODA Filter Specifications
(Reference) <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
8DDB51EB-D80F-4476-9ABF-D6860C6214D1>`__.
For node-oracledb examples, see :ref:`SODA Query-by-Example Searches for JSON
Documents <sodaqbesearches>`.
.. method:: sodaOperation.hint()
.. versionadded:: 5.2
.. code-block:: javascript
hint(String hint)
The ``hint()`` value can be used to pass an Oracle hint to :ref:`terminal
SodaOperation Methods <sodaoperationclassterm>`. It is string in the
same format as a `SQL
hint <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
C558F7CF-446E-4078-B045-0B3BB026CB3C>`__
but without any comment characters, for example ``hint("MONITOR")``.
Pass only the hint ``"MONITOR"`` (turn on monitoring) or
``"NO_MONITOR"`` (turn off monitoring). See the Oracle Database SQL
Tuning Guide documentation `MONITOR and NO_MONITOR
Hints <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-
19E0F73C-A959-41E4-A168-91E436DEE1F1>`__ and `Monitoring Database
Operations <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID
-C941CE9D-97E1-42F8-91ED-4949B2B710BF>`__ for more information.
It requires Oracle Client 21.3 or higher (or Oracle Client 19 from
19.11).
.. method:: sodaOperation.key()
.. versionadded:: 3.0
.. code-block:: javascript
key(String value)
Sets the key value to be used to match a document for the operation. Any
previous calls made to this method or :meth:`~sodaOperation.keys()`
will be ignored.
SODA document keys are unique.
.. method:: sodaOperation.keys()
.. versionadded:: 3.0
.. code-block:: javascript
keys(Array value)
Sets the keys to be used to match multiple documents for the operation.
Any previous calls made to this method or :meth:`sodaOperation.key()`
will be ignored.
SODA document keys are unique.
A maximum of 1000 keys can be used.
.. method:: sodaOperation.limit()
.. versionadded:: 3.0
.. code-block:: javascript
limit(Number n)
Sets the maximum number of documents that a terminal method will apply
to. The value of ``n`` must be greater than 0. The limit is applied to
documents that match the other SodaOperation criteria. The ``limit()``
method only applies to SodaOperation read operations like
``getCursor()`` and ``getDocuments()``. If a filter ``$orderby`` is not
used, the document order is internally defined.
The ``limit()`` method cannot be used in conjunction with
:meth:`~sodaOperation.count()`.
.. method:: sodaOperation.lock()
.. versionadded:: 6.2
.. code-block:: javascript
lock()
Locks the documents fetched from the collection.
Using ``lock()`` allows for pessimistic locking, that is, only the current
user that performed the lock can modify the documents in the collection.
Other users can only perform operations on these documents once they are
unlocked. The functionality of this method is equivalent to the
``SELECT FOR UPDATE`` clause.
The documents can be unlocked with an explicit call to
:meth:`~connection.commit()` or :meth:`~connection.rollback()` on the
connection. Ensure that the :attr:`oracledb.autoCommit` is
set to *false* for the connection. Otherwise, the documents will be
unlocked immediately after the operation is complete.
This method should only be used with read operations (other than
:meth:`~sodaOperation.count()`), and should not be used in conjunction
with non-terminal methods :meth:`~sodaOperation.skip()` and
:meth:`~sodaOperation.limit()`.
If this method is specified in conjunction with a write operation, then
this method is ignored.
This method requires Oracle Client 21.3 or later (or Oracle Client 19 from
19.11).
.. method:: sodaOperation.skip()
.. versionadded:: 3.0
.. code-block:: javascript
skip(Number n)
Sets the number of documents that will be skipped before the terminal
method is applied. The value of ``n`` must be greater or equal to 0. The
skip applies to documents that match the other SodaOperation criteria.
If a filter ``$orderby`` is not used, the document order (and hence
which documents are skipped) is internally defined.
The ``skip()`` method only applies to SodaOperation read operations like
``getDocuments()``. It cannot be used with
:meth:`~sodaOperation.count()`.
.. method:: sodaOperation.version()
.. versionadded:: 3.0
.. code-block:: javascript
version(String value)
Sets the document version that documents must have.
This is typically used in conjunction with a key, for example
``collection.find().key("k").version("v").replaceOne(doc)``.
Using ``version()`` allows for optimistic locking, so that the
subsequent SodaOperation terminal method does not affect a document that
someone else has already modified. If the requested document version is
not matched, then your terminal operation will not impact any document.
The application can then query to find the latest document version and
apply any desired change.
.. _sodaoperationclassterm:
Terminal SodaOperation Methods
==============================
A terminal SodaOperation method operates on the set of documents that
satisfy the criteria specified by previous non-terminal methods in the
method chain. Only one terminal method can be used in each chain.
.. method:: sodaOperation.count()
.. versionadded:: 3.0
**Promise**::
promise = count();
Finds the number of documents matching the given SodaOperation query
criteria.
If ``skip()`` or ``limit()`` are set, then ``count()`` will return an
error.
If :attr:`oracledb.autoCommit` is *true*, and ``count()`` succeeds,
then any open transaction on the connection is committed.
**Callback**:
If you are using the callback programming style::
count(function (Error error, Object result){});
The parameters of the callback function
``function (Error error, Object result)`` 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 ``count()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
* - Object ``result``
- The `result` object contains one attribute::
Number count
The number of documents matching the SodaOperation criteria.
Due to Node.js type limitations, the largest ``count`` value will be 232 - 1, even if more rows exist. Larger values will wrap.
.. method:: sodaOperation.getCursor()
.. versionadded:: 3.0
**Promise**::
promise = getCursor()
Returns a :ref:`SodaDocumentCursor <sodadocumentcursorclass>` for
documents that match the SodaOperation query criteria. The cursor can be
iterated over with :meth:`sodaDocumentCursor.getNext()` to access
each :ref:`SodaDocument <sodadocumentclass>`.
When the application has completed using the cursor it must be closed
with :meth:`sodaDocumentCursor.close()`.
If the number of documents is known to be small, it is recommended to
use :meth:`sodaOperation.getDocuments()` instead.
If :attr:`oracledb.autoCommit` is *true*, and
``getCursor()`` succeeds, then any open transaction on the connection is
committed.
**Callback**:
If you are using the callback programming style::
getCursor(function(Error error, SodaDocumentCursor cursor){});
The parameters of the callback function
``function(Error error, SodaDocumentCursor cursor)`` 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 ``getCursor()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
* - SodaDocumentCursor ``cursor``
- A cursor that can be iterated over to access SodaDocument objects matching the SodaOperation search criteria.
.. method:: sodaOperation.getDocuments()
.. versionadded:: 3.0
**Promise**::
promise = getDocuments();
Gets an array of :ref:`SodaDocuments <sodadocumentclass>` matching the
SodaOperation query criteria. An empty array will be returned when no
documents match.
Where the number of matching documents is known to be small, this API
should be used in preference to :meth:`sodaOperation.getCursor()`.
If :attr:`oracledb.autoCommit` is *true*, and ``getDocuments()``
succeeds, then any open transaction on the connection is committed.
**Callback**:
If you are using the callback programming style::
getDocuments(function(Error error, Array documents){});
The parameters of the callback function
``function(Error error, Array documents)`` 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 ``getDocuments()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
* - Array ``documents``
- An array of SodaDocuments that match the SodaOperation query criteria.
.. method:: sodaOperation.getOne()
.. versionadded:: 3.0
**Promise**::
promise = getOne();
Obtains one document matching the SodaOperation query criteria. If the
criteria match more than one document, then only the first is returned.
Typically ``getone()`` should be used with ``key(k)`` or
``key(k).version(v)`` to ensure only one document is matched.
If :attr:`oracledb.autoCommit` is *true*, and ``getOne()`` succeeds, then
any open transaction on the connection is committed.
**Callback**:
If you are using the callback programming style::
getOne(function(Error error, SodaDocument document){});
The parameters of the callback function
``function(Error error, SodaDocument document)`` 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 ``getOne()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
* - SodaDocument ``document``
- One SodaDocument that matches the sodaOperation query criteria. If no document is found, then ``document`` will be undefined.
.. method:: sodaOperation.remove()
.. versionadded:: 3.0
**Promise**::
promise = remove();
Removes a set of documents matching the SodaOperation query criteria.
Note settings from ``skip()`` and ``limit()`` non-terminals are ignored
because they only apply to read operations.
If :attr:`oracledb.autoCommit` is *true*, and ``remove()`` succeeds, then
removal and any open transaction on the connection is committed.
**Callback**:
If you are using the callback programming style::
remove(function(Error error, Object result){});
The parameters of the callback function
``function(Error error, Object result)`` 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 ``remove()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the error message.
* - Object ``result``
- The `result` object contains one attribute::
result.count
The number of documents removed from the collection.
Due to Node.js type limitations, the largest ``count`` value will be 232 - 1, even if Oracle Database removed more rows. Larger values will wrap.
.. method:: sodaOperation.replaceOne()
.. versionadded:: 3.0
**Promise**::
promise = replaceOne(Object newDocumentContent);
promise = replaceOne(SodaDocument newSodaDocument);
Replaces a document in a collection. The input document can be either a
JavaScript object representing the data content, or it can be an
existing :ref:`SodaDocument <sodadocumentclass>`.
The ``mediaType`` document component and content of the document that
matches the SodaOperation query criteria will be replaced by the content
and any ``mediaType`` document component of the new document. Any other
document components will not be affected. The ``lastModified`` and
``version`` document components of the replaced document will be
updated.
The ``key()`` non-terminal must be used when using ``replaceOne()``.
No error is reported if the operation criteria do not match any
document.
Note settings from ``skip()`` and ``limit()`` non-terminals are ignored
because they only apply to read operations.
If :attr:`oracledb.autoCommit` is *true*, and ``replaceOne()`` succeeds,
then any open transaction on the connection is committed.
The parameters of the ``sodaOperation.replaceOne()`` method are:
.. _replaceone:
.. list-table-with-summary:: sodaOperation.replaceOne() Parameters
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the parameter. The second column
displays the data type of the parameter. The third column displays
the description of the parameter.
* - Parameter
- Data Type
- Description
* - ``newDocumentContent`` or ``newSodaDocument``
- Object or SodaDocument
- The new document. See :meth:`sodaCollection.insertOne()`, which has the same semantics for the document.
**Callback**:
If you are using the callback programming style::
replaceOne(Object newDocumentContent, function(Error error, Object result){});
replaceOne(SodaDocument newSodaDocument, function(Error error, Object result){});
See :ref:`replaceone` for information on the parameters.
The parameters of the callback function
``function(Error error, Object result)`` 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 ``replaceOne()`` succeeds, ``error`` is NULL. It is not an error if no document is replaced. If an error occurs, then ``error`` contains the error message.
* - Object ``result``
- The `result` object contains one attribute::
result.replaced
This attribute will be *true* if the document was successfully replaced, *false* otherwise.
.. method:: sodaOperation.replaceOneAndGet()
.. versionadded:: 3.0
**Promise**::
promise = replaceOneAndGet(Object newDocumentContent);
promise = replaceOneAndGet(SodaDocument newSodaDocument);
Replaces a document in a collection similar to
:meth:`sodaOperation.replaceOne()`, but also returns
the result document which contains all :ref:`SodaDocument
<sodadocumentclass>` components (key, version, etc.)
except for content. Content itself is not returned for performance
reasons. The result document has new values for components that are
updated as part of the replace operation (such as version, last-modified
timestamp, and media type)
If :attr:`oracledb.autoCommit` is *true*, and ``replaceOneAndGet()``
succeeds, then any open transaction on the connection is committed.
The parameters of the ``sodaOperation.replaceOneAndGet()`` method are:
.. _replaceoneandget:
.. list-table-with-summary:: sodaOperation.replaceOneAndGet() Parameters
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the parameter. The second column
displays the data type of the parameter. The third column displays
the description of the parameter.
* - Parameter
- Data Type
- Description
* - ``newDocumentContent`` or ``newSodaDocument``
- Object or SodaDocument
- The new document. See :meth:`sodaCollection.insertOne()`, which has the same semantics for the document.
**Callback**:
If you are using the callback programming style::
replaceOneAndGet(Object newDocumentContent, function(Error error, SodaDocument updatedDocument){});
replaceOneAndGet(SodaDocument newSodaDocument, function(Error error, SodaDocument updatedDocument){});
See :ref:`replaceoneandget` for information on the parameters.
The parameters of the callback function
``function(Error error, SodaDocument updatedDocument)`` 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 ``replaceOneAndGet()`` succeeds, ``error`` is NULL. It is not an error if no document is replaced. If an error occurs, then ``error`` contains the error message.
* - SodaDocument ``updatedDocument``
- The updated :ref:`SodaDocument <sodadocumentclass>` if replacement was successful, otherwise ``updatedDocument`` will be undefined.
The ``lastModified`` and ``version`` attributes of the stored SodaDocument will be updated. The ``mediaType`` attribute and the content will be replaced. Other attributes of ``newSodaDocument`` are ignored.
Note for performance reasons, ``updatedDocument`` will not have document content and cannot itself be passed directly to SODA insert or replace methods.

1
doc/src/index.rst
View File

@ -66,6 +66,7 @@ API Manual
api_manual/statistics.rst
api_manual/resultset.rst
api_manual/sodacollection.rst
api_manual/sodaoperation.rst
api_manual/sodadb.rst
api_manual/sodadocument.rst
api_manual/sodacursor.rst

2
lib/constants.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/dbObject.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2019, 2023, Oracle and/or its affiliates.
// Copyright (c) 2019, 2024, Oracle and/or its affiliates.
//----------------------------------------------------------------------------
//

2
lib/errors.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/lob.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2016, 2023, Oracle and/or its affiliates.
// Copyright (c) 2016, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/pool.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2016, 2022, Oracle and/or its affiliates.
// Copyright (c) 2016, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/poolStatistics.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2021, 2023, Oracle and/or its affiliates.
// Copyright (c) 2021, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/settings.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/connection.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/dbObject.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2023, Oracle and/or its affiliates.
// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/lob.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/pool.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/protocol/buffer.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/protocol/capabilities.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/protocol/constants.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/protocol/messages/base.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/protocol/messages/dataType.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/protocol/messages/withData.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/sqlnet/networkSession.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/thin/statement.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/transformer.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2023, Oracle and/or its affiliates.
// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/types.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

2
lib/version.js
View File

@ -1,4 +1,4 @@
// Copyright (c) 2023, Oracle and/or its affiliates.
// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
//-----------------------------------------------------------------------------
//

10
test/dbObject20.js
View File

@ -1,4 +1,4 @@
/* Copyright (c) 2019, 2023, Oracle and/or its affiliates. */
/* Copyright (c) 2019, 2024, Oracle and/or its affiliates. */
/******************************************************************************
*
@ -864,10 +864,10 @@ describe('290. dbObject20.js', () => {
describe(`290.4 db Object tests with Invalid values to attributes`, () => {
let conn;
const TYPE1 = 'NODB_TEST_INVALID_VALUES_OBJ_TBL_LINE';
const TYPE2 = 'NODB_TEST_INVALID_VALUES_OBJ_TBL';
const TYPE3 = 'NODB_TEST_INVALID_VALUES_OBJ';
const TYPE4 = 'NODB_TEST_INVALID_VALUES_OBJ_TBL_VARCHAR';
const TYPE1 = 'NODB_TEST_INV_OBJ_TBL_LINE';
const TYPE2 = 'NODB_TEST_INV_OBJ_TBL';
const TYPE3 = 'NODB_TEST_INV_OBJ';
const TYPE4 = 'NODB_TEST_INV_OBJ_TBL_VARCHAR';
const maxVarCharLen = 4;
const maxVarNCharLen = 4;
const maxVarRawLen = 10;

16
test/jsonDualityViews6.js
View File

@ -1,4 +1,4 @@
/* Copyright (c) 2023, Oracle and/or its affiliates. */
/* Copyright (c) 2023, 2024, Oracle and/or its affiliates. */
/******************************************************************************
*
@ -236,7 +236,7 @@ describe('277. jsonDualityView6.js', function() {
);
});
describe('277.1.2 Queries(SNT,SNT+where clause)', function() {
describe('277.2 Queries(SNT,SNT+where clause)', function() {
before (async function() {
await connection.execute(`CREATE OR REPLACE JSON RELATIONAL DUALITY VIEW student_ov
AS
@ -249,7 +249,7 @@ describe('277. jsonDualityView6.js', function() {
`);
});
it('277.1.2.1 With SNT', async function() {
it('277.2.1 With SNT', async function() {
let result = await connection.execute(`select o.data.StudentId as name from student_ov o
order by o.data.StudentId`);
assert.deepStrictEqual(result.rows, [[1], [2], [3]]);
@ -274,7 +274,7 @@ describe('277. jsonDualityView6.js', function() {
assert.deepStrictEqual(result.rows, [[1, 1], [2, 2], [3, 3]]);
});
it('277.1.2.2 SNT+where clause)', async function() {
it('277.2.2 SNT+where clause', async function() {
let result = await connection.execute(`select o.data.StudentId from student_ov o
where o.data.StudentId in (1,3) order by 1`);
assert.deepStrictEqual(result.rows, [[1], [3]]);
@ -302,7 +302,7 @@ describe('277. jsonDualityView6.js', function() {
});
});
});
describe('277.2 PK-PK-FK', function() {
describe('277.3 PK-PK-FK', function() {
before(async function() {
// create the student table
await connection.execute(`
@ -337,7 +337,7 @@ describe('277. jsonDualityView6.js', function() {
await connection.execute(`drop table student PURGE`);
});
it('277.2.1 Insert data in table and views', async function() {
it('277.3.1 Insert data in table and views', async function() {
await connection.execute(`insert into student values (1, 'Ajit')`);
await connection.execute(`insert into student values (2, 'Tirthankar')`);
await connection.execute(`insert into student values (3, 'Shashank')`);
@ -379,7 +379,7 @@ describe('277. jsonDualityView6.js', function() {
"StudentId": 1, "Class": [{"ClassId": 1, "Name": "CS101"}]}]);
});
it('277.2.2 Sanity DMLs', async function() {
it('277.3.2 Sanity DMLs', async function() {
await connection.execute(`
insert into student_ov values ('{"StudentId":4,
"StudentName":"Abcd","StudentClass":[{"StudentClassId":1,
@ -412,7 +412,7 @@ describe('277. jsonDualityView6.js', function() {
"Class": [{"ClassId": 1, "Name": "CS101"}]}]);
});
it('277.2.3 with different keywords', async function() {
it('277.3.3 with different keywords', async function() {
await connection.execute(`CREATE OR REPLACE JSON RELATIONAL DUALITY VIEW student_ov
AS
Student @INSERT@UPDATE@DELETE

33
test/list.txt
View File

@ -4272,7 +4272,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true
173.9 Negative - dropIndex() no parameter
173.10 option object of dropIndex(), basic case
173.11 option object of dropIndex(), boolean value is false
173.12 getDataGiuide(), basic case
173.12 getDataGuide(), basic case
174. soda6.js
174.1 filter() basic case
@ -5344,7 +5344,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true
271.22 converter function to convert column val to string
271.23 converter function with multiple columns
272. jsonDualityView1.js
272. jsonDualityViews1.js
272.1 JSON Relational Duality View
272.1.1 fetch results
272.1.2 update query
@ -5389,7 +5389,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true
272.3.11.1 Query with test1 user
272.3.11.2 Query with test2 user
273. jsonDualityView2.js
273. jsonDualityViews2.js
273.1 without base table being available (use force option at view creation)
273.2 Base table name with various sizes (128)
273.3 Perform dbms_metadata.get_ddl() and verify tags were properly added to columns and tables
@ -5413,7 +5413,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true
273.5 With Redaction on base tables
273.5.1 redaction enabled on a base table
274. jsonDualityView3.js
274. jsonDualityViews3.js
274.1 Define Columns of View with WITH READ WRITE or WITH READ ONLY annotations
274.2 Create View on Virtual columns, UNUSED columns
274.3 Have columns of all scalar types, including FLOAT, TIMESTAMP, TIMESTAMP WITH TIME ZONE
@ -5423,7 +5423,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true
274.7 Add VISIBLE | INVISIBLE options to define columns in view
274.8 Create view on NULL columns empty columns
275. jsonDualityView4.js
275. jsonDualityViews4.js
275.1 Test create table, Column defaults
275.2 Test with Table and column constraints
275.3 Test with Virtual columns
@ -5447,22 +5447,22 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true
275.11 Tests with Views
275.11.1 Object view
276. jsonDualityView5.js
276. jsonDualityViews5.js
276.1 Insert data in table and views
276.2 test with Tags in column level
277. jsonDualityView6.js
277. jsonDualityViews6.js
277.1 With tables and without constraints relationship
277.1.1 Insert data in table and views
277.1.2 Sanity DMLs
277.1.3 With Invalid tags
277.1.2 Queries(SNT,SNT+where clause)
277.1.2.1 With SNT
277.1.2.2 SNT+where clause)
277.2 PK PK FK
277.2.1 Insert data in table and views
277.2.2 Sanity DMLs
277.2.3 with different keywords
277.2 Queries(SNT,SNT+where clause)
277.2.1 With SNT
277.2.2 SNT+where clause
277.3 PK PK FK
277.3.1 Insert data in table and views
277.3.2 Sanity DMLs
277.3.3 with different keywords
278. Pool expansion
278.1 pool expansion when new connection created and within pool max limit
@ -5582,14 +5582,15 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true
289. sqlParser.js
289.1 parse SQL containing json_object()
289.2 bind variables between quoted string
289.3 single line comment
289.4 constant string
289.3 PL/SQL - single line comment
289.4 PL/SQL - constant string
289.5 multiple division operation
289.6 SQL statement starting with parentheses
289.7 statement containing simple strings
289.8 binds between comments
289.9 non-ascii character in the bind name
289.10 apostrophe in single line comment
289.11 single line comment at the end
290. dbObject20.js
290.1 db Object tests with NCHAR datatype

19
test/sqlParser.js
View File

@ -1,4 +1,4 @@
/* Copyright (c) 2023, Oracle and/or its affiliates. */
/* Copyright (c) 2023, 2024, Oracle and/or its affiliates. */
/******************************************************************************
*
@ -64,7 +64,7 @@ describe('289. sqlParser.js', function() {
}); // 289.1
it('289.2 bind variables between quoted string', async () => {
const sql = `select
const sql = `SELECT
:a,
q'{This contains ' and " and : just fine}',
:b,
@ -76,19 +76,19 @@ describe('289. sqlParser.js', function() {
:e,
q'$This contains ' and " and : just fine$',
:f
from dual`;
FROM DUAL`;
const info = await conn.getStatementInfo(sql);
assert.deepStrictEqual(info.bindNames, ["A", "B", "C", "D", "E", "F"]);
}); // 289.2
it('289.3 single line comment', async () => {
it('289.3 PL/SQL - single line comment', async () => {
const sql = `--begin :value2 := :a + :b + :c +:a +3; end;
begin :value2 := :a + :c +3; end; -- not a :bindv`;
begin :value2 := :a + :c +3; end; -- not a :bindVariable`;
const info = await conn.getStatementInfo(sql);
assert.deepStrictEqual(info.bindNames, ["VALUE2", "A", "C"]);
}); // 289.3
it('289.4 constant string', async () => {
it('289.4 PL/SQL - constant string', async () => {
const sql = `begin
:value := to_date('20021231 12:31:00', :format);
end;`;
@ -142,4 +142,11 @@ describe('289. sqlParser.js', function() {
const info = await conn.getStatementInfo(sql);
assert.deepStrictEqual(info.bindNames, ['TEST']);
}); // 289.10
it('289.11 single line comment at the end', async () => {
const sql = `
SELECT :test, 'String' FROM DUAL -- not a :bindVariable`;
const info = await conn.getStatementInfo(sql);
assert.deepStrictEqual(info.bindNames, ['TEST']);
}); // 289.11
});