Documentation improvements.

Author: anthony-tuininga

doc/src/api_manual/soda.rst

@@ -9,13 +9,47 @@ SODA
 allows documents to be inserted, queried, and retrieved from Oracle Database
 using a set of NoSQL-style cx_Oracle methods.
 
-See :ref:`sodausermanual` for a cx_Oracle example.
+See :ref:`user manual <sodausermanual>` for an example.
 
 SODA requires Oracle Client 18.3 or higher and Oracle Database 18.1 and higher.
 The role SODA_APP must be granted to the user.
 
-See
-`this tracking issue <https://github.com/oracle/python-cx_Oracle/issues/309>`__ for known issues with SODA.
+.. note::
+
+    If you are using Oracle Database 21c (or later) and create new collections
+    you need to do one of the following:
+
+    - Use Oracle Client libraries 21c (or later).
+
+    - Or, explicitly use collection metadata when creating collections and set
+      the data storage type to BLOB, for example::
+
+        {
+            "keyColumn": {
+                "name":"ID"
+            },
+            "contentColumn": {
+                "name": "JSON_DOCUMENT",
+                "sqlType": "BLOB"
+            },
+            "versionColumn": {
+                "name": "VERSION",
+                "method": "UUID"
+            },
+            "lastModifiedColumn": {
+                "name": "LAST_MODIFIED"
+            },
+            "creationTimeColumn": {
+                "name": "CREATED_ON"
+            }
+        }
+
+    - Or, set the database initialization parameter `compatible
+      <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
+      id=GUID-A2E90F08-BC9F-4688-A9D0-4A948DD3F7A9>`__ to 19 or lower.
+
+    Otherwise you may get errors such as "ORA-40659: Data type does not match
+    the specification in the collection metadata".
 
 .. _sodadb:
 

doc/src/index.rst

@@ -56,7 +56,7 @@ API Manual
     api_manual/lob.rst
     api_manual/object_type.rst
     api_manual/aq.rst
-    Soda Document Class <api_manual/soda.rst>
+    api_manual/soda.rst
 
 
 Indices and tables

doc/src/user_guide/bind.rst

@@ -278,6 +278,8 @@ return type of :meth:`Cursor.callfunc()`:
     for row in refCursor:
         print(row)
 
+See :ref:`tuning` for information on how to tune REF CURSORS.
+
 Binding PL/SQL Collections
 ==========================
 

doc/src/user_guide/initialization.rst

@@ -382,6 +382,6 @@ not specified, then the value "cx_Oracle : *version*" is used.
 
 The ``error_url`` string will be shown in the exception raised if
 ``init_oracle_client()`` cannot load the Oracle Client libraries.  This allows
-applications that use node-oracledb to refer users to application-specific
+applications that use cx_Oracle to refer users to application-specific
 installation instructions.  If this value is not specified, then the
 :ref:`installation` URL is used.

doc/src/user_guide/tuning.rst

@@ -214,6 +214,30 @@ data from one database to another:
 
 .. _roundtrips:
 
+Tuning REF CURSORS
+++++++++++++++++++
+
+In cx_Oracle, REF CURSORS can also be tuned by setting the values of ``arraysize``
+and ``prefetchrows``. The prefetchrows value must be set before calling the PL/SQL
+procedure as the REF CURSOR is executed on the server.
+
+For example:
+
+.. code-block:: python
+
+    # Set the arraysize and prefetch rows of the REF cursor
+    ref_cursor = connection.cursor()
+    ref_cursor.prefetchrows = 1000
+    ref_cursor.arraysize = 1000
+
+    # Perform the tuned fetch
+    sum_rows = 0
+    cursor.callproc("myrefcursorproc", [ref_cursor])
+    print("Sum of IntCol for", num_rows, "rows:")
+    for row in ref_cursor:
+        sum_rows += row[0]
+    print(sum_rows)
+
 Database Round-trips
 ====================