8. API: Data Frames

Python-oracledb can fetch directly to data frames that expose an Apache Arrow PyCapsule Interface. These can be used by many numerical and data analysis libraries.

See Working with Data Frames for more information, including the type mapping from Oracle Database types to Arrow data types.

Note

The data frame support in python-oracledb 3.3 is a pre-release and may change in a future version.

8.1. DataFrame Objects

DataFrame objects are returned from the methods Connection.fetch_df_all() and Connection.fetch_df_batches().

Each column in a DataFrame exposes an Apache Arrow PyCapsule interface, giving access to the underlying Arrow array.

This object is an extension to the DB API definition.

Changed in version 3.3.0: Removed the prefix “Oracle” from the class name.

Added in version 3.0.0.

8.1.1. DataFrame Methods

DataFrame.column_arrays()

Returns a list of ArrowArray objects, each containing a select list column.

DataFrame.column_names()

Returns a list of the column names in the data frame.

DataFrame.get_column(i)

Returns an ArrowArray object for the column at the given index i.

DataFrame.get_column_by_name(name)

Returns an ArrowArray object for the column with the given name name.

DataFrame.num_columns()

Returns the number of columns in the data frame.

DataFrame.num_rows()

Returns the number of rows in the data frame.

8.1.2. DataFrame Attributes

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, showing the number of columns, rows, and chunks, respectively. The number of chunks is always 1 in python-oracledb.

8.2. ArrowArray Objects

ArrowArray objects are returned by DataFrame.column_arrays().

These are used for conversion to PyArrow Tables, see Working with Data Frames.

Changed in version 3.3.0: Removed the prefix “Oracle” from the class name.

Added in version 3.0.0.