Added support for being able to bind a data frame to

cursor.executemany().

Author: anthony-tuininga

doc/src/api_manual/async_connection.rst

@@ -137,9 +137,9 @@ AsyncConnection Methods
 .. method:: AsyncConnection.fetch_df_all(statement, parameters=None, \
             arraysize=None)
 
-    Fetches all rows of the SQL query ``statement``, returning them in an
-    :ref:`OracleDataFrame <oracledataframeobj>` object. An empty
-    OracleDataFrame is returned if there are no rows available.
+    Fetches all rows of the SQL query ``statement``, returning them in a
+    :ref:`DataFrame <oracledataframeobj>` object. An empty DataFrame is
+    returned if there are no rows available.
 
     The ``parameters`` parameter can be a list of tuples, where each tuple item
     maps to one :ref:`bind variable placeholder <bind>` in ``statement``. It
@@ -165,9 +165,8 @@ AsyncConnection Methods
             size=None)
 
     This returns an iterator yielding the next ``size`` rows of the SQL query
-    ``statement`` in each iteration as an :ref:`OracleDataFrame
-    <oracledataframeobj>` object. An empty OracleDataFrame is returned if there
-    are no rows available.
+    ``statement`` in each iteration as a :ref:`DataFrame <oracledataframeobj>`
+    object. An empty DataFrame is returned if there are no rows available.
 
     The ``parameters`` parameter can be a list of tuples, where each tuple item
     maps to one :ref:`bind variable placeholder <bind>` in ``statement``. It

doc/src/api_manual/async_cursor.rst

@@ -170,7 +170,10 @@ AsyncCursor Methods
     list of dictionaries, where the keys match the bind variable placeholder
     names in ``statement``. If there are no bind values, or values have
     previously been bound, the ``parameters`` value can be an integer
-    specifying the number of iterations.
+    specifying the number of iterations. The ``parameters`` parameter can also
+    be a :ref:`DataFrame <oracledataframeobj>`, or a third-party data frame
+    that supports the `Apache Arrow PyCapsule <https://arrow.apache.org/docs/
+    format/CDataInterface/PyCapsuleInterface.html>`__ Interface.
 
     In python-oracledb Thick mode, if the size of the buffers allocated for any
     of the parameters exceeds 2 GB, you will receive the error ``DPI-1015:
@@ -196,6 +199,10 @@ AsyncCursor Methods
     string of length 1 so any values that are later bound as numbers or dates
     will raise a TypeError exception.
 
+    .. versionchanged:: 3.3.0
+
+        Added support for passing data frames in the ``parameters`` parameter.
+
 .. method:: AsyncCursor.fetchall()
 
     Fetches all (remaining) rows of a query result, returning them as a list of

doc/src/api_manual/connection.rst

@@ -119,9 +119,9 @@ Connection Methods
 .. method:: Connection.fetch_df_all(statement, parameters=None, \
             arraysize=None)
 
-    Fetches all rows of the SQL query ``statement``, returning them in an
-    :ref:`OracleDataFrame <oracledataframeobj>` object. An empty
-    OracleDataFrame is returned if there are no rows available.
+    Fetches all rows of the SQL query ``statement``, returning them in a
+    :ref:`DataFrame <oracledataframeobj>` object. An empty DataFrame is
+    returned if there are no rows available.
 
     The ``parameters`` parameter can be a list of tuples, where each tuple item
     maps to one :ref:`bind variable placeholder <bind>` in ``statement``. It
@@ -151,9 +151,8 @@ Connection Methods
             size=None)
 
     This returns an iterator yielding the next ``size`` rows of the SQL query
-    ``statement`` in each iteration as an :ref:`OracleDataFrame
-    <oracledataframeobj>` object. An empty OracleDataFrame is returned if there
-    are no rows available.
+    ``statement`` in each iteration as a :ref:`DataFrame <oracledataframeobj>`
+    object. An empty DataFrame is returned if there are no rows available.
 
     The ``parameters`` parameter can be a list of tuples, where each tuple item
     maps to one :ref:`bind variable placeholder <bind>` in ``statement``. It

doc/src/api_manual/cursor.rst

