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

Documentation for centralized config provider, JSON Relational Duality View and other updates with formatting improvements

This commit is contained in:
Sharad Chandran R 2024-07-23 17:09:02 +05:30
parent 39bd3a100d
commit c63115f0cf
13 changed files with 813 additions and 246 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/src/.static/custom.css
View File

@ -54,3 +54,9 @@ li div.highlight-default.notranslate, li div.highlight-shell.notranslate, li div
font-size: 11pt;
font-weight: bold;
}
/* Added code to override the default content width in ReadtheDocs and break long words */
.wy-nav-content {
max-width: none;
word-break: break-word;
}

52
doc/src/_ext/constants_table.py Normal file
View File

@ -0,0 +1,52 @@
#------------------------------------------------------------------------------
# Copyright (c) 2024, Oracle and/or its affiliates.
#
# This software is dual-licensed to you under the Universal Permissive License
# (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
# 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
# either license.
#
# If you elect to accept the software under the Apache License, Version 2.0,
# the following applies:
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#------------------------------------------------------------------------------
#------------------------------------------------------------------------------
# constants_table.py
#
# Defines a directive (constants-table) that creates a table with a specific
# configuration on top of the extended "list-table-with-summary" directive.
#------------------------------------------------------------------------------
from docutils.statemachine import ViewList
import table_with_summary
class ConstantsTable(table_with_summary.ListTableWithSummary):
def run(self):
self.options["summary"] = \
"The first column displays the name of the constant. The " \
"second column displays the value of the constant. The third " \
"column displays the description of the constant."
self.options["header-rows"] = 1
self.options["class"] = ["wy-table-responsive"]
self.options["widths"] = [40, 15, 45]
self.options["width"] = "100%"
headings = ViewList(['* - Constant Name', ' - Value', ' - Description'])
self.content = headings + self.content
return super().run()
def setup(app):
app.add_directive('constants-table', ConstantsTable)

13
doc/src/api_manual/connection.rst
View File

@ -676,6 +676,7 @@ Connection Methods
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:width: 100%
:summary: The first column displays the name of the parameter. The second column displays the data type of the parameter. The third column displays the description of the parameter.
* - Parameter
@ -842,7 +843,7 @@ Connection Methods
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 20 30
:widths: 10 15 20 25
:summary: The first column displays the Node.js Type. The second
column displays the Database type. The third column displays the
Bind type value. The fourth column displays the notes.
@ -972,7 +973,7 @@ Connection Methods
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 5 10 35
:widths: 10 10 30
:summary: The first column displays the property. The second column
displays the data type of the property. The third column displays
the description of the property.
@ -1511,7 +1512,8 @@ Connection Methods
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 12 45
:widths: 10 10 30
:width: 100%
: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.
@ -1712,7 +1714,8 @@ Connection Methods
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 15 40
:widths: 10 10 30
:width: 100%
: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.
@ -2257,6 +2260,7 @@ Connection Methods
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:width: 100%
: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.
@ -2814,6 +2818,7 @@ Connection Methods
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:width: 100%
: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.

2
doc/src/api_manual/deprecations.rst
View File

@ -15,7 +15,7 @@ desupported features are listed first.
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 25 20
:widths: 20 20 15
:width: 100%
:summary: The first column displays the deprecated API method, property, or constant. The second column displays the node-oracledb version in which the API method, property, or constant was deprecated or desupported. The third column displays the API property, method, or constant to use instead, if applicable.

1
doc/src/api_manual/lob.rst
View File

@ -146,6 +146,7 @@ Lob Methods
:class: wy-table-responsive
:align: center
:widths: 15 30
:width: 100%
: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.

267
doc/src/api_manual/oracledb.rst
View File

