Merge pull request ClickHouse#79839 from rschu1ze/introduced_in

`storage.functions`: Add field `introduced_in`

Author: rschu1ze

docs/en/operations/system-tables/functions.md

@@ -20,6 +20,7 @@ Columns:
 - `arguments`, ([String](../../sql-reference/data-types/string.md)) - What arguments does the function take.
 - `returned_value`, ([String](../../sql-reference/data-types/string.md)) - What does the function return.
 - `examples`, ([String](../../sql-reference/data-types/string.md)) - Example usage of the function.
+- `introduced_in`, ([String](../../sql-reference/data-types/string.md)) - ClickHouse version in which the function was first introduced.
 - `categories`, ([String](../../sql-reference/data-types/string.md)) - The category of the function.
 
 **Example**

src/Common/FunctionDocumentation.cpp

@@ -12,6 +12,8 @@ namespace ErrorCodes
     extern const int LOGICAL_ERROR;
 }
 
+VersionNumber VERSION_UNKNOWN = {0};
+
 std::string FunctionDocumentation::argumentsAsString() const
 {
     std::string res;
@@ -37,6 +39,14 @@ std::string FunctionDocumentation::examplesAsString() const
     return res;
 }
 
+std::string FunctionDocumentation::introducedInAsString() const
+{
+    if (introduced_in == FunctionDocumentation::VERSION_UNKNOWN)
+        return ""; /// we could show "unknown" here but for consistency with other fields return the empty string
+    else
+        return introduced_in.toString();
+}
+
 std::string FunctionDocumentation::categoryAsString() const
 {
     static const std::unordered_map<Category, std::string> category_to_string = {

src/Common/FunctionDocumentation.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <set>
+#include <Common/VersionNumber.h>
 #include <string>
 #include <vector>
 
@@ -63,6 +63,9 @@ struct FunctionDocumentation
     };
     using Examples = std::vector<Example>;
 
+    using IntroducedIn = VersionNumber;
+    static constexpr VersionNumber VERSION_UNKNOWN;
+
     enum class Category : uint8_t
     {
         /// Default category
@@ -118,15 +121,17 @@ struct FunctionDocumentation
     using Related = std::vector<std::string>;
 
     /// TODO Fields with {} initialization are optional. We should make all fields non-optional.
-    Description description;                /// E.g. "Returns the position (in bytes, starting at 1) of a substring needle in a string haystack."
-    Syntax syntax {};                       /// E.g. "position(haystack, needle)"
-    Arguments arguments {};                 /// E.g. ["haystack — String in which the search is performed. String.", "needle — Substring to be searched. String."]
-    ReturnedValue returned_value {};        /// E.g. "Starting position in bytes and counting from 1, if the substring was found."
-    Examples examples {};                   ///
-    Category category;                      /// E.g. Category::DatesAndTimes
+    Description description;                      /// E.g. "Returns the position (in bytes, starting at 1) of a substring needle in a string haystack."
+    Syntax syntax {};                             /// E.g. "position(haystack, needle)"
+    Arguments arguments {};                       /// E.g. ["haystack — String in which the search is performed. String.", "needle — Substring to be searched. String."]
+    ReturnedValue returned_value {};              /// E.g. "Starting position in bytes and counting from 1, if the substring was found."
+    Examples examples {};                         ///
+    IntroducedIn introduced_in {VERSION_UNKNOWN}; /// E.g. {25, 5}
+    Category category;                            /// E.g. Category::DatesAndTimes
 
     std::string argumentsAsString() const;
     std::string examplesAsString() const;
+    std::string introducedInAsString() const;
     std::string categoryAsString() const;
 };
 

src/Common/VersionNumber.cpp

@@ -32,6 +32,7 @@ std::string VersionNumber::toString() const
 int VersionNumber::compare(const VersionNumber & rhs) const
 {
     size_t min = std::min(components.size(), rhs.components.size());
+
     for (size_t i = 0; i < min; ++i)
     {
         if (auto d = components[i] - rhs.components[i])
@@ -42,6 +43,7 @@ int VersionNumber::compare(const VersionNumber & rhs) const
     {
         return components[min] >= 0 ? 1 : -1;
     }
+
     if (rhs.components.size() > min)
     {
         return -rhs.components[min] > 0 ? 1 : -1;

src/Common/VersionNumber.h

@@ -13,7 +13,7 @@ struct VersionNumber
 {
     explicit VersionNumber() = default;
 
-    VersionNumber(const std::initializer_list<Int64> & init) : components(init) {}
+    constexpr VersionNumber(const std::initializer_list<Int64> & init) : components(init) {}
     explicit VersionNumber(Int64 major, Int64 minor = 0, Int64 patch = 0) : components{major, minor, patch} { }
 
     /// Parse version number from string.

src/Functions/abs.cpp

@@ -56,8 +56,9 @@ REGISTER_FUNCTION(Abs)
     FunctionDocumentation::Arguments argument = {{"x", "Value to get the absolute value of"}};
     FunctionDocumentation::ReturnedValue returned_value = "The absolute value of `x`";
     FunctionDocumentation::Examples examples = {{"", "SELECT abs(-0.5)", "0.5"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {1, 1};
     FunctionDocumentation::Category categories = FunctionDocumentation::Category::Arithmetic;
-    FunctionDocumentation documentation = {description, syntax, argument, returned_value, examples, categories};
+    FunctionDocumentation documentation = {description, syntax, argument, returned_value, examples, introduced_in, categories};
 
     factory.registerFunction<FunctionAbs>(documentation, FunctionFactory::Case::Insensitive);
 }

src/Functions/array/arrayNormalizedGini.cpp

@@ -406,10 +406,11 @@ REGISTER_FUNCTION(NormalizedGini)
         = {{"Example",
             "SELECT arrayNormalizedGini([0.9, 0.3, 0.8, 0.7],[6, 1, 0, 2]);",
             "(0.18055555555555558,0.2638888888888889,0.6842105263157896)"}};
+    FunctionDocumentation::IntroducedIn doc_introduced_in = {25, 1};
     FunctionDocumentation::Category doc_category = FunctionDocumentation::Category::Array;
 
     factory.registerFunction<FunctionArrayNormalizedGini>(
-        {doc_description, doc_syntax, doc_arguments, doc_returned_value, doc_examples, doc_category}, FunctionFactory::Case::Sensitive);
+        {doc_description, doc_syntax, doc_arguments, doc_returned_value, doc_examples, doc_introduced_in, doc_category}, FunctionFactory::Case::Sensitive);
 }
 
 }

src/Functions/base64Decode.cpp

@@ -13,9 +13,10 @@ REGISTER_FUNCTION(Base64Decode)
     FunctionDocumentation::Arguments arguments = {{"encoded", "String column or constant. If the string is not a valid Base64-encoded value, an exception is thrown."}};
     FunctionDocumentation::ReturnedValue returned_value = "A string containing the decoded value of the argument.";
     FunctionDocumentation::Examples examples = {{"Example", "SELECT base64Decode('Y2xpY2tob3VzZQ==')", "clickhouse"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {18, 16};
     FunctionDocumentation::Category category = FunctionDocumentation::Category::Encoding;
 
-    factory.registerFunction<FunctionBase64Conversion<Base64Decode<Base64Variant::Normal>>>({description, syntax, arguments, returned_value, examples, category});
+    factory.registerFunction<FunctionBase64Conversion<Base64Decode<Base64Variant::Normal>>>({description, syntax, arguments, returned_value, examples, introduced_in, category});
 
     /// MySQL compatibility alias.
     factory.registerAlias("FROM_BASE64", "base64Decode", FunctionFactory::Case::Insensitive);

src/Functions/base64Encode.cpp

@@ -13,9 +13,10 @@ REGISTER_FUNCTION(Base64Encode)
     FunctionDocumentation::Arguments arguments = {{"plaintext", "String column or constant."}};
     FunctionDocumentation::ReturnedValue returned_value = "A string containing the encoded value of the argument.";
     FunctionDocumentation::Examples examples = {{"Example", "SELECT base64Encode('clickhouse')", "Y2xpY2tob3VzZQ=="}};
+    FunctionDocumentation::IntroducedIn introduced_in = {18, 16};
     FunctionDocumentation::Category category = FunctionDocumentation::Category::String;
 
-    factory.registerFunction<FunctionBase64Conversion<Base64Encode<Base64Variant::Normal>>>({description, syntax, arguments, returned_value, examples, category});
+    factory.registerFunction<FunctionBase64Conversion<Base64Encode<Base64Variant::Normal>>>({description, syntax, arguments, returned_value, examples, introduced_in, category});
 
     /// MySQL compatibility alias.
     factory.registerAlias("TO_BASE64", "base64Encode", FunctionFactory::Case::Insensitive);

src/Functions/base64URLDecode.cpp

@@ -13,9 +13,10 @@ REGISTER_FUNCTION(Base64URLDecode)
     FunctionDocumentation::Arguments arguments = {{"encodedURL", "String column or constant. If the string is not a valid Base64-encoded value, an exception is thrown."}};
     FunctionDocumentation::ReturnedValue returned_value = "A string containing the decoded value of the argument.";
     FunctionDocumentation::Examples examples = {{"Example", "SELECT base64URLDecode('aHR0cDovL2NsaWNraG91c2UuY29t')", "https://clickhouse.com"}};
+    FunctionDocumentation::IntroducedIn introduced_in = {24, 6};
     FunctionDocumentation::Category category = FunctionDocumentation::Category::Encoding;
 
-    factory.registerFunction<FunctionBase64Conversion<Base64Decode<Base64Variant::URL>>>({description, syntax, arguments, returned_value, examples, category});
+    factory.registerFunction<FunctionBase64Conversion<Base64Decode<Base64Variant::URL>>>({description, syntax, arguments, returned_value, examples, introduced_in, category});
 }
 
 }