@@ -176,7 +176,10 @@ Cursor Methods
     list of dictionaries, where the keys match the bind variable placeholder
     names in ``statement``. If there are no bind values, or values have
     previously been bound, the ``parameters`` value can be an integer
-    specifying the number of iterations.
+    specifying the number of iterations. The ``parameters`` parameter can also
+    be a :ref:`DataFrame <oracledataframeobj>`, or a third-party data frame
+    that supports the `Apache Arrow PyCapsule <https://arrow.apache.org/docs/
+    format/CDataInterface/PyCapsuleInterface.html>`__ Interface.
 
     In python-oracledb Thick mode, if the size of the buffers allocated for any
     of the parameters exceeds 2 GB, you will receive the error ``DPI-1015:
@@ -202,6 +205,10 @@ Cursor Methods
     *None* is assumed to be a string of length 1 so any values that are later
     bound as numbers or dates will raise a TypeError exception.
 
+    .. versionchanged:: 3.3.0
+
+        Added support for passing data frames in the ``parameters`` parameter.
+
 .. method:: Cursor.fetchall()
 
     Fetches all (remaining) rows of a query result, returning them as a list of

doc/src/api_manual/dataframe.rst

@@ -18,58 +18,62 @@ from Oracle Database types to Arrow data types.
 
 .. _oracledataframeobj:
 
-OracleDataFrame Objects
-=======================
+DataFrame Objects
+=================
 
-OracleDataFrame objects are returned from the methods
+DataFrame objects are returned from the methods
 :meth:`Connection.fetch_df_all()` and :meth:`Connection.fetch_df_batches()`.
 
-Each column in OracleDataFrame exposes an `Apache Arrow PyCapsule
+Each column in a DataFrame exposes an `Apache Arrow PyCapsule
 <https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html>`__
 interface, giving access to the underlying Arrow array.
 
 .. dbapiobjectextension::
 
+.. versionchanged:: 3.3.0
+
+    Removed the prefix "Oracle" from the class name.
+
 .. versionadded:: 3.0.0
 
 .. _oracledataframemeth:
 
-OracleDataFrame Methods
------------------------
+DataFrame Methods
+-----------------
 
-.. method:: OracleDataFrame.column_arrays()
+.. method:: DataFrame.column_arrays()
 
-    Returns a list of :ref:`OracleArrowArray <oraclearrowarrayobj>` objects,
+    Returns a list of :ref:`ArrowArray <oraclearrowarrayobj>` objects,
     each containing a select list column.
 
-.. method:: OracleDataFrame.column_names()
+.. method:: DataFrame.column_names()
 
     Returns a list of the column names in the data frame.
 
-.. method:: OracleDataFrame.get_column(i)
+.. method:: DataFrame.get_column(i)
 
-    Returns an :ref:`OracleArrowArray <oraclearrowarrayobj>` object for the column
+    Returns an :ref:`ArrowArray <oraclearrowarrayobj>` object for the column
     at the given index ``i``.
 
-.. method:: OracleDataFrame.get_column_by_name(name)
+.. method:: DataFrame.get_column_by_name(name)
 
-    Returns an :ref:`OracleArrowArray <oraclearrowarrayobj>` object for the column
+    Returns an :ref:`ArrowArray <oraclearrowarrayobj>` object for the column
     with the given name ``name``.
 
-.. method:: OracleDataFrame.num_columns()
+.. method:: DataFrame.num_columns()
 
    Returns the number of columns in the data frame.
 
-.. method:: OracleDataFrame.num_rows()
+.. method:: DataFrame.num_rows()
 
    Returns the number of rows in the data frame.
 
 .. _oracledataframeattr:
 
-OracleDataFrame Attributes
---------------------------
+DataFrame Attributes
+--------------------
 
-.. attribute:: OracleDataFrame.metadata
+.. attribute:: DataFrame.metadata
 
     This read-only attribute returns the metadata for the data frame as a
     dictionary with keys ``num_columns``, ``num_rows``, and ``num_chunks``,
@@ -78,14 +82,17 @@ OracleDataFrame Attributes
 
 .. _oraclearrowarrayobj:
 
-OracleArrowArray Objects
-========================
+ArrowArray Objects
+==================
 
-OracleArrowArray objects are returned by
-:meth:`OracleDataFrame.column_arrays()`.
+ArrowArray objects are returned by :meth:`DataFrame.column_arrays()`.
 
 These are used for conversion to `PyArrow Tables
 <https://arrow.apache.org/docs/python/generated/pyarrow.Table.html>`__, see
 :ref:`dataframeformat`.
 