@ -36,18 +36,8 @@ Query ``outFormat`` Constants
Constants for the query result :attr:`~oracledb.outFormat` option:
.. list-table-with-summary:: Query outFormat Constants
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the query outformat
constant. The second column displays the value of the constant. The
third column displays the description of the constant.
.. constants-table:: Query outFormat Constants
* - Constant Name
- Value
- Description
* - ``oracledb.OUT_FORMAT_ARRAY``
- 4001
- Fetch each row as array of column values.
@ -89,7 +79,8 @@ instead of ``result.metadata[0].fetchType == 2001``.
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:widths: 40 15 45
:width: 100%
:summary: The first column displays the name of the Oracle Database type object. The second column displays the value of the database type object. The third column displays the database data type.
* - DbType Object
@ -204,7 +195,7 @@ for common :ref:`Oracle Database Type Constants <oracledbconstantsdbtype>`.
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 10 30
:widths: 15 10 20 15
:summary: The first column displays the name of the node-oracledb Type
constant. The second column displays the value of the constant. The
third column displays the DB_TYPE equivalent of the constant.
@ -268,18 +259,8 @@ Constants for the ``dir`` property of ``execute()``
These specify whether data values bound to SQL or PL/SQL bind parameters
are passed into, or out from, the database:
.. list-table-with-summary:: Execute Bind Direction Constants
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the Execute Bind Direction
constant. The second column displays the value of the constant. The
third column displays the description of the constant.
.. constants-table:: Execute Bind Direction Constants
* - Constant Name
- Value
- Description
* - ``oracledb.BIND_IN``
- 3001
- Direction for IN binds.
@ -301,18 +282,8 @@ Constants for :meth:`~oracledb.getConnection()`
These specify what privilege should be used by the connection that is
being established.
.. list-table-with-summary:: Privileged Connection Constants
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the Privileged
Connection constant. The second column displays the value of the
constant. The third column displays the description of the constant.
.. constants-table:: Privileged Connection Constants
* - Constant Name
- Value
- Description
* - ``oracledb.SYSASM``
- 32768
- SYSASM privileges
@ -347,18 +318,8 @@ SQL Statement Type Constants
Constants for :meth:`connection.getStatementInfo()` properties.
.. list-table-with-summary:: SQL Statement Type Constants
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the SQL Statement Type
constant. The second column displays the value of the constant. The
third column displays the description of the constant.
.. constants-table:: SQL Statement Type Constants
* - Constant Name
- Value
- Description
* - ``oracledb.STMT_TYPE_ALTER``
- 7
- ALTER
@ -413,18 +374,8 @@ Subscription Constants
Constants for the Continuous Query Notification (CQN)
:ref:`message.type <consubscribeoptcallback>`.
.. list-table-with-summary:: Subscription Constants for the CQN ``message.type`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
message.type property. The second column displays the value of the
constant. The third column displays the description of the constant.
.. constants-table:: Subscription Constants for the CQN ``message.type`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.SUBSCR_EVENT_TYPE_AQ``
- 100
- Advanced Queuing notifications are being used.
@ -449,18 +400,8 @@ Constants for the Continuous Query Notification (CQN)
Constant for the CQN :ref:`groupingClass <consubscribeoptgroupingclass>`.
.. list-table-with-summary:: Subscription Constant for the CQN ``groupingClass`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
groupingClass property. The second column displays the value of the
constant. The third column displays the description of the constant.
.. constants-table:: Subscription Constant for the CQN ``groupingClass`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.SUBSCR_GROUPING_CLASS_TIME``
- 1
- Group notifications by time into a single notification
@ -468,18 +409,8 @@ Constant for the CQN :ref:`groupingClass <consubscribeoptgroupingclass>`.
Constants for the CQN :ref:`groupingType <consubscribeoptgroupingtype>`.
.. list-table-with-summary:: Subscription Constants for the CQN ``groupingType`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
groupingType property. The second column displays the value of the
constant. The third column displays the description of the constant.
.. constants-table:: Subscription Constants for the CQN ``groupingType`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.SUBSCR_GROUPING_TYPE_LAST``
- 2
- The last notification in the group is sent.
@ -489,18 +420,8 @@ Constants for the CQN :ref:`groupingType <consubscribeoptgroupingtype>`.
Constants for the CQN :ref:`qos <consubscribeoptqos>` Quality of Service.
.. list-table-with-summary:: Subscription Constants for the CQN ``qos`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the qos
property. The second column displays the value of the constant. The
third column displays the description of the constant.
.. constants-table:: Subscription Constants for the CQN ``qos`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.SUBSCR_QOS_BEST_EFFORT``
- 16
- When best effort filtering for query result set changes is acceptable. False positive notifications may be received. This behavior may be suitable for caching applications.
@ -519,18 +440,8 @@ Constants for the CQN :ref:`qos <consubscribeoptqos>` Quality of Service.
Constants for the CQN :ref:`namespace <consubscribeoptnamespace>`.
.. list-table-with-summary:: Subscription Constants for the CQN ``namespace`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
namespace property. The second column displays the value of the constant.
The third column displays the description of the constant.
.. constants-table:: Subscription Constants for the CQN ``namespace`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.SUBSCR_NAMESPACE_AQ``
- 1
- For Advanced Queuing notifications.
@ -549,18 +460,8 @@ for more details about attributes.
Constants for :ref:`AqDeqOptions Class <aqdeqoptionsclass>` ``mode``.
.. list-table-with-summary:: Constants for the AqDeqOptions Class ``mode`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
mode property. The second column displays the value of the constant.
The third column displays the description of the constant.
.. constants-table:: Constants for the AqDeqOptions Class ``mode`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.AQ_DEQ_MODE_BROWSE``
- 1
- Read a message without acquiring a lock.
@ -577,18 +478,8 @@ Constants for :ref:`AqDeqOptions Class <aqdeqoptionsclass>` ``mode``.
Constants for :ref:`AqDeqOptions Class <aqdeqoptionsclass>`
``navigation``.
.. list-table-with-summary:: Constants for the AqDeqOptions Class ``navigation`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
navigation property. The second column displays the value of the
constant. The third column displays the description of the constant.
.. constants-table:: Constants for the AqDeqOptions Class ``navigation`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.AQ_DEQ_NAV_FIRST_MSG``
- 1
- Get the message at the head of queue.
@ -601,18 +492,8 @@ Constants for :ref:`AqDeqOptions Class <aqdeqoptionsclass>`
Constants for :ref:`AqDeqOptions Class <aqdeqoptionsclass>` ``wait``.
.. list-table-with-summary:: Constants for the AqDeqOptions Class ``wait`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the wait
property. The second column displays the value of the constant. The
third column displays the description of the constant.
.. constants-table:: Constants for the AqDeqOptions Class ``wait`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.AQ_DEQ_NO_WAIT``
- 0
- Do not wait if no message is available.
@ -623,18 +504,8 @@ Constants for :ref:`AqDeqOptions Class <aqdeqoptionsclass>` ``wait``.
Constants for :ref:`AqEnqOptions Class <aqenqoptionsclass>`
``deliveryMode``.
.. list-table-with-summary:: Constants for the AqDeqOptions Class ``deliveryMode`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
deliveryMode property. The second column displays the value of the
constant. The third column displays the description of the constant.
.. constants-table:: Constants for the AqDeqOptions Class ``deliveryMode`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.AQ_MSG_DELIV_MODE_PERSISTENT``
- 1
- Messages are persistent.
@ -647,18 +518,8 @@ Constants for :ref:`AqEnqOptions Class <aqenqoptionsclass>`
Constants for :ref:`AqMessage Class <aqmessageclass>` ``state``.
.. list-table-with-summary:: Constants for the AqMessage Class ``state`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
state property. The second column displays the value of the constant.
The third column displays the description of the constant.
.. constants-table:: Constants for the AqMessage Class ``state`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.AQ_MSG_STATE_READY``
- 0
- Consumers can dequeue messages that are in the READY state.
@ -675,18 +536,8 @@ Constants for :ref:`AqMessage Class <aqmessageclass>` ``state``.
Constants for :ref:`AqEnqOptions Class <aqenqoptionsclass>` and
:ref:`AqDeqOptions Class <aqdeqoptionsclass>` ``visibility``.
.. list-table-with-summary:: Constants for the AqEnqOptions Class and AqDeqOptions Class ``visibility`` Property
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
visibility property. The second column displays the value of the
constant. The third column displays the description of the constant.
.. constants-table:: Constants for the AqEnqOptions Class and AqDeqOptions Class ``visibility`` Property
* - Constant Name
- Value
- Description
* - ``oracledb.AQ_VISIBILITY_IMMEDIATE``
- 1
- The message is not part of the current transaction. It constitutes a transaction on its own.
@ -707,19 +558,9 @@ the :meth:`connection.subscribe()` method:
- :ref:`operation <consubscribeoptcallback>` property in the
:ref:`message <messageparam>` parameter
.. list-table-with-summary:: Constants for the connection.subscribe() option
.. constants-table:: Constants for the connection.subscribe() option
``operations`` and notification message ``operation`` Properties.
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
operations property. The second column displays the value of the
constant. The third column displays the description of the constant.
* - Constant Name
- Value
- Description
* - ``oracledb.CQN_OPCODE_ALL_OPS``
- 0
- Default. Used to request notification of all operations.
@ -749,18 +590,8 @@ Pool Status Constants
Constants for the connection :attr:`pool.status` read-only attribute.
.. list-table-with-summary:: Constants for the connection ``pool.status`` Attribute
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the constant for the
pool.status attribute. The second column displays the value of the
constant. The third column displays the description of the constant.
.. constants-table:: Constants for the connection ``pool.status`` Attribute
* - Constant Name
- Value
- Description
* - ``oracledb.POOL_STATUS_CLOSED``
- 6002
- The connection pool has been closed.
@ -779,18 +610,8 @@ Constants for the connection :attr:`pool.status` read-only attribute.
Simple Oracle Document Access (SODA) Constants
----------------------------------------------
.. list-table-with-summary:: SODA Constant
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the SODA constant. The
second column displays the value of the constant. The third column
displays the description of the constant.
.. constants-table:: SODA Constant
* - Constant Name
- Value
- Description
* - ``oracledb.SODA_COLL_MAP_MODE``
- 5001
- Indicate :meth:`sodaDatabase.createCollection()` should use an externally created table to store the collection.
@ -805,18 +626,8 @@ Constants for shutting down the Oracle Database with
.. versionadded:: 5.0
.. list-table-with-summary:: Database Shutdown Constants
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the database shutdown
constant. The second column displays the value of the constant. The
third column displays the description of the constant.
.. constants-table:: Database Shutdown Constants
* - Constant Name
- Value
- Description
* - ``oracledb.SHUTDOWN_MODE_ABORT``
- 4
- All uncommitted transactions are terminated and not rolled back. This is the fastest way to shut down the database, but the next database start up may require instance recovery.
@ -845,18 +656,8 @@ Two-Phase Commit Constants
Constants for two-phase commit (TPC) functions
:meth:`connection.tpcBegin()` and :meth:`connection.tpcEnd()`.
.. list-table-with-summary:: Two-Phase Commit Constants
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the two-phase commit
constant name. The second column displays the value of the constant.
The third column displays the description of the constant.
.. constants-table:: Two-Phase Commit Constants
* - Constant Name
- Value
- Description
* - ``oracledb.TPC_BEGIN_JOIN``
- 2
- Join an existing two-phase commit (TPC) transaction.
@ -883,18 +684,8 @@ Vector Type Constants
Constants for the :ref:`vectorFormat <execmetadata>` attribute.
.. list-table-with-summary:: Vector Type Constants
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 10 30
:summary: The first column displays the name of the vector type constant
name. The second column displays the value of the constant. The third
column displays the description of the constant.
.. constants-table:: Vector Type Constants
* - Constant Name
- Value
- Description
* - ``oracledb.VECTOR_FORMAT_FLOAT32``
- 2
- The storage format of each dimension value in the VECTOR column is a 32-bit floating-point number.
@ -2034,7 +1825,7 @@ Oracledb Methods
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 5 7 12 22
:widths: 13 7 12 18
:summary: The first column, Property, displays the property. The second column, Type, displays the data type of the property. The third column, Mode, displays whether the property can be used in the node-oracledb Thin mode, node-oracledb Thick mode, or both node-oracledb modes. The fourth column, Description, displays the description of the property.
* - Property
@ -2608,7 +2399,8 @@ Oracledb Methods
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 55
:widths: 20 80
:width: 100%
:summary: The first column displays the attribute. The second column
displays the description of the attribute.
@ -2769,7 +2561,7 @@ Oracledb Methods
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 5 7 12 22
:widths: 12 7 12 19
:summary: The first column, Property, displays the property. The second column, Type, displays the data type of the property. The third column, Mode, displays whether the property can be used in the node-oracledb Thin mode, node-oracledb Thick mode, or both node-oracledb modes. The fourth column, Description, displays the description of the property.
* - Property
@ -3189,7 +2981,8 @@ Oracledb Methods
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 55
:widths: 20 80
:width: 100%
:summary: The first column displays the attribute. The second column
displays the description of the attribute.

