Added support for Json ID values.

anthony-tuininga · anthony-tuininga · commit ef3ba1f90692 · 2024-03-08T14:33:52.000-07:00
diff --git a/doc/src/api_manual/module.rst b/doc/src/api_manual/module.rst
@@ -1867,6 +1867,17 @@ Oracledb Methods
     (number of seconds since the epoch; see the documentation of the standard
     Python time module for details).
 
+
+.. _jsonid:
+
+oracledb.JsonId Class
+=====================
+
+Objects of this class are returned by SODA in Oracle Database 23.4 and higher
+in the ``_id`` attribute of documents stored in native collections. It is a
+subclass of the ``bytes`` class.
+
+
 .. _futureobj:
 
 Oracledb.__future__ Object
diff --git a/doc/src/release_notes.rst b/doc/src/release_notes.rst
@@ -67,6 +67,9 @@ 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 class :ref:`oracledb.JsonId <jsonid>` to represent JSON ID values
+    returned by SODA in Oracle Database 23.4 and higher in the ``_id``
+    attribute of documents stored in native collections.
 #)  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
diff --git a/src/oracledb/__init__.py b/src/oracledb/__init__.py
@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2020, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2020, 2024, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -270,6 +270,11 @@
     future as __future__,  # noqa: F401
 )
 
+
+class JsonId(bytes):
+    pass
+
+
 package = sys.modules[__name__]
 base_impl.init_base_impl(package)
 thick_impl.init_thick_impl(package)
diff --git a/src/oracledb/base_impl.pxd b/src/oracledb/base_impl.pxd
@@ -45,7 +45,7 @@ cdef enum:
 
 cdef enum:
     DB_TYPE_NUM_MIN = 2000
-    DB_TYPE_NUM_MAX = 2033
+    DB_TYPE_NUM_MAX = 2034
 
     DB_TYPE_NUM_BFILE = 2020
     DB_TYPE_NUM_BINARY_DOUBLE = 2008
diff --git a/src/oracledb/base_impl.pyx b/src/oracledb/base_impl.pyx
@@ -69,6 +69,7 @@ cdef type PY_TYPE_DATETIME = datetime.datetime
 cdef type PY_TYPE_DECIMAL = decimal.Decimal
 cdef type PY_TYPE_DB_OBJECT
 cdef type PY_TYPE_DB_OBJECT_TYPE
+cdef type PY_TYPE_JSON_ID
 cdef type PY_TYPE_LOB
 cdef type PY_TYPE_TIMEDELTA = datetime.timedelta
 cdef type PY_TYPE_VAR
diff --git a/src/oracledb/impl/base/oson.pyx b/src/oracledb/impl/base/oson.pyx
@@ -163,7 +163,7 @@ cdef class OsonDecoder(Buffer):
         elif node_type == TNS_JSON_TYPE_ID:
             self.read_ub1(&temp8)
             ptr = self._get_raw(temp8)
-            return ptr[:temp8]
+            return PY_TYPE_JSON_ID(ptr[:temp8])
         elif node_type == TNS_JSON_TYPE_BINARY_LENGTH_UINT16:
             self.read_uint16(&temp16)
             ptr = self._get_raw(temp16)
@@ -611,7 +611,10 @@ cdef class OsonTreeSegment(GrowableBuffer):
         # handle bytes
         elif isinstance(value, bytes):
             value_len = len(<bytes> value)
-            if value_len < 65536:
+            if isinstance(value, PY_TYPE_JSON_ID):
+                self.write_uint8(TNS_JSON_TYPE_ID)
+                self.write_uint8(<uint8_t> value_len)
+            elif value_len < 65536:
                 self.write_uint8(TNS_JSON_TYPE_BINARY_LENGTH_UINT16)
                 self.write_uint16(<uint16_t> value_len)
             else:
