Skip to content

Commit 76b855e

Browse files
anthony-tuiningaanthony-tuininga
committed
Update SODA documentation.
1 parent 4ca3dfd commit 76b855e

File tree

2 files changed

+62
-37
lines changed

2 files changed

+62
-37
lines changed

‎doc/src/api_manual/soda.rst‎

Lines changed: 48 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -256,11 +256,16 @@ SODA Collection Object
256256

257257
The hint parameter, if specified, supplies a hint to the database when
258258
processing the SODA operation. This is expected to be a string in the same
259-
format as SQL hints but without any comment characters, for example
260-
``hint="MONITOR"``. While you could use this to pass any SQL hint, the
261-
hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn off
262-
monitoring) are the most useful. Use of the hint parameter requires Oracle
263-
Client 21.3 or higher (or Oracle Client 19 from 19.11).
259+
format as a SQL hint but without any comment characters, for example
260+
``hint="MONITOR"``. Pass only the hint ``"MONITOR"`` (turn on monitoring)
261+
or ``"NO_MONITOR"`` (turn off monitoring). See the Oracle Database SQL
262+
Tuning Guide documentation `MONITOR and NO_MONITOR Hints
263+
<https://www.oracle.com/pls/topic/lookup?
264+
ctx=dblatest&id=GUID-19E0F73C-A959-41E4-A168-91E436DEE1F1>`__
265+
and `Monitoring Database Operations
266+
<https://www.oracle.com/pls/topic/lookup?
267+
ctx=dblatest&id=GUID-C941CE9D-97E1-42F8-91ED-4949B2B710BF>`__
268+
for more information.
264269

265270
.. note::
266271

@@ -270,7 +275,8 @@ SODA Collection Object
270275

271276
.. versionchanged:: 8.2
272277

273-
The parameter `hint` was added.
278+
The parameter `hint` was added. Use of the hint parameter requires
279+
Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).
274280

275281

276282
.. method:: SodaCollection.insertOne(doc)
@@ -290,17 +296,23 @@ SODA Collection Object
290296

291297
The hint parameter, if specified, supplies a hint to the database when
292298
processing the SODA operation. This is expected to be a string in the same
293-
format as SQL hints but without any comment characters, for example
294-
``hint="MONITOR"``. While you could use this to pass any SQL hint, the
295-
hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn off
296-
monitoring) are the most useful. Use of the hint parameter requires Oracle
297-
Client 21.3 or higher (or Oracle Client 19 from 19.11).
299+
format as a SQL hint but without any comment characters, for example
300+
``hint="MONITOR"``. Pass only the hint ``"MONITOR"`` (turn on monitoring)
301+
or ``"NO_MONITOR"`` (turn off monitoring). See the Oracle Database SQL
302+
Tuning Guide documentation `MONITOR and NO_MONITOR Hints
303+
<https://www.oracle.com/pls/topic/lookup?
304+
ctx=dblatest&id=GUID-19E0F73C-A959-41E4-A168-91E436DEE1F1>`__
305+
and `Monitoring Database Operations
306+
<https://www.oracle.com/pls/topic/lookup?
307+
ctx=dblatest&id=GUID-C941CE9D-97E1-42F8-91ED-4949B2B710BF>`__
308+
for more information.
298309

299310
.. versionadded:: 7.0
300311

301312
.. versionchanged:: 8.2
302313

303-
The parameter `hint` was added.
314+
The parameter `hint` was added. Use of the hint parameter requires
315+
Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).
304316

305317

306318
.. attribute:: SodaCollection.metadata
@@ -343,11 +355,16 @@ SODA Collection Object
343355

344356
The hint parameter, if specified, supplies a hint to the database when
345357
processing the SODA operation. This is expected to be a string in the same
346-
format as SQL hints but without any comment characters, for example
347-
``hint="MONITOR"``. While you could use this to pass any SQL hint, the
348-
hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn off
349-
monitoring) are the most useful. Use of the hint parameter requires Oracle
350-
Client 21.3 or higher (or Oracle Client 19 from 19.11).
358+
format as a SQL hint but without any comment characters, for example
359+
``hint="MONITOR"``. Pass only the hint ``"MONITOR"`` (turn on monitoring)
360+
or ``"NO_MONITOR"`` (turn off monitoring). See the Oracle Database SQL
361+
Tuning Guide documentation `MONITOR and NO_MONITOR Hints
362+
<https://www.oracle.com/pls/topic/lookup?
363+
ctx=dblatest&id=GUID-19E0F73C-A959-41E4-A168-91E436DEE1F1>`__
364+
and `Monitoring Database Operations
365+
<https://www.oracle.com/pls/topic/lookup?
366+
ctx=dblatest&id=GUID-C941CE9D-97E1-42F8-91ED-4949B2B710BF>`__
367+
for more information.
351368