3
doc/src/api_manual/pool.rst
View File

@ -668,7 +668,8 @@ Pool Methods
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 10 55
:widths: 15 35
:width: 100%
:summary: The first column displays the name of the attribute. The
second column displays the description of the attribute.

1
doc/src/api_manual/sodadb.rst
View File

@ -337,6 +337,7 @@ SodaDatabase Methods
:class: wy-table-responsive
:align: center
:widths: 10 10 40
:width: 100%
: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.

3
doc/src/conf.py
View File

@ -21,7 +21,8 @@ sys.path.append(os.path.abspath("_ext"))
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ["table_with_summary", "oracle_desupported", 'sphinx_rtd_theme']
extensions = ["table_with_summary", "oracle_desupported", "constants_table",
'sphinx_rtd_theme']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['.templates']

2
doc/src/user_guide/appendix_a.rst
View File

@ -284,7 +284,7 @@ node-oracledb Thin and Thick modes. For more details see :ref:`modediff`.
* - Oracle Database 21c JSON data type (see :ref:`json21ctype`)
- Yes
- Yes
* - Oracle Database 23ai JSON duality view
* - Oracle Database 23ai JSON-Relational Duality Views (see :ref:`jsondualityviews`)
- Yes
- Yes
* - Oracle Database 23ai BOOLEAN data type (see :ref:`oracledbconstantsdbtype`)

625
doc/src/user_guide/connection_handling.rst
View File

@ -4037,6 +4037,631 @@ containing the ``MY_WALLET_DIRECTORY`` option needs to be created::
They contain important bug fixes for using multiple wallets in the one
process.
.. _configurationprovider:
Connecting Using Centralized Configuration Providers
====================================================
Centralized Configuration Providers enable you to centrally store and manage
the configuration information of your application in a single location on the
cloud. These providers allow you to separately store the configuration
information from the code of your application. The configuration information
that can be stored in these providers includes connect descriptors, and
database credentials such as user name and password. The database password can
be stored separately in a secure vault which is a service offered by these
providers. Also, you can store properties specific to node-oracledb in
centralized configuration providers.
Node-oracledb can securely look up the configuration information stored in the
following configuration providers:
- :ref:`Microsoft Azure App Configuration <azureappconfig>`
- :ref:`Oracle Cloud Infrastructure (OCI) Object Storage <ociobjstorage>`
Using the configuration information from these providers, node-oracledb can
connect to Oracle Database. The centralized configuration provider support is
available from node-oracledb 6.6 onwards in both Thin and Thick modes.
The configuration from these providers can be used to create both
:ref:`standalone connections <standaloneconnection>` and
:ref:`connection pools <connpooling>`. For node-oracledb to be able to
retrieve the Oracle Database connection information from a configuration
provider, you must define the connection string in a specific format in the
``connectString`` property of the :meth:`oracledb.getConnection()` or
:meth:`oracledb.createPool()` methods. The connection string for these
configuration providers must begin with ``config-<azure>`` or
``config-<ociobject>``, contain the URL of the Azure App Configuration or the
OCI Object Storage endpoints, and authentication details.
.. _azureappconfig:
Azure App Configuration Provider
--------------------------------
`Azure App Configuration <https://learn.microsoft.com/en-us/azure/azure-app-
configuration/overview>`__ is a cloud-based service provided by Microsoft
Azure that enables the central management of your application's configuration
information. Your application must be registered with `Microsoft Entra ID
<https://www.microsoft.com/en-in/security/business/identity-access/microsoft
-entra-id>`__ (formerly Microsoft Azure Active Directory) and must have the
required authorization permissions to access the Azure App Configuration
provider.
To use node-oracledb to retrieve the configuration information from Azure App
Configuration, you must install the following libraries:
- `App Configuration <https://www.npmjs.com/package/@azure/
app-configuration>`__ (azure/app-configuration)
- `Azure AD token authentication <https://www.npmjs.com/package/@azure/
identity>`__ (azure/identity)
- `Azure Key Vault <https://www.npmjs.com/package/@azure/keyvault-secrets>`__
(azure/keyvault-secrets) is optional and required only if a password is
stored in the vault
Configuration information is stored as key-value pairs in Azure App
Configuration. You must add the connect descriptor as a key under a prefix
based on the requirements of your application. Optionally, you can add the
database user name, password, and node-oracledb specific properties as
keys. The database password can be stored securely as a secret using
`Azure Key Vault <https://learn.microsoft.com/en-us/azure/key-vault/general/
overview>`__. In Azure App Configuration, you can add the following keys under
a prefix:
- <prefix>connect_descriptor (required)
- <prefix>user (optional)
- <prefix>password (optional)
- <prefix>node-oracledb (optional)
The key ending with:
- ``connect_descriptor`` stores the :ref:`connect descriptor <embedtns>`
as the value.
- ``user`` stores the database user name as the value.
- ``password`` stores the reference to the Azure Key Vault and Secret as
the value.
- ``node-oracledb`` stores the values of the node-oracledb specific
properties. The properties that can be stored in Azure App Configuration
include ``poolMin``, ``poolMax``, ``poolIncrement``, ``poolTimeout``,
``poolPingInterval``, ``poolPingTimeout``, ``stmtCacheSize``,
``prefetchRows``, and ``lobPrefetch``.
See `Oracle Net Service Administrator’s Guide <https://www.oracle.com/pls/
topic/lookup?ctx=dblatest&id=GUID-DBCA9021-F3E1-4B30-8F17-A98900299D73>`__ for
more information.
You must use a connection string containing the configuration provider values
in node-oracledb to access the information stored in Azure App Configuration.
The ``connectString`` property of :meth:`oracledb.getConnection()` or
:meth:`oracledb.createPool()` should be a URL such as::
config-azure://<appconfigname>[?key=<prefix>&label=<value>&<option1>=<value1>&<option2>=<value2>…]
The parameters of the connection string are detailed in the table below.
.. list-table-with-summary:: Connection String Parameters for Azure App Configuration
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 15 15 25
:name: _connection_string_for_azure_app
:summary: The first row displays the name of the connection string parameter. The second row displays whether the connection string parameter is required or optional. The third row displays the description of the connection string parameter.
* - Parameter
- Required or Optional
- Description
* - ``config-azure``
- Required
- Indicates that the configuration provider is Azure App Configuration.
* - ``<appconfigname>``
- Required
- The URL of the App configuration endpoint.
* - ``key=<prefix>``
- Optional
- A key prefix to identify the connection. You can organize configuration information under a prefix as per application requirements.
* - ``label=<value>``
- Optional
- The Azure App Configuration label name.
* - ``<options>=<values>``
- Optional
- The Azure authentication method and corresponding authentication parameters to use when connecting to the Azure App Configuration provider. Each authentication method requires specific parameters to be set which is detailed in the :ref:`Azure Authentication Methods and Their Values <_azure_authentication_methods_and_values>` table.
You can specify one of the following authentication methods:
- **Default Azure Credential**: The authentication to Azure App Configuration is done as a service principal (using either a client secret or client certificate) or as a managed identity depending on which parameters are set. This authentication method also supports reading the parameters as environment variables. This is the default authentication method.
- **Service Principal with Client Secret**: The authentication to Azure App Configuration is done using the client secret.
- **Service Principal with Client Certificate**: The authentication to Azure App Configuration is done using the client certificate.
- **Managed Identity**: The authentication to Azure App Configuration is done using managed identity or managed user identity credentials.
Depending on the specified authentication method, you must also set the
corresponding authentication parameters in the ``option=value`` syntax of the
connection string. The different authentication methods and their
corresponding option values are listed in the table below.
.. list-table-with-summary:: Azure Authentication Methods and Their Values
:header-rows: 1
:class: wy-table-responsive
:name: _azure_authentication_methods_and_values
:summary: The first row displays the authentication method. The second row displays the authentication option values. The third row displays the required parameters for the specified option value. The fourth row displays the optional parameters for the specified option value.
* - Authentication Method
- Authentication Option Values
- Required Parameters for This Option Value
- Optional Parameters for This Option Value
* - Default Azure Credential
- AZURE_DEFAULT (also used when the Authentication method is not set)
-
- AZURE_CLIENT_ID
AZURE_CLIENT_SECRET
AZURE_CLIENT_CERTIFICATE_PATH
AZURE_TENANT_ID
AZURE_MANAGED_IDENTITY_CLIENT_ID
* - Service Principal with client secret
- AZURE_SERVICE_PRINCIPAL
- AZURE_CLIENT_ID
AZURE_CLIENT_SECRET
AZURE_TENANT_ID
-
* - Service Principal with client certificate
- AZURE_SERVICE_PRINCIPAL
- AZURE_CLIENT_ID
AZURE_CLIENT_CERTIFICATE_PATH
AZURE_TENANT_ID
-
* - Managed Identity
- AZURE_MANAGED_IDENTITY
- AZURE_MANAGED_IDENTITY_CLIENT_ID - required only if user assigned
-
Note that the Azure service principal with client certificate overrides Azure
service principal with client secret.
See `Authentication Parameters for Azure App Configuration Store <https://www.
oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-1EECAD82-6CE5-4F4F-A844-
C75C7AA1F907>`__ for more information.
.. _exampleazureappconfig:
Using node-oracledb and Azure App Configuration
+++++++++++++++++++++++++++++++++++++++++++++++
Consider the following table which lists sample configuration information defined
in Azure App Configuration as key-value pairs. Note that the key-value pairs
are defined under the same prefix ``test/`` as an example.
.. list-table-with-summary::
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 30 70
:name: _azure_app_configuration_keys_and_values
:summary: The first row displays the name of the key defined in Azure App Configuration. The second row displays the value of the key defined in Azure App Configuration.
* - Azure App Configuration Key
- Value
* - test/connect_descriptor
- (description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.region.oraclecloud.com))(connect_data=(service_name=cdb1_pdb1)))
* - test/user
- scott
* - test/password
- {"uri":"https://mykeyvault.vault.azure.net/secrets/passwordsalescrm"}
* - test/node-oracledb
- {"stmtCacheSize":30, "prefetchRows":2, "poolMin":2, "poolMax":10}
**Standalone Connections with Azure App Configuration**
:ref:`Standalone connections <standaloneconnection>` can be created with the
configuration information defined in Azure App Configuration. Using the
connection string URL below, you can access the information that is stored
in :ref:`Azure App Configuration <_azure_app_configuration_keys_and_values>`.
.. code-block:: javascript
const connection = await oracledb.getConnection({
connectString : "config-azure://aznetnamingappconfig.azconfig.io/?key=test/&azure_client_id=123-456&azure_client_secret=MYSECRET&azure_tenant_id=789-123"
});
const result = await connection.execute(`SELECT 1 FROM dual`);
console.log(result.rows[0][0]);
Substitute your own values in the connection string to access your Azure App
Configuration service.
Node-oracledb retrieves the necessary connection information from Azure App
Configuration and uses the values of the keys to create a standalone
connection to Oracle Database. For example, the values of the node-oracledb
connection properties will be the key values that were defined in the sample
configuration information in this
:ref:`table <_azure_app_configuration_keys_and_values>`:
.. list-table-with-summary::
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 40 60
:name: _standalone_connection_properties_used
:summary: The first row displays the name of the node-oracledb connection property. The second row displays the value of the connection property.
* - Node-oracledb Connection Property
- Value
* - ``connectString``
- "(description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.region.oraclecloud.com))(connect_data=(service_name=cdb1_pdb1)))"
* - ``user``
- "scott"
* - ``password``
- "manager" (value of secret in URI - for demo purposes)
* - ``stmtCacheSize``
- 30
* - ``prefetchRows``
- 2
**Connection Pools with Azure App Configuration**
:ref:`Connection pools <connpooling>` can be created with the configuration
information defined in Azure App Configuration. Using the connection string
URL below, you can access the information that is stored in
:ref:`Azure App Configuration <_azure_app_configuration_keys_and_values>`.
.. code-block:: javascript
await oracledb.createPool({
connectString : "config-azure://aznetnamingappconfig.azconfig.io/?key=test/&azure_client_id=123-456&azure_client_secret=MYSECRET&azure_tenant_id=789-123"
});
const connection = await oracledb.getConnection();
const result = await connection.execute(`SELECT 1 FROM dual`);
console.log(result.rows[0][0]);
Substitute your own values in the connection string to access your Azure App
Configuration service.
Node-oracledb retrieves the necessary connection information from Azure App
Configuration and uses the values of the keys to create a connection pool to
Oracle Database. For example, the values of the node-oracledb connection
properties will be the key values that were defined in the
sample configuration information in this
:ref:`table <_azure_app_configuration_keys_and_values>`:
.. list-table-with-summary::
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 40 60
:name: _connection_pool_properties_used
:summary: The first row displays the name of the node-oracledb connection property. The second row displays the value of the connection property.
* - Node-oracledb Connection Property
- Value
* - ``connectString``
- "(description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.region.oraclecloud.com))(connect_data=(service_name=cdb1_pdb1)))"
* - ``user``
- "scott"
* - ``password``
- "manager" (value of secret in URI - for demo purposes)
* - ``stmtCacheSize``
- 30
* - ``prefetchRows``
- 2
* - ``poolMin``
- 2
* - ``poolMax``
- 10
**Precedence of Properties**
If you have defined the values of ``user`` and ``password`` in both the
application and Azure App Configuration, then the values defined in the
application will have the higher precedence.
If you are using Thin mode and have defined the node-oracledb specific
properties in both the application and in Azure App Configuration, then the
values defined in the configuration provider will have the higher precedence.
If you are using Thick mode and have defined the node-oracledb properties in
an ``oraaccess.xml`` file, Azure App Configuration, and the application, then
the order of precedence from highest to lowest will be as follows:
- ``oraaccess.xml`` file
- Azure App Configuration
- Application
.. _ociobjstorage:
OCI Object Storage Configuration Provider
-----------------------------------------
`Object Storage <https://docs.oracle.com/en-us/iaas/Content/Object/Concepts/
objectstorageoverview.htm>`__ is a cloud-based service provided by Oracle
Cloud Infrastructure (OCI) that enables the centralized storage and management
of your application's configuration information. Ensure that you have the
necessary authorization permissions to access OCI Object Storage.
To use node-oracledb to retrieve the configuration information from OCI Object
Storage, you must install the following:
- `OCI Node.js Client for Common Utilities <https://www.npmjs.com/package/
oci-common>`__ (oci-common)
- `OCI Node.js Client for ObjectStorage Service <https://www.npmjs.com/package/
oci-objectstorage>`__ (oci-objectstorage)
- `OCI Node.js Client for Secrets Service <https://www.npmjs.com/package/oci-
secrets>`__ (oci-secrets) is optional and required only if a password is
stored in the vault. See `Managing Vault Secrets <https://docs.oracle.com/en
-us/iaas/Content/KeyManagement/Tasks/managingsecrets.htm>`__ for more
information.
Configuration information is stored as a JSON file in OCI Object Storage. You
must add the connect descriptor in the JSON file. Optionally, you can add the
database user name, password, and node-oracledb specific properties in the
JSON file. The database password can also be stored securely as a secret using
`OCI Vault <https://docs.oracle.com/en-us/iaas/Content/KeyManagement/Tasks/
managingsecrets.htm>`__. In OCI Object Storage, you can add the following
sub-objects in the JSON file:
- connect_descriptor (required)
- user (optional)
- password (optional)
- node-oracledb (optional)
Each sub-object is detailed below:
- ``connect_descriptor`` is used to specify the :ref:`connect descriptor <embedtns>`
value.
- ``user`` is used to specify the database user name as the value.
- ``password`` is used to specify the reference to OCI Vault and secret as
the value.
- ``node-oracledb`` is used to specify the values of the node-oracledb specific
properties. The properties that can be stored in OCI Object Storage include
``poolMin``, ``poolMax``, ``poolIncrement``, ``poolTimeout``,
``poolPingInterval``, ``poolPingTimeout``, ``stmtCacheSize``,
``prefetchRows``, and ``lobPrefetch``.
See `Oracle Net Service Administrator’s Guide <https://www.oracle.com/pls/
topic/lookup?ctx=dblatest&id=GUID-B43EA22D-5593-40B3-87FC-C70D6DAF780E>`__.
You must use a connection string containing the configuration provider values
in node-oracledb to access the information stored in OCI Object Storage. The
``connectString`` property of :meth:`oracledb.getConnection()` or
:meth:`oracledb.createPool()` should be a URL such as::
config-ociobject://<objectstorage-name>/n/<namespaceName>/b/<bucketName>/o/
<objectName>[/c/<networkServiceName>][?<option1>=<value1>&<option2>=<value2>...]
The parameters of the connection string are detailed in the table below.
.. list-table-with-summary:: Connection String Parameters for OCI Object Storage
:header-rows: 1
:class: wy-table-responsive
:widths: 15 15 25
:name: _connection_string_for_oci_object_storage
:summary: The first row displays the name of the connection string parameter. The second row displays whether the connection string parameter is required or optional. The third row displays the description of the connection string parameter.
* - Parameter
- Required or Optional
- Description
* - ``config-ociobject``
- Required
- Indicates that the configuration provider is OCI Object Storage.
* - ``<server-name>``
- Required
- The URL of OCI Object Storage endpoint.
* - ``<namespaceName>``
- Required
- The OCI Object Storage namespace where the JSON file is stored.
* - ``<bucketName>``
- Required
- The OCI Object Storage bucket name where the JSON file is stored.
* - ``<objectName>``
- Required
- The JSON file name.
* - ``<networkServiceName>``
- Optional
- The network service name or alias if the JSON file contains one or more network service names.
* - ``<options>`` and ``<values>``
- Optional
- The OCI Object Storage authentication method and corresponding authentication parameters to use when connecting to OCI Object Storage. Each authentication method requires specific parameters to be set which is detailed in the :ref:`table <_oci_authentication_methods>` below.
You can specify one of the following authentication methods in the connection string to access OCI Object Storage:
- **OCI API Key**: The authentication to OCI is done using API key-related values. This is the default authentication method.
- **OCI Instance Principal**: The authentication to OCI is done using VM instance credentials running on OCI.
- **OCI Resource Principal**: The authentication to OCI is done using OCI resource principals.
See `OCI Authentication Methods <https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm>`__ for more information.
Depending on the specified authentication method, you must also set the
corresponding authentication parameters in the ``option=value`` syntax of the
connection string. The different authentication methods and their
corresponding option values are listed in the table below.
.. list-table-with-summary:: OCI Authentication Methods and Their Values
:header-rows: 1
:class: wy-table-responsive
:widths: 10 10 10 10
:name: _oci_authentication_methods
:summary: The first row displays the authentication method. The second row displays the authentication option values. The third row displays the required parameters for the specified option value. The fourth row displays the optional parameters for the specified option value.
* - Authentication Method
- Authentication Option Values
- Optional Configuration
- Optional Parameters
* - API Key-Based Authentication
- OCI_DEFAULT (also used when the Authentication method is not set)
- (~/.oci/config),
(~/.oraclebmc/config), or
environment variable OCI_CONFIG_FILE
- OCI_PROFILE
OCI_TENANCY
OCI_USER
OCI_FINGERPRINT
OCI_KEY_FILE
OCI_PROFILE_PATH
* - Instance Principal Authentication
- OCI_INSTANCE_PRINCIPAL
-
-
* - Resource Principal Authentication
- OCI_RESOURCE_PRINCIPAL
-
-
See `Authentication Parameters for OCI Object Storage <https://www.oracle.com/
pls/topic/lookup?ctx=dblatest&id=GUID-EB94F084-0F3F-47B5-AD77-D111070F7E8D>`__
for more information.
.. _exampleociobjstorage:
Using node-oracledb and OCI Object Storage
++++++++++++++++++++++++++++++++++++++++++
Consider the following sample configuration information is defined in a JSON
file which is stored in OCI Object Storage::
{
"connect_descriptor": "(description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)
(host=adb.region.oraclecloud.com))(connect_data=(service_name=cdb_pdb1))
(security=(ssl_server_dn_match=yes)))",
"user": "scott",
"password": {
"type": "ocivault",
"value": "ocid1.vaultsecret.my-secret-id",
},
"node-oracledb": {
"stmtCacheSize": 30,
"prefetchRows": 2
"poolMin": 2
"poolMax": 10
}
}
**Standalone Connections with OCI Object Storage**
:ref:`Standalone connections <standaloneconnection>` can be created with the
configuration information defined in the JSON file that is stored in OCI
Object Storage. Using the connection string URL below, you can access the
information defined in the :ref:`JSON file <exampleociobjstorage>` above.
.. code-block:: javascript
const connection = await oracledb.getConnection({
connectString : "config-ociobject://abc.oraclecloud.com/n/abcnamespace/b/abcbucket/o/abcobject?oci_tenancy=abc123&oci_user=ociuser1&oci_fingerprint=ab:14:ba:13&oci_key_file=ociabc/ocikeyabc.pem"
});
const result = await connection.execute(`SELECT 1 FROM dual`);
console.log(result.rows[0][0]);
Substitute your own values in the connection string to access your OCI Object
Storage service.
Node-oracledb retrieves the necessary connection information from OCI Object
Storage and uses the values defined in the JSON file to create a standalone
connection to Oracle Database. For example, the values of the node-oracledb
connection properties will be the values that were defined in the
:ref:`sample JSON file <exampleociobjstorage>`:
.. list-table-with-summary::
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 40 60
:name: _standalone_connection_properties_used_oci_object_storage
:summary: The first row displays the name of the node-oracledb connection property. The second row displays the value of the connection property.
* - node-oracledb Connection Property
- Value
* - ``connectString``
- "(description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.region.oraclecloud.com))(connect_data=(service_name=cdb1_pdb1)))"
* - ``user``
- "scott"
* - ``password``
- "manager" (value of secret in URI - for demo purposes)
* - ``stmtCacheSize``
- 30
* - ``prefetchRows``
- 2
**Connection Pools with OCI Object Storage**
:ref:`Connection pools <connpooling>` can be created with the configuration
information defined in the JSON file stored in OCI Object Storage. Using the
connection string URL below, you can access the information defined in the
:ref:`JSON file <exampleociobjstorage>` above.
.. code-block:: javascript
await oracledb.createPool({
connectString : "config-ociobject://abc.oraclecloud.com/n/abcnamespace/b/abcbucket/o/abcobject?oci_tenancy=abc123&oci_user=ociuser1&oci_fingerprint=ab:14:ba:13&oci_key_file=ociabc/ocikeyabc.pem"
});
const connection = await oracledb.getConnection();
const result = await connection.execute(`SELECT 1 FROM dual`);
console.log(result.rows[0][0]);
Substitute your own values in the connection string to access your OCI Object
Storage service.
Node-oracledb retrieves the necessary connection information from OCI Object
Storage and uses the values defined in the JSON file to create a connection
pool to Oracle Database. For example, the values of the node-oracledb
connection properties will be the values that were defined in the
:ref:`sample JSON file <exampleociobjstorage>`:
.. list-table-with-summary::
:header-rows: 1
:class: wy-table-responsive
:align: center
:widths: 40 60
:name: _connection_pool_properties_used_oci_object_storage
:summary: The first row displays the name of the node-oracledb connection property. The second row displays the value of the connection property.
* - node-oracledb Connection Property
- Value
* - ``connectString``
- "(description=(retry_count=20)(retry_delay=3)(address=(protocol=tcps)(port=1521)(host=adb.region.oraclecloud.com))(connect_data=(service_name=cdb1_pdb1)))"
* - ``user``
- "scott"
* - ``password``
- "manager" (value of secret in URI - for demo purposes)
* - ``stmtCacheSize``
- 30
* - ``prefetchRows``
- 2
* - ``poolMin``
- 2
* - ``poolMax``
- 10
**Precedence of Properties**
If you have defined the values of ``user`` and ``password`` in both the
application and OCI Object Storage, then the values defined in the application
will have the higher precedence.
If you are using Thin mode and have defined the node-oracledb specific
properties in both the application and in OCI Object Storage, then the values
defined in the configuration provider will have the higher precedence.
If you are using Thick mode and have defined these node-oracledb properties in
an ``oraaccess.xml`` file, OCI Object Storage, and the application, then the order
precedence from highest to lowest will be as follows:
- ``oraaccess.xml`` file
- OCI Object Storage
- Application
.. _sharding:
Connecting to Sharded Databases

