From c63115f0cf1611b4148cb314363cad4323b15ba2 Mon Sep 17 00:00:00 2001 From: Sharad Chandran R Date: Tue, 23 Jul 2024 17:09:02 +0530 Subject: [PATCH] Documentation for centralized config provider, JSON Relational Duality View and other updates with formatting improvements --- doc/src/.static/custom.css | 6 + doc/src/_ext/constants_table.py | 52 ++ doc/src/api_manual/connection.rst | 13 +- doc/src/api_manual/deprecations.rst | 2 +- doc/src/api_manual/lob.rst | 1 + doc/src/api_manual/oracledb.rst | 267 +-------- doc/src/api_manual/pool.rst | 3 +- doc/src/api_manual/sodadb.rst | 1 + doc/src/conf.py | 3 +- doc/src/user_guide/appendix_a.rst | 2 +- doc/src/user_guide/connection_handling.rst | 625 +++++++++++++++++++++ doc/src/user_guide/json_data_type.rst | 77 +++ doc/src/user_guide/vector_data_type.rst | 7 +- 13 files changed, 813 insertions(+), 246 deletions(-) create mode 100644 doc/src/_ext/constants_table.py diff --git a/doc/src/.static/custom.css b/doc/src/.static/custom.css index b70d0d370..8ddd95afc 100644 --- a/doc/src/.static/custom.css +++ b/doc/src/.static/custom.css @@ -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; +} diff --git a/doc/src/_ext/constants_table.py b/doc/src/_ext/constants_table.py new file mode 100644 index 000000000..aca396218 --- /dev/null +++ b/doc/src/_ext/constants_table.py @@ -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) diff --git a/doc/src/api_manual/connection.rst b/doc/src/api_manual/connection.rst index 99ac5c137..3679b4ba2 100644 --- a/doc/src/api_manual/connection.rst +++ b/doc/src/api_manual/connection.rst @@ -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. diff --git a/doc/src/api_manual/deprecations.rst b/doc/src/api_manual/deprecations.rst index 63e2d28cb..ba54cd088 100644 --- a/doc/src/api_manual/deprecations.rst +++ b/doc/src/api_manual/deprecations.rst @@ -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. diff --git a/doc/src/api_manual/lob.rst b/doc/src/api_manual/lob.rst index 754d444f2..ff64d0ab6 100644 --- a/doc/src/api_manual/lob.rst +++ b/doc/src/api_manual/lob.rst @@ -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. diff --git a/doc/src/api_manual/oracledb.rst b/doc/src/api_manual/oracledb.rst index d0a1b2112..e4d292174 100644 --- a/doc/src/api_manual/oracledb.rst +++ b/doc/src/api_manual/oracledb.rst @@ -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 `. :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 `. -.. 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 `. -.. 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 `. Constants for the CQN :ref:`groupingType `. -.. 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 `. Constants for the CQN :ref:`qos ` 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 ` Quality of Service. Constants for the CQN :ref:`namespace `. -.. 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 ` ``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 ` ``mode``. Constants for :ref:`AqDeqOptions Class ` ``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 ` Constants for :ref:`AqDeqOptions Class ` ``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 ` ``wait``. Constants for :ref:`AqEnqOptions Class ` ``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 ` Constants for :ref:`AqMessage Class ` ``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 ` ``state``. Constants for :ref:`AqEnqOptions Class ` and :ref:`AqDeqOptions Class ` ``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 ` property in the :ref:`message ` 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 ` 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. diff --git a/doc/src/api_manual/pool.rst b/doc/src/api_manual/pool.rst index 96974b450..02693cb04 100644 --- a/doc/src/api_manual/pool.rst +++ b/doc/src/api_manual/pool.rst @@ -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. diff --git a/doc/src/api_manual/sodadb.rst b/doc/src/api_manual/sodadb.rst index 6122265de..0844b9f77 100644 --- a/doc/src/api_manual/sodadb.rst +++ b/doc/src/api_manual/sodadb.rst @@ -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. diff --git a/doc/src/conf.py b/doc/src/conf.py index ae63bff36..64cb18705 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -21,7 +21,8 @@ # 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'] diff --git a/doc/src/user_guide/appendix_a.rst b/doc/src/user_guide/appendix_a.rst index 8a466d68e..e3bc3c59e 100644 --- a/doc/src/user_guide/appendix_a.rst +++ b/doc/src/user_guide/appendix_a.rst @@ -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`) diff --git a/doc/src/user_guide/connection_handling.rst b/doc/src/user_guide/connection_handling.rst index 5fd78e864..b8153e5cd 100644 --- a/doc/src/user_guide/connection_handling.rst +++ b/doc/src/user_guide/connection_handling.rst @@ -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 ` +- :ref:`Oracle Cloud Infrastructure (OCI) Object Storage ` + +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 ` and +:ref:`connection pools `. 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-`` or +``config-``, 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 `__ 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 +`__ (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 `__ (azure/app-configuration) +- `Azure AD token authentication `__ (azure/identity) +- `Azure Key Vault `__ + (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 `__. In Azure App Configuration, you can add the following keys under +a prefix: + +- connect_descriptor (required) +- user (optional) +- password (optional) +- node-oracledb (optional) + +The key ending with: + +- ``connect_descriptor`` stores the :ref:`connect descriptor ` + 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 `__ 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://[?key=&label=&=&=…] + +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. + * - ```` + - Required + - The URL of the App configuration endpoint. + * - ``key=`` + - Optional + - A key prefix to identify the connection. You can organize configuration information under a prefix as per application requirements. + * - ``label=`` + - Optional + - The Azure App Configuration label name. + * - ``=`` + - 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 `__ 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 ` 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 ` 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 `__ 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 `__ (oci-common) +- `OCI Node.js Client for ObjectStorage Service `__ (oci-objectstorage) +- `OCI Node.js Client for Secrets Service `__ (oci-secrets) is optional and required only if a password is + stored in the vault. See `Managing Vault Secrets `__ 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 `__. 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 ` + 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 `__. + +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:///n//b//o/ + [/c/][?=&=...] + +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. + * - ```` + - Required + - The URL of OCI Object Storage endpoint. + * - ```` + - Required + - The OCI Object Storage namespace where the JSON file is stored. + * - ```` + - Required + - The OCI Object Storage bucket name where the JSON file is stored. + * - ```` + - Required + - The JSON file name. + * - ```` + - Optional + - The network service name or alias if the JSON file contains one or more network service names. + * - ```` and ```` + - 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 `__ 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 `__ +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 ` 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 ` 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 `: + +.. 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 ` 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 ` 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 `: + +.. 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 diff --git a/doc/src/user_guide/json_data_type.rst b/doc/src/user_guide/json_data_type.rst index c73987efa..99c3a3d53 100644 --- a/doc/src/user_guide/json_data_type.rst +++ b/doc/src/user_guide/json_data_type.rst @@ -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 +`__ 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 ============= diff --git a/doc/src/user_guide/vector_data_type.rst b/doc/src/user_guide/vector_data_type.rst index 0d0b5d8eb..fe78ca514 100644 --- a/doc/src/user_guide/vector_data_type.rst +++ b/doc/src/user_guide/vector_data_type.rst @@ -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 +`__ 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