352369
This method requires Oracle Client 19.9 or higher in addition to the usual
353370
SODA requirements.
@@ -356,7 +373,8 @@ SODA Collection Object
356373

357374
.. versionchanged:: 8.2
358375

359-
The parameter `hint` was added.
376+
The parameter `hint` was added. Use of the hint parameter requires
377+
Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).
360378

361379

362380
.. method:: SodaCollection.truncate()
@@ -565,15 +583,22 @@ SODA Operation Object
565583
.. method:: SodaOperation.hint(value)
566584

567585
Specifies a hint that will be provided to the SODA operation when it is
568-
performed. This is expected to be a string in the same format as SQL hints
569-
but without any comment characters. While you could use this to pass any SQL
570-
hint, the hints ``MONITOR`` (turn on monitoring) and ``NO_MONITOR`` (turn
571-
off monitoring) are the most useful. Use of this method requires Oracle
572-
Client 21.3 or higher (or Oracle Client 19 from 19.11).
586+
performed. This is expected to be a string in the same format as a SQL hint
587+
but without any comment characters, for example ``hint("MONITOR")``. Pass
588+
only the hint ``"MONITOR"`` (turn on monitoring) or ``"NO_MONITOR"`` (turn
589+
off monitoring). See the Oracle Database SQL Tuning Guide documentation
590+
`MONITOR and NO_MONITOR Hints
591+
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-19E0F73C-A959-41E4-A168-91E436DEE1F1>`__
592+
and `Monitoring Database Operations
593+
<https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-C941CE9D-97E1-42F8-91ED-4949B2B710BF>`__
594+
for more information.
573595

574596
As a convenience, the SodaOperation object is returned so that further
575597
criteria can be specified by chaining methods together.
576598

599+
Use of this method requires Oracle Client 21.3 or higher (or Oracle Client
600+
19 from 19.11).
601+
577602
.. versionadded:: 8.2
578603

579604

‎doc/src/user_guide/soda.rst‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -130,18 +130,6 @@ SODA metadata can be cached to improve the performance of
130130
:meth:`SodaDatabase.openCollection()` by reducing :ref:`round-trips
131131
<roundtrips>` to the database. Caching is available with Oracle Client 21.3 (or
132132
later). The feature is also available in Oracle Client 19 from 19.11 onwards.
133-
Note: if collection metadata changes are made externally, the cache can become
134-
invalid. If this happens, the cache can be cleared by calling
135-
:meth:`SessionPool.reconfigure()` with ``soda_metadata_cache`` set to `False`,
136-
or by setting the attribute :attr:`SessionPool.soda_metadata_cache` to `False`.
137-
A second call to ``reconfigure()`` or a direct setting of the
138-
``soda_metadata_cache`` attribute can then be performed to re-enable the cache.
139-
140-
Caching can be enabled for pooled connections but not standalone
141-
connections. Applications using standalone connections should retain and reuse
142-
the :ref:`collection <sodacoll>` returned from ``createCollection()`` or
143-
``openCollection()`` wherever possible, instead of making repeated calls to
144-
those methods.
145133

146134
The metadata cache can be turned on when creating a connection pool with
147135
: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
153141
dsn="dbhost.example.com/orclpdb1",
154142
soda_metadata_cache=True)
155143
156-
Note the cache is not used by ``createCollection()`` when explicitly passing
157-
metadata. In this case, instead of using only ``createCollection()`` and
144+
The cache is not available for standalone connections. Applications using these
145+
should retain and reuse the :ref:`collection <sodacoll>` returned from
146+
``createCollection()`` or ``openCollection()`` wherever possible, instead of
147+
making repeated calls to those methods.
148+
149+
The cache is not used by ``createCollection()`` when explicitly passing
150+
metadata. In this case, instead of using only ``createCollection()`` and
158151
relying on its behavior of opening an existing collection like:
159152

160153
.. code-block:: python
@@ -173,6 +166,13 @@ you will find it more efficient to use logic similar to:
173166
collection = soda.createCollection("mycollection", mymetadata)
174167
collection.insertOne(mycontent)
175168
169+
If collection metadata changes are made externally, the cache can become
170+
invalid. If this happens, the cache can be cleared by calling
171+
:meth:`SessionPool.reconfigure()` with ``soda_metadata_cache`` set to `False`,
172+
or by setting the attribute :attr:`SessionPool.soda_metadata_cache` to `False`.
173+
Use a second call to ``reconfigure()`` or set ``soda_metadata_cache`` to
174+
re-enable the cache.
175+
176176
Committing SODA Work
177177
====================
178178

0 commit comments

Comments
 (0)