+.. versionchanged:: 3.3.0
+
+    Removed the prefix "Oracle" from the class name.
+
 .. versionadded:: 3.0.0

doc/src/api_manual/module.rst

@@ -2163,6 +2163,19 @@ Oracledb Methods
 
     .. versionadded:: 2.5.0
 
+.. function:: from_arrow(obj)
+
+    This method converts a data frame to a :ref:`DataFrame <oracledataframeobj>`
+    or :ref:`ArrowArray <oraclearrowarrayobj>` instance.
+
+    If ``obj`` supports the Arrow PyCapsule interface ``__arrow_c_stream__``
+    method, then ``from_arrow()`` returns the instance as a :ref:`DataFrame
+    <oracledataframeobj>`. If ``obj`` does not support that method, but does
+    support ``__arrow_c_array__``, then an :ref:`ArrowArray
+    <oraclearrowarrayobj>` is returned.
+
+    .. versionadded:: 3.3.0
+
 .. function:: get_pool(pool_alias)
 
     Returns a :ref:`ConnectionPool object <connpool>` from the python-oracledb

doc/src/release_notes.rst

@@ -42,22 +42,25 @@ Common Changes
 
 #)  Changes to :ref:`data frame <dataframeformat>` support:
 
+    - Added support for binding data frames to :meth:`Cursor.executemany()` and
+      :meth:`AsyncCursor.executemany()` for fast data ingestion. See
+      :ref:`dfinsert`.
     - Added internal support for the ArrowArrayStream PyCapsule interface to
-      simplify :ref:`OracleDataFrame <oracledataframeobj>` use.
-    - Remove use of the DataFrame Interchange Protocol in
-      :ref:`OracleDataFrames <oracledataframeobj>`.
-    - Documentation on methods and attributes on the ``DataFrame`` and
-      ``ArrowArray`` objects are now available in Python plugins such as those
-      found in VS Code
-    - Upgraded Arrow C Data (nanoarrow) API version to 0.7.0
-    - Ensure that the GIL is held when releasing references to ``ArrowArray``
-      objects when exported Arrow buffers are released by the consumer. In
-      some circumstances this could cause a segfault.
+      simplify :ref:`DataFrame <oracledataframeobj>` use.
+    - Remove use of the DataFrame Interchange Protocol in python-oracledb
+      :ref:`DataFrame <oracledataframeobj>` objects.
+    - Documentation on methods and attributes of the :ref:`DataFrame
+      <oracledataframeobj>` and :ref:`ArrowArray <oraclearrowarrayobj>` objects
+      is now available when using IDE introspection.
+    - Upgraded Arrow C Data (nanoarrow) API version to 0.7.0.
+    - Ensure that the GIL is held when releasing references to :ref:`ArrowArray
+      <oraclearrowarrayobj>` objects when exported Arrow buffers are released
+      by the consumer. This avoids a segfault seen in some circumstances.
     - Fixed bug when deciding Arrow datatype for numeric expressions
       (`issue 510 <https://github.com/oracle/python-oracledb/issues/510>`__)
 
     Note the data frame support in python-oracledb 3.3 is a pre-release, and
-    may change in a future version
+    may change in a future version.
 
 oracledb `3.2.0 <https://github.com/oracle/python-oracledb/compare/v3.1.1...v3.2.0>`__ (June 2025)
 --------------------------------------------------------------------------------------------------

doc/src/user_guide/batch_statement.rst

@@ -102,6 +102,9 @@ the bind variable placeholder names:
     cursor.executemany("insert into ParentTable values :pid, :pdesc)", data)
 
 
+A data frame can alternatively be passed to :meth:`Cursor.executemany()`, see
+:ref:`dfinsert`.
+
 .. _predefmemory:
 
 Predefining Memory Areas