Added support for columns of type VECTOR (currently requires access to a

limited availability release of the database).

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -62,6 +62,8 @@ Common Changes
     columns which have the check constraint ``IS JSON FORMAT OSON`` enabled.
 #)  Added boolean property :data:`FetchInfo.is_oson` which is set when a column
     has the check constraint "IS JSON FORMAT OSON" enabled.
+#)  Added support for columns of type vector (currently requires access to a
+    limited availability release of the database).
 #)  Errors raised when calling :meth:`Cursor.executemany()` with PL/SQL now
     have the :data:`oracledb._Error.offset` attribute populated with the last
     iteration that succeeded

src/oracledb/__init__.py

@@ -147,6 +147,10 @@
     # flags for tpc_end()
     TPC_END_NORMAL as TPC_END_NORMAL,
     TPC_END_SUSPEND as TPC_END_SUSPEND,
+    # vector types
+    VECTOR_FORMAT_FLOAT32 as VECTOR_FORMAT_FLOAT32,
+    VECTOR_FORMAT_FLOAT64 as VECTOR_FORMAT_FLOAT64,
+    VECTOR_FORMAT_INT8 as VECTOR_FORMAT_INT8,
 )
 
 from .exceptions import (
@@ -237,6 +241,7 @@
     DB_TYPE_UNKNOWN as DB_TYPE_UNKNOWN,
     DB_TYPE_UROWID as DB_TYPE_UROWID,
     DB_TYPE_VARCHAR as DB_TYPE_VARCHAR,
+    DB_TYPE_VECTOR as DB_TYPE_VECTOR,
     DB_TYPE_XMLTYPE as DB_TYPE_XMLTYPE,
     # API types
     BINARY as BINARY,

src/oracledb/base_impl.pxd

@@ -33,6 +33,7 @@
 
 from libc.stdint cimport int8_t, int16_t, int32_t, int64_t
 from libc.stdint cimport uint8_t, uint16_t, uint32_t, uint64_t
+from cpython cimport array
 
 ctypedef unsigned char char_type
 
@@ -44,7 +45,7 @@ cdef enum:
 
 cdef enum:
     DB_TYPE_NUM_MIN = 2000
-    DB_TYPE_NUM_MAX = 2032
+    DB_TYPE_NUM_MAX = 2033
 
     DB_TYPE_NUM_BFILE = 2020
     DB_TYPE_NUM_BINARY_DOUBLE = 2008
@@ -75,6 +76,7 @@ cdef enum:
     DB_TYPE_NUM_UNKNOWN = 0
     DB_TYPE_NUM_UROWID = 2030
     DB_TYPE_NUM_VARCHAR = 2001
+    DB_TYPE_NUM_VECTOR = 2033
     DB_TYPE_NUM_XMLTYPE = 2032
 
 cdef enum:
@@ -91,6 +93,7 @@ cdef enum:
     NATIVE_TYPE_NUM_ROWID = 3012
     NATIVE_TYPE_NUM_STMT = 3010
     NATIVE_TYPE_NUM_TIMESTAMP = 3005
+    NATIVE_TYPE_NUM_VECTOR = 3017
 
 cdef enum:
     CS_FORM_IMPLICIT = 1
@@ -169,8 +172,10 @@ cdef class Buffer:
     cdef int _write_raw_bytes_and_length(self, const char_type *ptr,
                                          ssize_t num_bytes) except -1
     cdef inline ssize_t bytes_left(self)
-    cdef object parse_binary_double(self, const uint8_t* ptr)
-    cdef object parse_binary_float(self, const uint8_t* ptr)
+    cdef int parse_binary_double(self, const uint8_t* ptr,
+                                 double *double_ptr) except -1
+    cdef int parse_binary_float(self, const uint8_t* ptr,
+                                float *float_ptr) except -1
     cdef object parse_date(self, const uint8_t* ptr, ssize_t num_bytes)
     cdef object parse_interval_ds(self, const uint8_t* ptr)
     cdef object parse_oracle_number(self, const uint8_t* ptr,
@@ -207,8 +212,10 @@ cdef class Buffer:
     cdef inline int skip_ub2(self) except -1
     cdef inline int skip_ub4(self) except -1
     cdef inline int skip_ub8(self) except -1
-    cdef int write_binary_double(self, double value) except -1
-    cdef int write_binary_float(self, float value) except -1
+    cdef int write_binary_double(self, double value,
+                                 bint write_length=*) except -1
+    cdef int write_binary_float(self, float value,
+                                bint write_length=*) except -1
     cdef int write_bool(self, bint value) except -1
     cdef int write_bytes(self, bytes value) except -1
     cdef int write_bytes_with_length(self, bytes value) except -1
@@ -304,6 +311,16 @@ cdef class OsonEncoder(GrowableBuffer):
     cdef int encode(self, object value, ssize_t max_fname_size) except -1
 
 
+cdef class VectorDecoder(Buffer):
+
+    cdef object decode(self, bytes data)
+
+
+cdef class VectorEncoder(GrowableBuffer):
+
+    cdef int encode(self, array.array value) except -1
+
+
 cdef class ConnectParamsNode:
     cdef:
         public bint source_route
@@ -549,6 +566,9 @@ cdef class FetchInfoImpl:
         readonly str domain_schema
         readonly str domain_name
         readonly dict annotations
+        readonly uint32_t vector_dimensions
+        readonly uint8_t vector_format
+        readonly uint8_t vector_flags
 
 
 cdef class BaseVarImpl:

src/oracledb/base_impl.pyx

@@ -39,6 +39,9 @@ from libc.stdint cimport int8_t, int16_t, int32_t, int64_t
 from libc.stdint cimport uint8_t, uint16_t, uint32_t, uint64_t
 from libc.stdint cimport UINT8_MAX, UINT16_MAX, UINT32_MAX, UINT64_MAX
 from libc.string cimport memcpy
+from cpython cimport array
+
+import array
 
 import base64
 import datetime
@@ -71,10 +74,16 @@ cdef type PY_TYPE_TIMEDELTA = datetime.timedelta
 cdef type PY_TYPE_VAR
 cdef type PY_TYPE_FETCHINFO
 
+# purity values
 cdef uint32_t PURITY_NEW = constants.PURITY_NEW
 cdef uint32_t PURITY_SELF = constants.PURITY_SELF
 cdef uint32_t PURITY_DEFAULT = constants.PURITY_DEFAULT
 
+# vector types
+cdef uint8_t VECTOR_FORMAT_FLOAT32 = constants.VECTOR_FORMAT_FLOAT32
+cdef uint8_t VECTOR_FORMAT_FLOAT64 = constants.VECTOR_FORMAT_FLOAT64
+cdef uint8_t VECTOR_FORMAT_INT8 = constants.VECTOR_FORMAT_INT8
+
 cdef const char* ENCODING_UTF8 = "UTF-8"
 cdef const char* ENCODING_UTF16 = "UTF-16BE"
 
@@ -89,6 +98,7 @@ include "impl/base/defaults.pyx"
 include "impl/base/utils.pyx"
 include "impl/base/buffer.pyx"
 include "impl/base/oson.pyx"
+include "impl/base/vector.pyx"
 include "impl/base/connect_params.pyx"
 include "impl/base/pool_params.pyx"
 include "impl/base/connection.pyx"

src/oracledb/constants.py

@@ -155,6 +155,14 @@
 TPC_END_NORMAL = 0
 TPC_END_SUSPEND = 0x00100000
 
+# vector types
+VECTOR_FORMAT_FLOAT32 = 2
+VECTOR_FORMAT_FLOAT64 = 3
+VECTOR_FORMAT_INT8 = 4
+
+# vector metadata flags
+VECTOR_META_FLAG_FLEXIBLE_DIM = 0x01
+
 # basic configuration constants
 DRIVER_NAME = "python-oracledb"
 INSTALLATION_URL = (

src/oracledb/errors.py

@@ -264,6 +264,8 @@ def _raise_err(
 ERR_OSON_FIELD_NAME_LIMITATION = 3020
 ERR_OSON_VERSION_NOT_SUPPORTED = 3021
 ERR_NAMED_TIMEZONE_NOT_SUPPORTED = 3022
+ERR_VECTOR_VERSION_NOT_SUPPORTED = 3023
+ERR_VECTOR_FORMAT_NOT_SUPPORTED = 3024
 
 # error numbers that result in DatabaseError
 ERR_TNS_ENTRY_NOT_FOUND = 4000
@@ -676,6 +678,12 @@ def _raise_err(
         "password verifier type 0x{verifier_type:x} is not supported by "
         "python-oracledb in thin mode"
     ),
+    ERR_VECTOR_FORMAT_NOT_SUPPORTED: (
+        "VECTOR type {vector_format} is not supported"
+    ),
+    ERR_VECTOR_VERSION_NOT_SUPPORTED: (
+        "VECTOR version {version} is not supported"
+    ),
     ERR_WALLET_FILE_MISSING: "wallet file {name} was not found",
     ERR_WRONG_ARRAY_DEFINITION: (
         "expecting a list of two elements [type, numelems]"

src/oracledb/fetch_info.py

@@ -32,6 +32,7 @@
 from typing import Union
 
 from . import __name__ as MODULE_NAME
+from . import constants
 from .dbobject import DbObjectType
 from .base_impl import (
     DbType,
@@ -43,6 +44,7 @@
     DB_TYPE_BINARY_DOUBLE,
     DB_TYPE_BINARY_INTEGER,
     DB_TYPE_NUMBER,
+    DB_TYPE_VECTOR,
 )
 
 
@@ -220,3 +222,28 @@ def type_code(self) -> DbType:
         Returns the type of the column.
         """
         return self._impl.dbtype
+
+    @property
+    def vector_dimensions(self) -> [int, None]:
+        """
+        Returns the number of dimensions required by vector columns. If the
+        column is not a vector column or allows for any number of dimensions,
+        the value returned is None.
+        """
+        if self._impl.dbtype is DB_TYPE_VECTOR:
+            flags = self._impl.vector_flags
+            if not (flags & constants.VECTOR_META_FLAG_FLEXIBLE_DIM):
+                return self._impl.vector_dimensions
+
+    @property
+    def vector_format(self) -> [int, None]:
+        """
+        Returns the storage type required by vector columns. If the column is
+        not a vector column or allows for any type of storage, the value
+        returned is None.
+        """
+        if (
+            self._impl.dbtype is DB_TYPE_VECTOR
+            and self._impl.vector_format != 0
+        ):
+            return self._impl.vector_format

src/oracledb/impl/base/buffer.pyx

@@ -276,15 +276,15 @@ cdef class Buffer:
         """
         return self._size - self._pos
 
-    cdef object parse_binary_double(self, const uint8_t* ptr):
+    cdef int parse_binary_double(self, const uint8_t* ptr,
+                                 double *double_ptr) except -1:
         """
         Read a binary double value from the buffer and return the corresponding
         Python object representing that value.
         """
         cdef:
             uint8_t b0, b1, b2, b3, b4, b5, b6, b7
             uint64_t high_bits, low_bits, all_bits
-            double *double_ptr
         b0 = ptr[0]
         b1 = ptr[1]
         b2 = ptr[2]
@@ -307,18 +307,17 @@ cdef class Buffer:
         high_bits = b0 << 24 | b1 << 16 | b2 << 8 | b3
         low_bits = b4 << 24 | b5 << 16 | b6 << 8 | b7
         all_bits = high_bits << 32 | (low_bits & <uint64_t> 0xffffffff)
-        double_ptr = <double*> &all_bits
-        return double_ptr[0]
+        memcpy(double_ptr, &all_bits, 8)
 
-    cdef object parse_binary_float(self, const uint8_t* ptr):
+    cdef int parse_binary_float(self, const uint8_t* ptr,
+                                float *float_ptr) except -1:
         """
         Parse a binary float value from the buffer and return the corresponding
         Python object representing that value.
         """
         cdef:
             uint8_t b0, b1, b2, b3
             uint64_t all_bits
-            float *float_ptr
         b0 = ptr[0]
         b1 = ptr[1]
         b2 = ptr[2]
@@ -331,8 +330,7 @@ cdef class Buffer:
             b2 = ~b2
             b3 = ~b3
         all_bits = (b0 << 24) | (b1 << 16) | (b2 << 8) | b3
-        float_ptr = <float*> &all_bits
-        return float_ptr[0]
+        memcpy(float_ptr, &all_bits, 4)
 
     cdef object parse_date(self, const uint8_t* ptr, ssize_t num_bytes):
         """
@@ -512,9 +510,11 @@ cdef class Buffer:
         cdef:
             const uint8_t *ptr
             ssize_t num_bytes
+            double value
         self.read_raw_bytes_and_length(&ptr, &num_bytes)
         if ptr != NULL:
-            return self.parse_binary_double(ptr)
+            self.parse_binary_double(ptr, &value)
+            return value
 
     cdef object read_binary_float(self):
         """
@@ -524,9 +524,11 @@ cdef class Buffer:
         cdef:
             const uint8_t *ptr
             ssize_t num_bytes
+            float value
         self.read_raw_bytes_and_length(&ptr, &num_bytes)
         if ptr != NULL:
-            return self.parse_binary_float(ptr)
+            self.parse_binary_float(ptr, &value)
+            return value
 
     cdef object read_binary_integer(self):
         """
@@ -835,7 +837,8 @@ cdef class Buffer:
         """
         return self._skip_int(8, NULL)
 
-    cdef int write_binary_double(self, double value) except -1:
+    cdef int write_binary_double(self, double value,
+                                 bint write_length=True) except -1:
         """
         Writes a double value to the buffer in Oracle canonical double floating
         point format.
@@ -874,10 +877,12 @@ cdef class Buffer:
         buf[5] = b5
         buf[6] = b6
         buf[7] = b7
-        self.write_uint8(8)
+        if write_length:
+            self.write_uint8(8)
         self.write_raw(buf, 8)
 
-    cdef int write_binary_float(self, float value) except -1:
+    cdef int write_binary_float(self, float value,
+                                bint write_length=True) except -1:
         """
         Writes a float value to the buffer in Oracle canonical floating point
         format.
@@ -904,7 +909,8 @@ cdef class Buffer:
         buf[1] = b1
         buf[2] = b2
         buf[3] = b3
-        self.write_uint8(4)
+        if write_length:
+            self.write_uint8(4)
         self.write_raw(buf, 4)
 
     cdef int write_bool(self, bint value) except -1:

src/oracledb/impl/base/connection.pyx

@@ -136,6 +136,12 @@ cdef class BaseConnImpl:
             return bool(value)
         elif db_type_num == DB_TYPE_NUM_JSON:
             return value
+        elif db_type_num == DB_TYPE_NUM_VECTOR:
+            if isinstance(value, list):
+                return array.array('d', value)
+            elif isinstance(value, array.array) \
+                    and value.typecode in ('f', 'd', 'b'):
+                return value
         else:
             if is_ok != NULL:
                 is_ok[0] = False

src/oracledb/impl/base/constants.pxi

@@ -70,6 +70,20 @@ cdef enum:
     TNS_JSON_TYPE_BINARY_FLOAT = 0x7f
     TNS_JSON_TYPE_OBJECT = 0x84
     TNS_JSON_TYPE_ARRAY = 0xc0
+    TNS_JSON_TYPE_EXTENDED = 0x7b
+    TNS_JSON_TYPE_VECTOR = 0x01
+
+# VECTOR constants
+cdef enum:
+    TNS_VECTOR_MAGIC_BYTE = 0xDB
+    TNS_VECTOR_VERSION = 0
+
+# VECTOR flags
+cdef enum:
+    TNS_VECTOR_FLAG_DIM_UINT8 = 0x0001
+    TNS_VECTOR_FLAG_DIM_UINT32 = 0x0002
+    TNS_VECTOR_FLAG_NORM = 0x0008
+    TNS_VECTOR_FLAG_NORM_RESERVED = 0x0040
 
 # general constants
 cdef enum: