Copyright updates, documentation and test case additions
This commit is contained in:
parent
b287d414cb
commit
4dd4721814
|
@ -13,8 +13,6 @@ Makefile.win32
|
||||||
/examples/*
|
/examples/*
|
||||||
!/examples/example.js
|
!/examples/example.js
|
||||||
!/examples/dbconfig.js
|
!/examples/dbconfig.js
|
||||||
!/examples/vectortype1.js
|
|
||||||
!/examples/vectortype2.js
|
|
||||||
/test
|
/test
|
||||||
/build/Release/oracledb.node
|
/build/Release/oracledb.node
|
||||||
/build/oracledb.target.mk
|
/build/oracledb.target.mk
|
||||||
|
|
534
doc/api.md
534
doc/api.md
File diff suppressed because it is too large
Load Diff
|
@ -273,653 +273,6 @@ SodaCollection Methods
|
||||||
See :ref:`Simple Oracle Document Access (SODA) <sodaoverview>` for more
|
See :ref:`Simple Oracle Document Access (SODA) <sodaoverview>` for more
|
||||||
examples.
|
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()
|
.. method:: sodaCollection.getDataGuide()
|
||||||
|
|
||||||
.. versionadded:: 3.0
|
.. 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.
|
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()
|
.. method:: sodaCollection.save()
|
||||||
|
|
||||||
.. versionadded:: 5.0
|
.. versionadded:: 5.0
|
||||||
|
|
|
@ -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.
|
|
@ -66,6 +66,7 @@ API Manual
|
||||||
api_manual/statistics.rst
|
api_manual/statistics.rst
|
||||||
api_manual/resultset.rst
|
api_manual/resultset.rst
|
||||||
api_manual/sodacollection.rst
|
api_manual/sodacollection.rst
|
||||||
|
api_manual/sodaoperation.rst
|
||||||
api_manual/sodadb.rst
|
api_manual/sodadb.rst
|
||||||
api_manual/sodadocument.rst
|
api_manual/sodadocument.rst
|
||||||
api_manual/sodacursor.rst
|
api_manual/sodacursor.rst
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2019, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2019, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//----------------------------------------------------------------------------
|
//----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2016, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2016, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2016, 2022, Oracle and/or its affiliates.
|
// Copyright (c) 2016, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2021, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2021, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2022, 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2022, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
// Copyright (c) 2023, Oracle and/or its affiliates.
|
// Copyright (c) 2023, 2024, Oracle and/or its affiliates.
|
||||||
|
|
||||||
//-----------------------------------------------------------------------------
|
//-----------------------------------------------------------------------------
|
||||||
//
|
//
|
||||||
|
|
|
@ -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`, () => {
|
describe(`290.4 db Object tests with Invalid values to attributes`, () => {
|
||||||
let conn;
|
let conn;
|
||||||
const TYPE1 = 'NODB_TEST_INVALID_VALUES_OBJ_TBL_LINE';
|
const TYPE1 = 'NODB_TEST_INV_OBJ_TBL_LINE';
|
||||||
const TYPE2 = 'NODB_TEST_INVALID_VALUES_OBJ_TBL';
|
const TYPE2 = 'NODB_TEST_INV_OBJ_TBL';
|
||||||
const TYPE3 = 'NODB_TEST_INVALID_VALUES_OBJ';
|
const TYPE3 = 'NODB_TEST_INV_OBJ';
|
||||||
const TYPE4 = 'NODB_TEST_INVALID_VALUES_OBJ_TBL_VARCHAR';
|
const TYPE4 = 'NODB_TEST_INV_OBJ_TBL_VARCHAR';
|
||||||
const maxVarCharLen = 4;
|
const maxVarCharLen = 4;
|
||||||
const maxVarNCharLen = 4;
|
const maxVarNCharLen = 4;
|
||||||
const maxVarRawLen = 10;
|
const maxVarRawLen = 10;
|
||||||
|
|
|
@ -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() {
|
before (async function() {
|
||||||
await connection.execute(`CREATE OR REPLACE JSON RELATIONAL DUALITY VIEW student_ov
|
await connection.execute(`CREATE OR REPLACE JSON RELATIONAL DUALITY VIEW student_ov
|
||||||
AS
|
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
|
let result = await connection.execute(`select o.data.StudentId as name from student_ov o
|
||||||
order by o.data.StudentId`);
|
order by o.data.StudentId`);
|
||||||
assert.deepStrictEqual(result.rows, [[1], [2], [3]]);
|
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]]);
|
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
|
let result = await connection.execute(`select o.data.StudentId from student_ov o
|
||||||
where o.data.StudentId in (1,3) order by 1`);
|
where o.data.StudentId in (1,3) order by 1`);
|
||||||
assert.deepStrictEqual(result.rows, [[1], [3]]);
|
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() {
|
before(async function() {
|
||||||
// create the student table
|
// create the student table
|
||||||
await connection.execute(`
|
await connection.execute(`
|
||||||
|
@ -337,7 +337,7 @@ describe('277. jsonDualityView6.js', function() {
|
||||||
await connection.execute(`drop table student PURGE`);
|
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 (1, 'Ajit')`);
|
||||||
await connection.execute(`insert into student values (2, 'Tirthankar')`);
|
await connection.execute(`insert into student values (2, 'Tirthankar')`);
|
||||||
await connection.execute(`insert into student values (3, 'Shashank')`);
|
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"}]}]);
|
"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(`
|
await connection.execute(`
|
||||||
insert into student_ov values ('{"StudentId":4,
|
insert into student_ov values ('{"StudentId":4,
|
||||||
"StudentName":"Abcd","StudentClass":[{"StudentClassId":1,
|
"StudentName":"Abcd","StudentClass":[{"StudentClassId":1,
|
||||||
|
@ -412,7 +412,7 @@ describe('277. jsonDualityView6.js', function() {
|
||||||
"Class": [{"ClassId": 1, "Name": "CS101"}]}]);
|
"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
|
await connection.execute(`CREATE OR REPLACE JSON RELATIONAL DUALITY VIEW student_ov
|
||||||
AS
|
AS
|
||||||
Student @INSERT@UPDATE@DELETE
|
Student @INSERT@UPDATE@DELETE
|
||||||
|
|
|
@ -4272,7 +4272,7 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true
|
||||||
173.9 Negative - dropIndex() no parameter
|
173.9 Negative - dropIndex() no parameter
|
||||||
173.10 option object of dropIndex(), basic case
|
173.10 option object of dropIndex(), basic case
|
||||||
173.11 option object of dropIndex(), boolean value is false
|
173.11 option object of dropIndex(), boolean value is false
|
||||||
173.12 getDataGiuide(), basic case
|
173.12 getDataGuide(), basic case
|
||||||
|
|
||||||
174. soda6.js
|
174. soda6.js
|
||||||
174.1 filter() basic case
|
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.22 converter function to convert column val to string
|
||||||
271.23 converter function with multiple columns
|
271.23 converter function with multiple columns
|
||||||
|
|
||||||
272. jsonDualityView1.js
|
272. jsonDualityViews1.js
|
||||||
272.1 JSON Relational Duality View
|
272.1 JSON Relational Duality View
|
||||||
272.1.1 fetch results
|
272.1.1 fetch results
|
||||||
272.1.2 update query
|
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.1 Query with test1 user
|
||||||
272.3.11.2 Query with test2 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.1 without base table being available (use force option at view creation)
|
||||||
273.2 Base table name with various sizes (128)
|
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
|
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 With Redaction on base tables
|
||||||
273.5.1 redaction enabled on a base table
|
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.1 Define Columns of View with WITH READ WRITE or WITH READ ONLY annotations
|
||||||
274.2 Create View on Virtual columns, UNUSED columns
|
274.2 Create View on Virtual columns, UNUSED columns
|
||||||
274.3 Have columns of all scalar types, including FLOAT, TIMESTAMP, TIMESTAMP WITH TIME ZONE
|
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.7 Add VISIBLE | INVISIBLE options to define columns in view
|
||||||
274.8 Create view on NULL columns empty columns
|
274.8 Create view on NULL columns empty columns
|
||||||
|
|
||||||
275. jsonDualityView4.js
|
275. jsonDualityViews4.js
|
||||||
275.1 Test create table, Column defaults
|
275.1 Test create table, Column defaults
|
||||||
275.2 Test with Table and column constraints
|
275.2 Test with Table and column constraints
|
||||||
275.3 Test with Virtual columns
|
275.3 Test with Virtual columns
|
||||||
|
@ -5447,22 +5447,22 @@ oracledb.OUT_FORMAT_OBJECT and resultSet = true
|
||||||
275.11 Tests with Views
|
275.11 Tests with Views
|
||||||
275.11.1 Object view
|
275.11.1 Object view
|
||||||
|
|
||||||
276. jsonDualityView5.js
|
276. jsonDualityViews5.js
|
||||||
276.1 Insert data in table and views
|
276.1 Insert data in table and views
|
||||||
276.2 test with Tags in column level
|
276.2 test with Tags in column level
|
||||||
|
|
||||||
277. jsonDualityView6.js
|
277. jsonDualityViews6.js
|
||||||
277.1 With tables and without constraints relationship
|
277.1 With tables and without constraints relationship
|
||||||
277.1.1 Insert data in table and views
|
277.1.1 Insert data in table and views
|
||||||
277.1.2 Sanity DMLs
|
277.1.2 Sanity DMLs
|
||||||
277.1.3 With Invalid tags
|
277.1.3 With Invalid tags
|
||||||
277.1.2 Queries(SNT,SNT+where clause)
|
277.2 Queries(SNT,SNT+where clause)
|
||||||
277.1.2.1 With SNT
|
277.2.1 With SNT
|
||||||
277.1.2.2 SNT+where clause)
|
277.2.2 SNT+where clause
|
||||||
277.2 PK PK FK
|
277.3 PK PK FK
|
||||||
277.2.1 Insert data in table and views
|
277.3.1 Insert data in table and views
|
||||||
277.2.2 Sanity DMLs
|
277.3.2 Sanity DMLs
|
||||||
277.2.3 with different keywords
|
277.3.3 with different keywords
|
||||||
|
|
||||||
278. Pool expansion
|
278. Pool expansion
|
||||||
278.1 pool expansion when new connection created and within pool max limit
|
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. sqlParser.js
|
||||||
289.1 parse SQL containing json_object()
|
289.1 parse SQL containing json_object()
|
||||||
289.2 bind variables between quoted string
|
289.2 bind variables between quoted string
|
||||||
289.3 single line comment
|
289.3 PL/SQL - single line comment
|
||||||
289.4 constant string
|
289.4 PL/SQL - constant string
|
||||||
289.5 multiple division operation
|
289.5 multiple division operation
|
||||||
289.6 SQL statement starting with parentheses
|
289.6 SQL statement starting with parentheses
|
||||||
289.7 statement containing simple strings
|
289.7 statement containing simple strings
|
||||||
289.8 binds between comments
|
289.8 binds between comments
|
||||||
289.9 non-ascii character in the bind name
|
289.9 non-ascii character in the bind name
|
||||||
289.10 apostrophe in single line comment
|
289.10 apostrophe in single line comment
|
||||||
|
289.11 single line comment at the end
|
||||||
|
|
||||||
290. dbObject20.js
|
290. dbObject20.js
|
||||||
290.1 db Object tests with NCHAR datatype
|
290.1 db Object tests with NCHAR datatype
|
||||||
|
|
|
@ -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
|
}); // 289.1
|
||||||
|
|
||||||
it('289.2 bind variables between quoted string', async () => {
|
it('289.2 bind variables between quoted string', async () => {
|
||||||
const sql = `select
|
const sql = `SELECT
|
||||||
:a,
|
:a,
|
||||||
q'{This contains ' and " and : just fine}',
|
q'{This contains ' and " and : just fine}',
|
||||||
:b,
|
:b,
|
||||||
|
@ -76,19 +76,19 @@ describe('289. sqlParser.js', function() {
|
||||||
:e,
|
:e,
|
||||||
q'$This contains ' and " and : just fine$',
|
q'$This contains ' and " and : just fine$',
|
||||||
:f
|
:f
|
||||||
from dual`;
|
FROM DUAL`;
|
||||||
const info = await conn.getStatementInfo(sql);
|
const info = await conn.getStatementInfo(sql);
|
||||||
assert.deepStrictEqual(info.bindNames, ["A", "B", "C", "D", "E", "F"]);
|
assert.deepStrictEqual(info.bindNames, ["A", "B", "C", "D", "E", "F"]);
|
||||||
}); // 289.2
|
}); // 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;
|
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);
|
const info = await conn.getStatementInfo(sql);
|
||||||
assert.deepStrictEqual(info.bindNames, ["VALUE2", "A", "C"]);
|
assert.deepStrictEqual(info.bindNames, ["VALUE2", "A", "C"]);
|
||||||
}); // 289.3
|
}); // 289.3
|
||||||
|
|
||||||
it('289.4 constant string', async () => {
|
it('289.4 PL/SQL - constant string', async () => {
|
||||||
const sql = `begin
|
const sql = `begin
|
||||||
:value := to_date('20021231 12:31:00', :format);
|
:value := to_date('20021231 12:31:00', :format);
|
||||||
end;`;
|
end;`;
|
||||||
|
@ -142,4 +142,11 @@ describe('289. sqlParser.js', function() {
|
||||||
const info = await conn.getStatementInfo(sql);
|
const info = await conn.getStatementInfo(sql);
|
||||||
assert.deepStrictEqual(info.bindNames, ['TEST']);
|
assert.deepStrictEqual(info.bindNames, ['TEST']);
|
||||||
}); // 289.10
|
}); // 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
|
||||||
});
|
});
|
||||||
|
|
Loading…
Reference in New Issue