diff --git a/src/oracledb/impl/base/utils.pyx b/src/oracledb/impl/base/utils.pyx
@@ -201,12 +201,13 @@ def init_base_impl(package):
     """
     global PY_TYPE_ASYNC_CURSOR, PY_TYPE_ASYNC_LOB, PY_TYPE_CURSOR
     global PY_TYPE_DB_OBJECT, PY_TYPE_DB_OBJECT_TYPE, PY_TYPE_LOB, PY_TYPE_VAR
-    global PY_TYPE_FETCHINFO
+    global PY_TYPE_FETCHINFO, PY_TYPE_JSON_ID
     PY_TYPE_ASYNC_CURSOR = package.AsyncCursor
     PY_TYPE_ASYNC_LOB = package.AsyncLOB
     PY_TYPE_CURSOR = package.Cursor
     PY_TYPE_DB_OBJECT = package.DbObject
     PY_TYPE_DB_OBJECT_TYPE = package.DbObjectType
+    PY_TYPE_JSON_ID = package.JsonId
     PY_TYPE_FETCHINFO = package.FetchInfo
     PY_TYPE_LOB = package.LOB
     PY_TYPE_VAR = package.Var
diff --git a/src/oracledb/impl/thick/buffer.pyx b/src/oracledb/impl/thick/buffer.pyx
@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2020, 2022, Oracle and/or its affiliates.
+# Copyright (c) 2020, 2024, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -48,7 +48,7 @@ cdef class StringBuffer:
             self.obj = (<str> value).encode()
             self.size_in_chars = <uint32_t> len(<str> value)
         elif isinstance(value, bytes):
-            self.obj = value
+            self.obj = <bytes> value
             self.size_in_chars = <uint32_t> len(<bytes> value)
         else:
             raise TypeError("expecting string or bytes")
diff --git a/src/oracledb/impl/thick/json.pyx b/src/oracledb/impl/thick/json.pyx
@@ -108,7 +108,9 @@ cdef class JsonBuffer:
             self._add_buf(value, &node.value.asBytes.ptr,
                           &node.value.asBytes.length)
         elif isinstance(value, bytes):
-            node.oracleTypeNum = DPI_ORACLE_TYPE_RAW
+            node.oracleTypeNum = DPI_ORACLE_TYPE_JSON_ID \
+                    if isinstance(value, PY_TYPE_JSON_ID) \
+                    else DPI_ORACLE_TYPE_RAW
             node.nativeTypeNum = DPI_NATIVE_TYPE_BYTES
             self._add_buf(value, &node.value.asBytes.ptr,
                           &node.value.asBytes.length)
diff --git a/src/oracledb/impl/thick/odpi.pxd b/src/oracledb/impl/thick/odpi.pxd
@@ -111,6 +111,7 @@ cdef extern from "impl/thick/odpi/embed/dpi.c":
         DPI_ORACLE_TYPE_INTERVAL_YM
         DPI_ORACLE_TYPE_JSON
         DPI_ORACLE_TYPE_JSON_ARRAY
+        DPI_ORACLE_TYPE_JSON_ID
         DPI_ORACLE_TYPE_JSON_OBJECT
         DPI_ORACLE_TYPE_LONG_NVARCHAR
         DPI_ORACLE_TYPE_LONG_RAW
@@ -342,6 +343,7 @@ cdef extern from "impl/thick/odpi/embed/dpi.c":
         const char *oracleClientLibDir
         const char *oracleClientConfigDir
         bint sodaUseJsonDesc
+        bint useJsonId
 
     ctypedef union dpiDataBuffer:
         bint asBoolean
diff --git a/src/oracledb/impl/thick/utils.pyx b/src/oracledb/impl/thick/utils.pyx
@@ -45,6 +45,7 @@ cdef object _convert_from_json_node(dpiJsonNode *node):
         int32_t seconds
         DbType dbtype
         uint32_t i
+        bytes temp
         str key
     if node.nativeTypeNum == DPI_NATIVE_TYPE_NULL:
         return None
@@ -93,6 +94,9 @@ cdef object _convert_from_json_node(dpiJsonNode *node):
         as_bytes = &node.value.asBytes
         vector_decoder = VectorDecoder.__new__(VectorDecoder)
         return vector_decoder.decode(as_bytes.ptr[:as_bytes.length])
+    elif node.oracleTypeNum == DPI_ORACLE_TYPE_JSON_ID:
+        temp = node.value.asBytes.ptr[:node.value.asBytes.length]
+        return PY_TYPE_JSON_ID(temp)
     dbtype = DbType._from_num(node.oracleTypeNum)
     errors._raise_err(errors.ERR_DB_TYPE_NOT_SUPPORTED, name=dbtype.name)
 
@@ -487,6 +491,7 @@ def init_oracle_client(lib_dir=None, config_dir=None, error_url=None,
         encoding_bytes = constants.ENCODING.encode()
         params.defaultEncoding = encoding_bytes
         params.sodaUseJsonDesc = driver_info.soda_use_json_desc
+        params.useJsonId = True
         if config_dir is None:
             config_dir = C_DEFAULTS.config_dir
         if lib_dir is not None:
@@ -520,6 +525,7 @@ def init_thick_impl(package):
     Initializes globals after the package has been completely initialized. This
     is to avoid circular imports and eliminate the need for global lookups.
     """
