From 76b855e98fc665b52eea4339646d39e6ec8dd718 Mon Sep 17 00:00:00 2001 From: Anthony Tuininga Date: Tue, 1 Jun 2021 11:46:00 -0600 Subject: [PATCH] Update SODA documentation. --- doc/src/api_manual/soda.rst | 71 +++++++++++++++++++++++++------------ doc/src/user_guide/soda.rst | 28 +++++++-------- 2 files changed, 62 insertions(+), 37 deletions(-) diff --git a/doc/src/api_manual/soda.rst b/doc/src/api_manual/soda.rst index f71d06f..1e4baf7 100644 --- a/doc/src/api_manual/soda.rst +++ b/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 + `__ + and `Monitoring Database Operations + `__ + 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 + `__ + and `Monitoring Database Operations + `__ + 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 + `__ + and `Monitoring Database Operations + `__ + 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 + `__ + and `Monitoring Database Operations + `__ + 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 diff --git a/doc/src/user_guide/soda.rst b/doc/src/user_guide/soda.rst index 552aa6e..490cafc 100644 --- a/doc/src/user_guide/soda.rst +++ b/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 ` 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 ` 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 ` 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 ====================