Update SODA documentation.

Author: anthony-tuininga

doc/src/api_manual/soda.rst

@@ -256,11 +256,16 @@ SODA Collection Object
 
     The hint parameter, if specified, supplies a hint to the database when
     processing the SODA operation. This is expected to be a string in the same
-    format as SQL hints but without any comment characters, for example
-    ``hint="MONITOR"``. While you could use this to pass any SQL hint, the
-    hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn off
-    monitoring) are the most useful. Use of the hint parameter requires Oracle
-    Client 21.3 or higher (or Oracle Client 19 from 19.11).
+    format as a SQL hint but without any comment characters, for example
+    ``hint="MONITOR"``. Pass only the hint ``"MONITOR"`` (turn on monitoring)
+    or ``"NO_MONITOR"`` (turn off monitoring).  See the Oracle Database SQL
+    Tuning Guide documentation `MONITOR and NO_MONITOR Hints
+    <https://www.oracle.com/pls/topic/lookup?
+    ctx=dblatest&id=GUID-19E0F73C-A959-41E4-A168-91E436DEE1F1>`__
+    and `Monitoring Database Operations
+    <https://www.oracle.com/pls/topic/lookup?
+    ctx=dblatest&id=GUID-C941CE9D-97E1-42F8-91ED-4949B2B710BF>`__
+    for more information.
 
     .. note::
 
@@ -270,7 +275,8 @@ SODA Collection Object
 
     .. versionchanged:: 8.2
 
-        The parameter `hint` was added.
+        The parameter `hint` was added. Use of the hint parameter requires
+        Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).
 
 
 .. method:: SodaCollection.insertOne(doc)
@@ -290,17 +296,23 @@ SODA Collection Object
 
     The hint parameter, if specified, supplies a hint to the database when
     processing the SODA operation. This is expected to be a string in the same
-    format as SQL hints but without any comment characters, for example
-    ``hint="MONITOR"``. While you could use this to pass any SQL hint, the
-    hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn off
-    monitoring) are the most useful. Use of the hint parameter requires Oracle
-    Client 21.3 or higher (or Oracle Client 19 from 19.11).
+    format as a SQL hint but without any comment characters, for example
+    ``hint="MONITOR"``. Pass only the hint ``"MONITOR"`` (turn on monitoring)
+    or ``"NO_MONITOR"`` (turn off monitoring).  See the Oracle Database SQL
+    Tuning Guide documentation `MONITOR and NO_MONITOR Hints
+    <https://www.oracle.com/pls/topic/lookup?
+    ctx=dblatest&id=GUID-19E0F73C-A959-41E4-A168-91E436DEE1F1>`__
+    and `Monitoring Database Operations
+    <https://www.oracle.com/pls/topic/lookup?
+    ctx=dblatest&id=GUID-C941CE9D-97E1-42F8-91ED-4949B2B710BF>`__
+    for more information.
 
     .. versionadded:: 7.0
 
     .. versionchanged:: 8.2
 
-        The parameter `hint` was added.
+        The parameter `hint` was added.  Use of the hint parameter requires
+        Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).
 
 
 .. attribute:: SodaCollection.metadata
@@ -343,11 +355,16 @@ SODA Collection Object
 
     The hint parameter, if specified, supplies a hint to the database when
     processing the SODA operation. This is expected to be a string in the same
-    format as SQL hints but without any comment characters, for example
-    ``hint="MONITOR"``. While you could use this to pass any SQL hint, the
-    hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn off
-    monitoring) are the most useful. Use of the hint parameter requires Oracle
-    Client 21.3 or higher (or Oracle Client 19 from 19.11).
+    format as a SQL hint but without any comment characters, for example
+    ``hint="MONITOR"``. Pass only the hint ``"MONITOR"`` (turn on monitoring)
+    or ``"NO_MONITOR"`` (turn off monitoring).  See the Oracle Database SQL
+    Tuning Guide documentation `MONITOR and NO_MONITOR Hints
+    <https://www.oracle.com/pls/topic/lookup?
+    ctx=dblatest&id=GUID-19E0F73C-A959-41E4-A168-91E436DEE1F1>`__
+    and `Monitoring Database Operations
+    <https://www.oracle.com/pls/topic/lookup?
+    ctx=dblatest&id=GUID-C941CE9D-97E1-42F8-91ED-4949B2B710BF>`__
+    for more information.
 
     This method requires Oracle Client 19.9 or higher in addition to the usual
     SODA requirements.