-    global PY_TYPE_DB_OBJECT, PY_TYPE_LOB
+    global PY_TYPE_DB_OBJECT, PY_TYPE_JSON_ID, PY_TYPE_LOB
     PY_TYPE_DB_OBJECT = package.DbObject
+    PY_TYPE_JSON_ID = package.JsonId
     PY_TYPE_LOB = package.LOB
diff --git a/src/oracledb/thick_impl.pyx b/src/oracledb/thick_impl.pyx
@@ -85,6 +85,7 @@ include "impl/thick/odpi.pxd"
 cdef type PY_TYPE_DATE = datetime.date
 cdef type PY_TYPE_DATETIME = datetime.datetime
 cdef type PY_TYPE_DECIMAL = decimal.Decimal
+cdef type PY_TYPE_JSON_ID
 cdef type PY_TYPE_DB_OBJECT
 cdef type PY_TYPE_LOB
 cdef type PY_TYPE_TIMEDELTA = datetime.timedelta
diff --git a/tests/test_3400_soda_collection.py b/tests/test_3400_soda_collection.py
@@ -31,6 +31,7 @@
 import json
 import unittest
 
+import oracledb
 import test_env
 
 
@@ -822,10 +823,10 @@ def test_3438(self):
 
         client_version = test_env.get_client_version()
         server_version = test_env.get_server_version()
-        if client_version >= (23, 1) and server_version >= (23, 1):
+        if client_version >= (23, 4) and server_version >= (23, 4):
             id_metadata = {
-                "type": "binary",
-                "o:length": 32,
+                "type": "id",
+                "o:length": 24,
                 "o:preferred_column_name": "DATA$_id",
             }
             self.assertEqual(data_guide["properties"]["_id"], id_metadata)
@@ -973,7 +974,9 @@ def test_3444(self):
                 )
 
     @unittest.skipIf(
-        test_env.get_client_version() < (23, 4), "unsupported data types"
+        test_env.get_client_version() < (23, 4)
+        and test_env.get_server_version() < (23, 4),
+        "unsupported data types",
     )
     def test_3445(self):
         "3445 - test fetching documents with JSON data using extended types"
@@ -993,6 +996,36 @@ def test_3445(self):
         self.assertEqual(fetched_content, val)
         self.assertEqual(doc.getContent(), val)
 
+    @unittest.skipIf(
+        test_env.get_client_version() < (23, 4)
+        and test_env.get_server_version() < (23, 4),
+        "unsupported data types",
+    )
+    def test_3446(self):
+        "3446 - test round-trip of JsonId"
+        soda_db = self.get_soda_database()
+        coll = soda_db.createCollection("TestJsonId")
+        val = {
+            "key1": 5,
+            "key2": "A string",
+            "key3": b"Raw data",
+            "key4": datetime.datetime(2024, 3, 2, 10, 1, 36),
+        }
+        doc = soda_db.createDocument(val)
+        coll.insertOne(doc)
+        self.conn.commit()
+        fetched_doc = coll.find().getDocuments()[0]
+        fetched_content = fetched_doc.getContent()
+        self.assertIs(type(fetched_content["_id"]), oracledb.JsonId)
+        updated_val = val.copy()
+        updated_val["key1"] = 25
+        content = fetched_content.copy()
+        content["key1"] = updated_val["key1"]
+        updated_doc = soda_db.createDocument(content)
+        coll.find().key(fetched_doc.key).replaceOne(updated_doc)
+        fetched_doc = coll.find().getDocuments()[0]
+        self.assertEqual(fetched_doc.getContent(), content)
+
 
 if __name__ == "__main__":
     test_env.run_test_cases()
