Merge branch '143-new-uuid-external-types' into 'main'

Annotations: add new UUID, update docs for external types #143

See merge request objectbox/objectbox-dart!105

Author: greenrobot-team

objectbox/lib/src/annotations.dart

@@ -498,6 +498,13 @@ enum ExternalPropertyType {
   /// Encoding: 1:1 binary representation, little endian (16 bytes)
   int128,
 
+  /// A UUID (Universally Unique Identifier) as defined by RFC 9562.
+  ///
+  /// ObjectBox uses the UUIDv7 scheme (timestamp + random) to create new UUIDs.
+  /// UUIDv7 is a good choice for database keys as it's mostly sequential and
+  /// encodes a timestamp. However, if keys are used externally, consider
+  /// [uuidV4] for better privacy by not exposing any time information.
+  ///
   /// Representing type: ByteVector
   ///
   /// Encoding: 1:1 binary representation (16 bytes)
@@ -510,6 +517,33 @@ enum ExternalPropertyType {
   /// Encoding: 1:1 binary representation (16 bytes)
   decimal128,
 
+  /// UUID represented as a string of 36 characters, e.g.
+  /// "019571b4-80e3-7516-a5c1-5f1053d23fff".
+  ///
+  /// For efficient storage, consider the [uuid] type instead, which occupies
+  /// only 16 bytes (20 bytes less). This type may still be a convenient
+  /// alternative as the string type is widely supported and more
+  /// human-readable. In accordance to standards, new UUIDs generated by
+  /// ObjectBox use lowercase hexadecimal digits.
+  ///
+  /// Representing type: String
+  uuidString,
+
+  /// A UUID (Universally Unique Identifier) as defined by RFC 9562.
+  ///
+  /// ObjectBox uses the UUIDv4 scheme (completely random) to create new UUIDs.
+  ///
+  /// Representing type: ByteVector
+  ///
+  /// Encoding: 1:1 binary representation (16 bytes)
+  uuidV4,
+
+  /// Like [uuidString], but using the UUIDv4 scheme (completely random) to
+  /// create new UUID.
+  ///
+  /// Representing type: String
+  uuidV4String,
+
   /// A key/value map; e.g. corresponds to a JSON object or a MongoDB document
   /// (although not keeping the key order).
   ///
@@ -550,7 +584,7 @@ enum ExternalPropertyType {
   /// A vector (array) of Int128 values.
   int128Vector,
 
-  /// A vector (array) of Int128 values
+  /// A vector (array) of Uuid values
   uuidVector,
 
   /// The 12-byte ObjectId type in MongoDB.

objectbox/lib/src/native/bindings/objectbox.h

@@ -479,8 +479,8 @@ typedef enum {
     /// Value range (normalized vectors): 0.0 - 2.0 (0.0: same direction, 1.0: orthogonal, 2.0: opposite direction)
     OBXVectorDistanceType_DotProduct = 3,
 
-    OBXVectorDistanceType_Manhattan = 4,
-    OBXVectorDistanceType_Hamming = 5,
+    // OBXVectorDistanceType_Manhattan = 4,
+    // OBXVectorDistanceType_Hamming = 5,
 
     /// For geospatial coordinates aka latitude/longitude pairs.
     /// Note, that the vector dimension must be 2, with the latitude being the first element and longitude the second.
@@ -625,16 +625,31 @@ typedef enum {
     /// Encoding: 1:1 binary representation, little endian (16 bytes)
     OBXExternalPropertyType_Int128 = 100,
     // OBXExternalPropertyType_Reserved1 = 101,
+    /// A UUID (Universally Unique Identifier) as defined by RFC 9562.
+    /// ObjectBox uses the UUIDv7 scheme (timestamp + random) to create new UUIDs.
+    /// UUIDv7 is a good choice for database keys as it's mostly sequential and encodes a timestamp.
+    /// However, if keys are used externally, consider UuidV4 for better privacy by not exposing any time information.
     /// Representing type: ByteVector
     /// Encoding: 1:1 binary representation (16 bytes)
     OBXExternalPropertyType_Uuid = 102,
     /// IEEE 754 decimal128 type, e.g. supported by MongoDB
     /// Representing type: ByteVector
     /// Encoding: 1:1 binary representation (16 bytes)
     OBXExternalPropertyType_Decimal128 = 103,
-    // OBXExternalPropertyType_Reserved2 = 104,
-    // OBXExternalPropertyType_Reserved3 = 105,
-    // OBXExternalPropertyType_Reserved4 = 106,
+    /// UUID represented as a string of 36 characters, e.g. "019571b4-80e3-7516-a5c1-5f1053d23fff".
+    /// For efficient storage, consider the Uuid type instead, which occupies only 16 bytes (20 bytes less).
+    /// This type may still be a convenient alternative as the string type is widely supported and more human-readable.
+    /// In accordance to standards, new UUIDs generated by ObjectBox use lowercase hexadecimal digits.
+    /// Representing type: String
+    OBXExternalPropertyType_UuidString = 104,
+    /// A UUID (Universally Unique Identifier) as defined by RFC 9562.
+    /// ObjectBox uses the UUIDv4 scheme (completely random) to create new UUIDs.
+    /// Representing type: ByteVector
+    /// Encoding: 1:1 binary representation (16 bytes)
+    OBXExternalPropertyType_UuidV4 = 105,
+    /// Like UuidString, but using the UUIDv4 scheme (completely random) to create new UUID.
+    /// Representing type: String
+    OBXExternalPropertyType_UuidV4String = 106,
     /// A key/value map; e.g. corresponds to a JSON object or a MongoDB document (although not keeping the key order).
     /// Unlike the Flex type, this must contain a map value (e.g. not a vector or a scalar).
     /// Representing type: Flex
@@ -661,7 +676,7 @@ typedef enum {
     /// A vector (array) of Int128 values
     OBXExternalPropertyType_Int128Vector = 116,
     // OBXExternalPropertyType_Reserved9 = 117,
-    /// A vector (array) of Int128 values
+    /// A vector (array) of Uuid values
     OBXExternalPropertyType_UuidVector = 118,
     // OBXExternalPropertyType_Reserved10 = 119,
     // OBXExternalPropertyType_Reserved11 = 120,
@@ -2956,4 +2971,4 @@ OBX_C_API obx_err obx_admin_close(OBX_admin* admin);
 
 #endif  // OBJECTBOX_H
 
-/**@}*/  // end of doxygen group
+/**@}*/  // end of doxygen group

objectbox/lib/src/native/bindings/objectbox_c.dart

@@ -10515,8 +10515,6 @@ abstract class OBXVectorDistanceType {
   /// Because of this, the dot product is often preferred as it performs better.
   /// Value range (normalized vectors): 0.0 - 2.0 (0.0: same direction, 1.0: orthogonal, 2.0: opposite direction)
   static const int DotProduct = 3;
-  static const int Manhattan = 4;
-  static const int Hamming = 5;
 
   /// For geospatial coordinates aka latitude/longitude pairs.
   /// Note, that the vector dimension must be 2, with the latitude being the first element and longitude the second.
@@ -10640,6 +10638,10 @@ abstract class OBXExternalPropertyType {
   /// Encoding: 1:1 binary representation, little endian (16 bytes)
   static const int Int128 = 100;
 
+  /// A UUID (Universally Unique Identifier) as defined by RFC 9562.
+  /// ObjectBox uses the UUIDv7 scheme (timestamp + random) to create new UUIDs.
+  /// UUIDv7 is a good choice for database keys as it's mostly sequential and encodes a timestamp.
+  /// However, if keys are used externally, consider UuidV4 for better privacy by not exposing any time information.
   /// Representing type: ByteVector
   /// Encoding: 1:1 binary representation (16 bytes)
   static const int Uuid = 102;
@@ -10649,6 +10651,23 @@ abstract class OBXExternalPropertyType {
   /// Encoding: 1:1 binary representation (16 bytes)
   static const int Decimal128 = 103;
 
+  /// UUID represented as a string of 36 characters, e.g. "019571b4-80e3-7516-a5c1-5f1053d23fff".
+  /// For efficient storage, consider the Uuid type instead, which occupies only 16 bytes (20 bytes less).
+  /// This type may still be a convenient alternative as the string type is widely supported and more human-readable.
+  /// In accordance to standards, new UUIDs generated by ObjectBox use lowercase hexadecimal digits.
+  /// Representing type: String
+  static const int UuidString = 104;
+
+  /// A UUID (Universally Unique Identifier) as defined by RFC 9562.
+  /// ObjectBox uses the UUIDv4 scheme (completely random) to create new UUIDs.
+  /// Representing type: ByteVector
+  /// Encoding: 1:1 binary representation (16 bytes)
+  static const int UuidV4 = 105;
+
+  /// Like UuidString, but using the UUIDv4 scheme (completely random) to create new UUID.
+  /// Representing type: String
+  static const int UuidV4String = 106;
+
   /// A key/value map; e.g. corresponds to a JSON object or a MongoDB document (although not keeping the key order).
   /// Unlike the Flex type, this must contain a map value (e.g. not a vector or a scalar).
   /// Representing type: Flex
@@ -10676,7 +10695,7 @@ abstract class OBXExternalPropertyType {
   /// A vector (array) of Int128 values
   static const int Int128Vector = 116;
 
-  /// A vector (array) of Int128 values
+  /// A vector (array) of Uuid values
   static const int UuidVector = 118;
 
   /// The 12-byte ObjectId type in MongoDB