Add UUIDv7-generating functions

docs/en/sql-reference/data-types/uuid.md

@@ -8,7 +8,8 @@ sidebar_label: UUID
 
 A Universally Unique Identifier (UUID) is a 16-byte value used to identify records. For detailed information about UUIDs, see [Wikipedia](https://en.wikipedia.org/wiki/Universally_unique_identifier).
 
-While different UUID variants exist (see [here](https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis)), ClickHouse does not validate that inserted UUIDs conform to a particular variant. UUIDs are internally treated as a sequence of 16 random bytes with [8-4-4-4-12 representation](https://en.wikipedia.org/wiki/Universally_unique_identifier#Textual_representation) at SQL level.
+While different UUID variants exist (see [here](https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis)), ClickHouse does not validate that inserted UUIDs conform to a particular variant.
+UUIDs are internally treated as a sequence of 16 random bytes with [8-4-4-4-12 representation](https://en.wikipedia.org/wiki/Universally_unique_identifier#Textual_representation) at SQL level.
 
 Example UUID value:
 
@@ -22,6 +23,46 @@ The default UUID is all-zero. It is used, for example, when a new record is inse
 00000000-0000-0000-0000-000000000000
 ```
 
+Due to historical reasons, UUIDs are sorted by their second half (which is unintuitive).
+UUIDs should therefore not be used in an primary key (or sorting key) of a table, or as partition key.
+
+Example:
+
+``` sql
+CREATE TABLE tab (uuid UUID) ENGINE = Memory;
+INSERT INTO tab SELECT generateUUIDv4() FROM numbers(50);
+SELECT * FROM tab ORDER BY uuid;
+```
+
+Result:
+
+``` text
+┌─uuid─────────────────────────────────┐
+│ 36a0b67c-b74a-4640-803b-e44bb4547e3c │
+│ 3a00aeb8-2605-4eec-8215-08c0ecb51112 │
+│ 3fda7c49-282e-421a-85ab-c5684ef1d350 │
+│ 16ab55a7-45f6-44a8-873c-7a0b44346b3e │
+│ e3776711-6359-4f22-878d-bf290d052c85 │
+│ 1be30226-57b2-4739-88ec-5e3d490090f2 │
+│ f65853a9-4375-4f0e-8b96-906ff622ed3c │
+│ d5a0c7a6-79c6-4107-8bb8-df85915edcb7 │
+│ 258e6068-17d1-4a1a-8be3-ed2ceb21815c │
+│ 04b0f6a9-1f7b-4a42-8bfc-62f37b8a32b8 │
+│ 9924f0d9-9c16-43a9-8f08-0944ab495aed │
+│ 6720dc14-4eab-4e3e-8f0c-10c4ae8d2673 │
+│ 5ddadb52-0452-4f5d-9030-c3f969af93a4 │
+│                [...]                 │
+│ 2dde30e6-59a1-48f8-b260-eb37921185b6 │
+│ d5402a1b-77b3-4897-b288-29edf5c3ed12 │
+│ 01843939-3ba7-4fea-b2aa-45f9a6f1e057 │
+│ 9eceda2f-6946-40e3-b725-16f2709ca41a │
+│ 03644f74-47ba-4020-b865-be5fd4c8c7ff │
+│ ce3bc93d-ab19-4c74-b8cc-737cb9212099 │
+│ b7ad6c91-23d6-4b5e-b8e4-a52297490b56 │
+│ 06892f64-cc2d-45f3-bf86-f5c5af5768a9 │
+└──────────────────────────────────────┘
+```
+
 ## Generating UUIDs
 
 ClickHouse provides the [generateUUIDv4](../../sql-reference/functions/uuid-functions.md) function to generate random UUID version 4 values.

src/Functions/FunctionsCodingUUID.cpp

@@ -1,14 +1,18 @@
 #include <Columns/ColumnDecimal.h>
+#include <Columns/ColumnsDateTime.h>
 #include <Columns/ColumnFixedString.h>
 #include <Columns/ColumnString.h>
+#include <Columns/ColumnsNumber.h>
 #include <Columns/ColumnVector.h>
 #include <Common/BitHelpers.h>
 #include <base/hex.h>
 #include <DataTypes/DataTypeString.h>
 #include <DataTypes/DataTypeFixedString.h>
+#include <DataTypes/DataTypeUUID.h>
 #include <Functions/FunctionFactory.h>
 #include <Functions/IFunction.h>
 #include <Functions/FunctionHelpers.h>
+#include <Functions/extractTimeZoneFromFunctionArguments.h>
 #include <IO/WriteHelpers.h>
 #include <Interpreters/Context_fwd.h>
 #include <Interpreters/castColumn.h>
@@ -17,11 +21,11 @@
 
 namespace DB::ErrorCodes
 {
-extern const int ARGUMENT_OUT_OF_BOUND;
-extern const int ILLEGAL_COLUMN;
-extern const int ILLEGAL_TYPE_OF_ARGUMENT;
-extern const int LOGICAL_ERROR;
-extern const int NUMBER_OF_ARGUMENTS_DOESNT_MATCH;
+    extern const int ARGUMENT_OUT_OF_BOUND;
+    extern const int ILLEGAL_COLUMN;
+    extern const int ILLEGAL_TYPE_OF_ARGUMENT;
+    extern const int LOGICAL_ERROR;
+    extern const int NUMBER_OF_ARGUMENTS_DOESNT_MATCH;
 }
 
 namespace
@@ -32,7 +36,7 @@ enum class Representation
     LittleEndian
 };
 
-std::pair<int, int> determineBinaryStartIndexWithIncrement(const ptrdiff_t num_bytes, const Representation representation)
+std::pair<int, int> determineBinaryStartIndexWithIncrement(ptrdiff_t num_bytes, Representation representation)
 {
     if (representation == Representation::BigEndian)
         return {0, 1};
@@ -42,15 +46,15 @@ std::pair<int, int> determineBinaryStartIndexWithIncrement(const ptrdiff_t num_b
     throw DB::Exception(DB::ErrorCodes::LOGICAL_ERROR, "{} is not handled yet", magic_enum::enum_name(representation));
 }
 
-void formatHex(const std::span<const UInt8> src, UInt8 * dst, const Representation representation)
+void formatHex(const std::span<const UInt8> src, UInt8 * dst, Representation representation)
 {
     const auto src_size = std::ssize(src);
     const auto [src_start_index, src_increment] = determineBinaryStartIndexWithIncrement(src_size, representation);
     for (int src_pos = src_start_index, dst_pos = 0; src_pos >= 0 && src_pos < src_size; src_pos += src_increment, dst_pos += 2)
         writeHexByteLowercase(src[src_pos], dst + dst_pos);
 }
 
-void parseHex(const UInt8 * __restrict src, const std::span<UInt8> dst, const Representation representation)
+void parseHex(const UInt8 * __restrict src, const std::span<UInt8> dst, Representation representation)
 {
     const auto dst_size = std::ssize(dst);
     const auto [dst_start_index, dst_increment] = determineBinaryStartIndexWithIncrement(dst_size, representation);
@@ -322,10 +326,191 @@ class FunctionUUIDStringToNum : public IFunction
     }
 };
 
+
+class FunctionUUIDToNum : public IFunction
+{
+public:
+    static constexpr auto name = "UUIDToNum";
+    static FunctionPtr create(ContextPtr) { return std::make_shared<FunctionUUIDToNum>(); }
+
+    String getName() const override { return name; }
+    size_t getNumberOfArguments() const override { return 0; }
+    bool useDefaultImplementationForConstants() const override { return true; }
+    ColumnNumbers getArgumentsThatAreAlwaysConstant() const override { return {1}; }
+    bool isInjective(const ColumnsWithTypeAndName &) const override { return true; }
+    bool isSuitableForShortCircuitArgumentsExecution(const DataTypesWithConstInfo & /*arguments*/) const override { return false; }
+    bool isVariadic() const override { return true; }
+
+    DataTypePtr getReturnTypeImpl(const DataTypes & arguments) const override
+    {
+        checkArgumentCount(arguments, name);
+
+        if (!isUUID(arguments[0]))
+        {
+            throw Exception(
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT,
+                "Illegal type {} of first argument of function {}, expected UUID",
+                arguments[0]->getName(),
+                getName());
+        }
+
+        checkFormatArgument(arguments, name);
+
+        return std::make_shared<DataTypeFixedString>(uuid_bytes_length);
+    }
+
+    ColumnPtr executeImpl(const ColumnsWithTypeAndName & arguments, const DataTypePtr &, size_t /*input_rows_count*/) const override
+    {
+        const ColumnWithTypeAndName & col_type_name = arguments[0];
+        const ColumnPtr & column = col_type_name.column;
+
+        const bool defaultFormat = (parseVariant(arguments) == UUIDSerializer::Variant::Default);
+
+        if (const auto * col_in = checkAndGetColumn<ColumnUUID>(column.get()))
+        {
+            const auto & vec_in = col_in->getData();
+            const UUID * uuids = vec_in.data();
+            const size_t size = vec_in.size();
+
+            auto col_res = ColumnFixedString::create(uuid_bytes_length);
+
+            ColumnString::Chars & vec_res = col_res->getChars();
+            vec_res.resize(size * uuid_bytes_length);
+
+            size_t dst_offset = 0;
+
+            for (size_t i = 0; i < size; ++i)
+            {
+                uint64_t hiBytes = DB::UUIDHelpers::getHighBytes(uuids[i]);
+                uint64_t loBytes = DB::UUIDHelpers::getLowBytes(uuids[i]);
+                unalignedStoreBigEndian<uint64_t>(&vec_res[dst_offset], hiBytes);
+                unalignedStoreBigEndian<uint64_t>(&vec_res[dst_offset + sizeof(hiBytes)], loBytes);
+                if (!defaultFormat)
+                {
+                    std::swap(vec_res[dst_offset], vec_res[dst_offset + 3]);
+                    std::swap(vec_res[dst_offset + 1], vec_res[dst_offset + 2]);
+                    std::swap(vec_res[dst_offset + 4], vec_res[dst_offset + 5]);
+                    std::swap(vec_res[dst_offset + 6], vec_res[dst_offset + 7]);
+                }
+                dst_offset += uuid_bytes_length;
+            }
+
+            return col_res;
+        }
+        else
+            throw Exception(
+                ErrorCodes::ILLEGAL_COLUMN, "Illegal column {} of argument of function {}", arguments[0].column->getName(), getName());
+    }
+};
+
+class FunctionUUIDv7ToDateTime : public IFunction
+{
+public:
+    static constexpr auto name = "UUIDv7ToDateTime";
+    static FunctionPtr create(ContextPtr) { return std::make_shared<FunctionUUIDv7ToDateTime>(); }
+
+    static constexpr UInt32 datetime_scale = 3;
+
+    String getName() const override { return name; }
+    size_t getNumberOfArguments() const override { return 0; }
+    bool useDefaultImplementationForConstants() const override { return true; }
+    ColumnNumbers getArgumentsThatAreAlwaysConstant() const override { return {1}; }
+    bool isSuitableForShortCircuitArgumentsExecution(const DataTypesWithConstInfo & /*arguments*/) const override { return false; }
+    bool isVariadic() const override { return true; }
+
+    DataTypePtr getReturnTypeImpl(const ColumnsWithTypeAndName & arguments) const override
+    {
+        if (arguments.empty() || arguments.size() > 2)
+            throw Exception(
+                ErrorCodes::NUMBER_OF_ARGUMENTS_DOESNT_MATCH, "Wrong number of arguments for function {}: should be 1 or 2", getName());
+
+        if (!checkAndGetDataType<DataTypeUUID>(arguments[0].type.get()))
+        {
+            throw Exception(
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT,
+                "Illegal type {} of first argument of function {}, expected UUID",
+                arguments[0].type->getName(),
+                getName());
+        }
+
+        String timezone;
+        if (arguments.size() == 2)
+        {
+            timezone = extractTimeZoneNameFromColumn(arguments[1].column.get(), arguments[1].name);
+
+            if (timezone.empty())
+                throw Exception(
+                    ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT,
+                    "Function {} supports a 2nd argument (optional) that must be a valid time zone",
+                    getName());
+        }
+
+        return std::make_shared<DataTypeDateTime64>(datetime_scale, timezone);
+    }
+
+    ColumnPtr executeImpl(const ColumnsWithTypeAndName & arguments, const DataTypePtr &, size_t /*input_rows_count*/) const override
+    {
+        const ColumnWithTypeAndName & col_type_name = arguments[0];
+        const ColumnPtr & column = col_type_name.column;
+
+        if (const auto * col_in = checkAndGetColumn<ColumnUUID>(column.get()))
+        {
+            const auto & vec_in = col_in->getData();
+            const UUID * uuids = vec_in.data();
+            const size_t size = vec_in.size();
+
+            auto col_res = ColumnDateTime64::create(size, datetime_scale);
+            auto & vec_res = col_res->getData();
+
+            for (size_t i = 0; i < size; ++i)
+            {
+                const uint64_t hiBytes = DB::UUIDHelpers::getHighBytes(uuids[i]);
+                const uint64_t ms = ((hiBytes & 0xf000) == 0x7000) ? (hiBytes >> 16) : 0;
+
+                vec_res[i] = DecimalUtils::decimalFromComponents<DateTime64>(ms / intExp10(datetime_scale), ms % intExp10(datetime_scale), datetime_scale);
+            }
+
+            return col_res;
+        }
+        else
+            throw Exception(
+                ErrorCodes::ILLEGAL_COLUMN, "Illegal column {} of argument of function {}", arguments[0].column->getName(), getName());
+    }
+};
+
 REGISTER_FUNCTION(CodingUUID)
 {
     factory.registerFunction<FunctionUUIDNumToString>();
     factory.registerFunction<FunctionUUIDStringToNum>();
+    factory.registerFunction<FunctionUUIDToNum>(
+        FunctionDocumentation{
+            .description = R"(
+This function accepts a UUID and returns a FixedString(16) as its binary representation, with its format optionally specified by variant (Big-endian by default).
+)",
+            .examples{
+                {"uuid",
+                 "select toUUID(UUIDNumToString(toFixedString('a/<@];!~p{jTj={)', 16))) as uuid, UUIDToNum(uuid) as uuidNum, "
+                 "UUIDToNum(uuid, 2) as uuidMsNum",
+                 R"(
+┌─uuid─────────────────────────────────┬─uuidNum──────────┬─uuidMsNum────────┐
+│ 612f3c40-5d3b-217e-707b-6a546a3d7b29 │ a/<@];!~p{jTj={) │ @</a];!~p{jTj={) │
+└──────────────────────────────────────┴──────────────────┴──────────────────┘
+)"}},
+            .categories{"UUID"}},
+        FunctionFactory::CaseSensitive);
+
+    factory.registerFunction<FunctionUUIDv7ToDateTime>(
+        FunctionDocumentation{
+            .description = R"(
+This function extracts the timestamp from a UUID and returns it as a DateTime64(3) typed value.
+The function expects the UUID having version 7 to be provided as the first argument.
+An optional second argument can be passed to specify a timezone for the timestamp.
+)",
+            .examples{
+                {"uuid","select UUIDv7ToDateTime(generateUUIDv7())", ""},
+                {"uuid","select generateUUIDv7() as uuid, UUIDv7ToDateTime(uuid), UUIDv7ToDateTime(uuid, 'America/New_York')", ""}},
+            .categories{"UUID"}},
+        FunctionFactory::CaseSensitive);
 }
 
 }

src/Functions/generateUUIDv4.cpp

@@ -1,15 +1,11 @@
+#include <DataTypes/DataTypeUUID.h>
 #include <Functions/FunctionFactory.h>
+#include <Functions/FunctionHelpers.h>
 #include <Functions/FunctionsRandom.h>
-#include <DataTypes/DataTypeUUID.h>
 
 namespace DB
 {
 
-namespace ErrorCodes
-{
-    extern const int NUMBER_OF_ARGUMENTS_DOESNT_MATCH;
-}
-
 #define DECLARE_SEVERAL_IMPLEMENTATIONS(...) \
 DECLARE_DEFAULT_CODE      (__VA_ARGS__) \
 DECLARE_AVX2_SPECIFIC_CODE(__VA_ARGS__)
@@ -21,30 +17,26 @@ class FunctionGenerateUUIDv4 : public IFunction
 public:
     static constexpr auto name = "generateUUIDv4";
 
-    String getName() const override
-    {
-        return name;
-    }
+    String getName() const override { return name; }
 
     size_t getNumberOfArguments() const override { return 0; }
-
+    bool isDeterministic() const override { return false; }
     bool isDeterministicInScopeOfQuery() const override { return false; }
     bool useDefaultImplementationForNulls() const override { return false; }
     bool isSuitableForShortCircuitArgumentsExecution(const DataTypesWithConstInfo & /*arguments*/) const override { return false; }
     bool isVariadic() const override { return true; }
 
-    DataTypePtr getReturnTypeImpl(const DataTypes & arguments) const override
+    DataTypePtr getReturnTypeImpl(const ColumnsWithTypeAndName & arguments) const override
     {
-        if (arguments.size() > 1)
-            throw Exception(ErrorCodes::NUMBER_OF_ARGUMENTS_DOESNT_MATCH,
-                "Number of arguments for function {} doesn't match: passed {}, should be 0 or 1.",
-                getName(), arguments.size());
+        FunctionArgumentDescriptors mandatory_args;
+        FunctionArgumentDescriptors optional_args{
+            {"expr", nullptr, nullptr, "Arbitrary Expression"}
+        };
+        validateFunctionArgumentTypes(*this, arguments, mandatory_args, optional_args);
 
         return std::make_shared<DataTypeUUID>();
     }
 
-    bool isDeterministic() const override { return false; }
-
     ColumnPtr executeImpl(const ColumnsWithTypeAndName &, const DataTypePtr &, size_t input_rows_count) const override
     {
         auto col_res = ColumnVector<UUID>::create();
@@ -79,10 +71,10 @@ class FunctionGenerateUUIDv4 : public TargetSpecific::Default::FunctionGenerateU
         selector.registerImplementation<TargetArch::Default,
             TargetSpecific::Default::FunctionGenerateUUIDv4>();
 
-    #if USE_MULTITARGET_CODE
+#if USE_MULTITARGET_CODE
         selector.registerImplementation<TargetArch::AVX2,
             TargetSpecific::AVX2::FunctionGenerateUUIDv4>();
-    #endif
+#endif
     }
 
     ColumnPtr executeImpl(const ColumnsWithTypeAndName & arguments, const DataTypePtr & result_type, size_t input_rows_count) const override