HackBase/python-cx_Oracle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update SODA doc.

Browse Source
This commit is contained in:
Anthony Tuininga 2021-06-01 12:03:03 -06:00
parent a61b14a5c6
commit 59558714ac
2 changed files with 62 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
doc/src/api_manual/soda.rst
View File

@ -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

28
doc/src/user_guide/soda.rst
View File

@ -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
====================