@@ -356,7 +373,8 @@ SODA Collection Object
 
     .. versionchanged:: 8.2
 
-        The parameter `hint` was added.
+        The parameter `hint` was added. Use of the hint parameter requires
+        Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).
 
 
 .. method:: SodaCollection.truncate()
@@ -565,15 +583,22 @@ SODA Operation Object
 .. method:: SodaOperation.hint(value)
 
     Specifies a hint that will be provided to the SODA operation when it is
-    performed. This is expected to be a string in the same format as SQL hints
-    but without any comment characters. While you could use this to pass any SQL
-    hint, the hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn
-    off monitoring) are the most useful. Use of this method requires Oracle
-    Client 21.3 or higher (or Oracle Client 19 from 19.11).
+    performed. This is expected to be a string in the same format as a SQL hint
+    but without any comment characters, for example ``hint("MONITOR")``. Pass
+    only the hint ``"MONITOR"`` (turn on monitoring) or ``"NO_MONITOR"`` (turn
+    off monitoring). See the Oracle Database SQL Tuning Guide documentation
+    `MONITOR and NO_MONITOR Hints
+    <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-19E0F73C-A959-41E4-A168-91E436DEE1F1>`__
+    and `Monitoring Database Operations
+    <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-C941CE9D-97E1-42F8-91ED-4949B2B710BF>`__
+    for more information.
 
     As a convenience, the SodaOperation object is returned so that further
     criteria can be specified by chaining methods together.
 
+    Use of this method requires Oracle Client 21.3 or higher (or Oracle Client
+    19 from 19.11).
+
     .. versionadded:: 8.2
 
 

doc/src/user_guide/soda.rst

@@ -130,18 +130,6 @@ SODA metadata can be cached to improve the performance of
 :meth:`SodaDatabase.openCollection()` by reducing :ref:`round-trips
 <roundtrips>` to the database. Caching is available with Oracle Client 21.3 (or
 later). The feature is also available in Oracle Client 19 from 19.11 onwards.
-Note: if collection metadata changes are made externally, the cache can become
-invalid.  If this happens, the cache can be cleared by calling
-:meth:`SessionPool.reconfigure()` with ``soda_metadata_cache`` set to `False`,
-or by setting the attribute :attr:`SessionPool.soda_metadata_cache` to `False`.
-A second call to ``reconfigure()`` or a direct setting of the
-``soda_metadata_cache`` attribute can then be performed to re-enable the cache.
-
-Caching can be enabled for pooled connections but not standalone
-connections. Applications using standalone connections should retain and reuse
-the :ref:`collection <sodacoll>` returned from ``createCollection()`` or
-``openCollection()`` wherever possible, instead of making repeated calls to
-those methods.
 
 The metadata cache can be turned on when creating a connection pool with
 :meth:`cx_Oracle.SessionPool()`. Each pool has its own cache:
@@ -153,8 +141,13 @@ The metadata cache can be turned on when creating a connection pool with
                                  dsn="dbhost.example.com/orclpdb1",
                                  soda_metadata_cache=True)
 
-Note the cache is not used by ``createCollection()`` when explicitly passing
-metadata.  In this case, instead of using only ``createCollection()`` and
+The cache is not available for standalone connections. Applications using these
+should retain and reuse the :ref:`collection <sodacoll>` returned from
+``createCollection()`` or ``openCollection()`` wherever possible, instead of
+making repeated calls to those methods.
+
+The cache is not used by ``createCollection()`` when explicitly passing
+metadata. In this case, instead of using only ``createCollection()`` and
 relying on its behavior of opening an existing collection like:
 
 .. code-block:: python
@@ -173,6 +166,13 @@ you will find it more efficient to use logic similar to:
         collection = soda.createCollection("mycollection", mymetadata)
     collection.insertOne(mycontent)
 
+If collection metadata changes are made externally, the cache can become
+invalid. If this happens, the cache can be cleared by calling
+:meth:`SessionPool.reconfigure()` with ``soda_metadata_cache`` set to `False`,
+or by setting the attribute :attr:`SessionPool.soda_metadata_cache` to `False`.
+Use a second call to ``reconfigure()`` or set ``soda_metadata_cache`` to
+re-enable the cache.
+
 Committing SODA Work
 ====================