77
doc/src/user_guide/json_data_type.rst
View File

@ -443,6 +443,83 @@ This produces::
{"deptId":30,"name":"Purchasing"}
{"deptId":40,"name":"Human Resources"}
.. _jsondualityviews:
JSON-Relational Duality Views
=============================
Oracle Database 23ai JSON-Relational Duality Views allow data to be stored as
rows in tables to provide the benefits of the relational model and SQL access,
while also allowing read and write access to data as JSON documents for
application simplicity. See the `JSON-Relational Duality Developer's Guide
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=JSNVU>`__ for more
information.
For example, if the tables ``authorTable`` and ``bookTable`` exist::
CREATE TABLE authorTable (
authorId NUMBER GENERATED BY DEFAULT ON NULL AS IDENTITY PRIMARY KEY,
authorName VARCHAR2(100)
);
CREATE TABLE bookTable (
bookId NUMBER GENERATED BY DEFAULT ON NULL AS IDENTITY PRIMARY KEY,
bookTitle VARCHAR2(100),
authorId NUMBER REFERENCES authorTable (authorId)
);
Then a JSON Duality View over the tables can be created using SQL*Plus::
CREATE OR REPLACE JSON RELATIONAL DUALITY VIEW bookDV AS
bookTable @insert @update @delete
{
_id: bookId,
book_title: bookTitle,
author: authorTable @insert @update
{
author_id: authorId,
author_name: authorName
}
};
You can insert into JSON Duality Views using SQL*Plus::
INSERT INTO bookDV VALUES(
'{"book_title": My Book",
"author": {"author_name": "James"}}'
);
Applications can choose whether to use relational access to the underlying
tables, or use the duality view.
Inserting JSON into the view will update the base relational tables:
.. code-block:: javascript
const data = { "_id": 1000, "book_title": "My New Book",
"author": { "author_id": 2000, "author_name": "John Doe" }};
await connection.execute(
`INSERT INTO bookDV VALUES (:bv)`,
{ bv: {val: data, type: oracledb.DB_TYPE_JSON}
);
You can use SQL/JSON to query the view and return JSON. The query uses the
special column ``DATA``:
.. code-block:: javascript
const sql = `SELECT b.data.book_title, b.data.author.author_name FROM
bookDV b WHERE b.data.author.author_id = :1`;
const binds = [1];
const options = {
bindDefs: [ { type: oracledb.NUMBER } ]
};
const result = await connection.execute(sql, binds, options);
console.log(result.rows);
This will print the book title and author name for the author whose id is
``1``.
Portable JSON
=============

7
doc/src/user_guide/vector_data_type.rst
View File

@ -215,7 +215,12 @@ BINARY format to define vectors. The BINARY format represents each dimension
value as a binary value (0 or 1). Binary vectors require less memory storage.
For example, a 16 dimensional vector with BINARY format requires only 2 bytes of
storage while a 16 dimensional vector with INT8 format requires 16 bytes of
storage. The BINARY vector support was introduced in node-oracledb 6.6.
storage.
Binary vectors require the database initialization parameter `COMPATIBLE
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-A2E90F08-BC9F-
4688-A9D0-4A948DD3F7A9>`__ to be set to 23.5.0.0.0 or greater on Oracle
Database. The BINARY vector support was introduced in node-oracledb 6.6.
Binary vectors are represented as 8-bit unsigned integers. For the BINARY
format, you must define the number of dimensions as a multiple of 8. To create