h3 hierarchical functions and string conversion

dbms/src/Functions/h3GetBaseCell.cpp

@@ -0,0 +1,66 @@
+#include "config_functions.h"
+#if USE_H3
+#    include <Columns/ColumnsNumber.h>
+#    include <DataTypes/DataTypesNumber.h>
+#    include <Functions/FunctionFactory.h>
+#    include <Functions/IFunction.h>
+#    include <Common/typeid_cast.h>
+#    include <ext/range.h>
+
+#    include <h3api.h>
+
+
+namespace DB
+{
+class FunctionH3GetBaseCell : public IFunction
+{
+public:
+    static constexpr auto name = "h3GetBaseCell";
+
+    static FunctionPtr create(const Context &) { return std::make_shared<FunctionH3GetBaseCell>(); }
+
+    std::string getName() const override { return name; }
+
+    size_t getNumberOfArguments() const override { return 1; }
+    bool useDefaultImplementationForConstants() const override { return true; }
+
+    DataTypePtr getReturnTypeImpl(const DataTypes & arguments) const override
+    {
+        auto arg = arguments[0].get();
+        if (!WhichDataType(arg).isUInt64())
+            throw Exception(
+                "Illegal type " + arg->getName() + " of argument " + std::to_string(1) + " of function " + getName() + ". Must be UInt64",
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+
+        return std::make_shared<DataTypeUInt8>();
+    }
+
+    void executeImpl(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count) override
+    {
+        const auto col_hindex = block.getByPosition(arguments[0]).column.get();
+
+        auto dst = ColumnVector<UInt8>::create();
+        auto & dst_data = dst->getData();
+        dst_data.resize(input_rows_count);
+
+        for (const auto row : ext::range(0, input_rows_count))
+        {
+            const UInt64 hindex = col_hindex->getUInt(row);
+
+            UInt8 res = h3GetBaseCell(hindex);
+
+            dst_data[row] = res;
+        }
+
+        block.getByPosition(result).column = std::move(dst);
+    }
+};
+
+
+void registerFunctionH3GetBaseCell(FunctionFactory & factory)
+{
+    factory.registerFunction<FunctionH3GetBaseCell>();
+}
+
+}
+#endif

dbms/src/Functions/h3HexAreaM2.cpp

@@ -0,0 +1,66 @@
+#include "config_functions.h"
+#if USE_H3
+#    include <Columns/ColumnsNumber.h>
+#    include <DataTypes/DataTypesNumber.h>
+#    include <Functions/FunctionFactory.h>
+#    include <Functions/IFunction.h>
+#    include <Common/typeid_cast.h>
+#    include <ext/range.h>
+
+#    include <h3api.h>
+
+
+namespace DB
+{
+class FunctionH3HexAreaM2 : public IFunction
+{
+public:
+    static constexpr auto name = "h3HexAreaM2";
+
+    static FunctionPtr create(const Context &) { return std::make_shared<FunctionH3HexAreaM2>(); }
+
+    std::string getName() const override { return name; }
+
+    size_t getNumberOfArguments() const override { return 1; }
+    bool useDefaultImplementationForConstants() const override { return true; }
+
+    DataTypePtr getReturnTypeImpl(const DataTypes & arguments) const override
+    {
+        auto arg = arguments[0].get();
+        if (!WhichDataType(arg).isUInt8())
+            throw Exception(
+                "Illegal type " + arg->getName() + " of argument " + std::to_string(1) + " of function " + getName() + ". Must be UInt8",
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+
+        return std::make_shared<DataTypeFloat64>();
+    }
+
+    void executeImpl(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count) override
+    {
+        const auto col_hindex = block.getByPosition(arguments[0]).column.get();
+
+        auto dst = ColumnVector<Float64>::create();
+        auto & dst_data = dst->getData();
+        dst_data.resize(input_rows_count);
+
+        for (const auto row : ext::range(0, input_rows_count))
+        {
+            const int resolution = col_hindex->getUInt(row);
+
+            Float64 res = hexAreaM2(resolution);
+
+            dst_data[row] = res;
+        }
+
+        block.getByPosition(result).column = std::move(dst);
+    }
+};
+
+
+void registerFunctionH3HexAreaM2(FunctionFactory & factory)
+{
+    factory.registerFunction<FunctionH3HexAreaM2>();
+}
+
+}
+#endif

dbms/src/Functions/h3IndexesAreNeighbors.cpp

@@ -0,0 +1,74 @@
+#include "config_functions.h"
+#if USE_H3
+#    include <Columns/ColumnsNumber.h>
+#    include <DataTypes/DataTypesNumber.h>
+#    include <Functions/FunctionFactory.h>
+#    include <Functions/IFunction.h>
+#    include <Common/typeid_cast.h>
+#    include <ext/range.h>
+
+#    include <h3api.h>
+
+
+namespace DB
+{
+class FunctionH3IndexesAreNeighbors : public IFunction
+{
+public:
+    static constexpr auto name = "h3IndexesAreNeighbors";
+
+    static FunctionPtr create(const Context &) { return std::make_shared<FunctionH3IndexesAreNeighbors>(); }
+
+    std::string getName() const override { return name; }
+
+    size_t getNumberOfArguments() const override { return 2; }
+    bool useDefaultImplementationForConstants() const override { return true; }
+
+    DataTypePtr getReturnTypeImpl(const DataTypes & arguments) const override
+    {
+        auto arg = arguments[0].get();
+        if (!WhichDataType(arg).isUInt64())
+            throw Exception(
+                "Illegal type " + arg->getName() + " of argument " + std::to_string(1) + " of function " + getName() + ". Must be UInt64",
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+
+        arg = arguments[1].get();
+        if (!WhichDataType(arg).isUInt64())
+            throw Exception(
+                "Illegal type " + arg->getName() + " of argument " + std::to_string(2) + " of function " + getName() + ". Must be UInt64",
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+
+        return std::make_shared<DataTypeUInt8>();
+    }
+
+    void executeImpl(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count) override
+    {
+        const auto col_hindex_origin = block.getByPosition(arguments[0]).column.get();
+        const auto col_hindex_dest = block.getByPosition(arguments[1]).column.get();
+
+        auto dst = ColumnVector<UInt8>::create();
+        auto & dst_data = dst->getData();
+        dst_data.resize(input_rows_count);
+
+        for (const auto row : ext::range(0, input_rows_count))
+        {
+            const UInt64 hindex_origin = col_hindex_origin->getUInt(row);
+            const UInt64 hindex_dest = col_hindex_dest->getUInt(row);
+
+            UInt8 res = h3IndexesAreNeighbors(hindex_origin, hindex_dest);
+
+            dst_data[row] = res;
+        }
+
+        block.getByPosition(result).column = std::move(dst);
+    }
+};
+
+
+void registerFunctionH3IndexesAreNeighbors(FunctionFactory & factory)
+{
+    factory.registerFunction<FunctionH3IndexesAreNeighbors>();
+}
+
+}
+#endif

dbms/src/Functions/h3ToChildren.cpp

@@ -0,0 +1,91 @@
+#include "config_functions.h"
+#if USE_H3
+#    include <Columns/ColumnArray.h>
+#    include <Columns/ColumnsNumber.h>
+#    include <DataTypes/DataTypeArray.h>
+#    include <DataTypes/DataTypesNumber.h>
+#    include <Functions/FunctionFactory.h>
+#    include <Functions/IFunction.h>
+#    include <Common/typeid_cast.h>
+#    include <ext/range.h>
+
+#    include <h3api.h>
+
+
+namespace DB
+{
+class FunctionH3ToChildren : public IFunction
+{
+public:
+    static constexpr auto name = "h3ToChildren";
+
+    static FunctionPtr create(const Context &) { return std::make_shared<FunctionH3ToChildren>(); }
+
+    std::string getName() const override { return name; }
+
+    size_t getNumberOfArguments() const override { return 2; }
+    bool useDefaultImplementationForConstants() const override { return true; }
+
+    DataTypePtr getReturnTypeImpl(const DataTypes & arguments) const override
+    {
+        auto arg = arguments[0].get();
+        if (!WhichDataType(arg).isUInt64())
+            throw Exception(
+                "Illegal type " + arg->getName() + " of argument " + std::to_string(1) + " of function " + getName() + ". Must be UInt64",
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+
+        arg = arguments[1].get();
+        if (!WhichDataType(arg).isUInt8())
+            throw Exception(
+                "Illegal type " + arg->getName() + " of argument " + std::to_string(2) + " of function " + getName() + ". Must be UInt8",
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+
+        return std::make_shared<DataTypeArray>(std::make_shared<DataTypeUInt64>());
+    }
+
+    void executeImpl(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count) override
+    {
+        const auto col_hindex = block.getByPosition(arguments[0]).column.get();
+        const auto col_resolution = block.getByPosition(arguments[1]).column.get();
+
+        auto dst = ColumnArray::create(ColumnUInt64::create());
+        auto & dst_data = dst->getData();
+        auto & dst_offsets = dst->getOffsets();
+        dst_offsets.resize(input_rows_count);
+        auto current_offset = 0;
+
+        std::vector<H3Index> hindex_vec;
+
+        for (const auto row : ext::range(0, input_rows_count))
+        {
+            const UInt64 parent_hindex = col_hindex->getUInt(row);
+            const UInt8 child_resolution = col_resolution->getUInt(row);
+
+            const auto vec_size = maxH3ToChildrenSize(parent_hindex, child_resolution);
+            hindex_vec.resize(vec_size);
+            h3ToChildren(parent_hindex, child_resolution, hindex_vec.data());
+
+            dst_data.reserve(dst_data.size() + vec_size);
+            for (auto hindex : hindex_vec)
+            {
+                if (hindex != 0)
+                {
+                    ++current_offset;
+                    dst_data.insert(hindex);
+                }
+            }
+            dst_offsets[row] = current_offset;
+        }
+
+        block.getByPosition(result).column = std::move(dst);
+    }
+};
+
+
+void registerFunctionH3ToChildren(FunctionFactory & factory)
+{
+    factory.registerFunction<FunctionH3ToChildren>();
+}
+
+}
+#endif

dbms/src/Functions/h3ToParent.cpp

@@ -0,0 +1,74 @@
+#include "config_functions.h"
+#if USE_H3
+#    include <Columns/ColumnsNumber.h>
+#    include <DataTypes/DataTypesNumber.h>
+#    include <Functions/FunctionFactory.h>
+#    include <Functions/IFunction.h>
+#    include <Common/typeid_cast.h>
+#    include <ext/range.h>
+
+#    include <h3api.h>
+
+
+namespace DB
+{
+class FunctionH3ToParent : public IFunction
+{
+public:
+    static constexpr auto name = "h3ToParent";
+
+    static FunctionPtr create(const Context &) { return std::make_shared<FunctionH3ToParent>(); }
+
+    std::string getName() const override { return name; }
+
+    size_t getNumberOfArguments() const override { return 2; }
+    bool useDefaultImplementationForConstants() const override { return true; }
+
+    DataTypePtr getReturnTypeImpl(const DataTypes & arguments) const override
+    {
+        auto arg = arguments[0].get();
+        if (!WhichDataType(arg).isUInt64())
+            throw Exception(
+                "Illegal type " + arg->getName() + " of argument " + std::to_string(1) + " of function " + getName() + ". Must be UInt64",
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+
+        arg = arguments[1].get();
+        if (!WhichDataType(arg).isUInt8())
+            throw Exception(
+                "Illegal type " + arg->getName() + " of argument " + std::to_string(2) + " of function " + getName() + ". Must be UInt8",
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+
+        return std::make_shared<DataTypeUInt64>();
+    }
+
+    void executeImpl(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count) override
+    {
+        const auto col_hindex = block.getByPosition(arguments[0]).column.get();
+        const auto col_resolution = block.getByPosition(arguments[1]).column.get();
+
+        auto dst = ColumnVector<UInt64>::create();
+        auto & dst_data = dst->getData();
+        dst_data.resize(input_rows_count);
+
+        for (const auto row : ext::range(0, input_rows_count))
+        {
+            const UInt64 hindex = col_hindex->getUInt(row);
+            const UInt8 resolution = col_resolution->getUInt(row);
+
+            UInt64 res = h3ToParent(hindex, resolution);
+
+            dst_data[row] = res;
+        }
+
+        block.getByPosition(result).column = std::move(dst);
+    }
+};
+
+
+void registerFunctionH3ToParent(FunctionFactory & factory)
+{
+    factory.registerFunction<FunctionH3ToParent>();
+}
+
+}
+#endif

dbms/src/Functions/h3ToString.cpp

@@ -0,0 +1,82 @@
+#include "config_functions.h"
+#if USE_H3
+#    include <Columns/ColumnString.h>
+#    include <DataTypes/DataTypeString.h>
+#    include <Functions/FunctionFactory.h>
+#    include <Functions/IFunction.h>
+#    include <Common/typeid_cast.h>
+
+#    include <h3api.h>
+
+#    define H3_INDEX_STRING_LENGTH 17 // includes \0 terminator
+
+namespace DB
+{
+class FunctionH3ToString : public IFunction
+{
+public:
+    static constexpr auto name = "h3ToString";
+
+    static FunctionPtr create(const Context &) { return std::make_shared<FunctionH3ToString>(); }
+
+    std::string getName() const override { return name; }
+
+    size_t getNumberOfArguments() const override { return 1; }
+
+    bool useDefaultImplementationForConstants() const override { return true; }
+
+    DataTypePtr getReturnTypeImpl(const DataTypes & arguments) const override
+    {
+        auto arg = arguments[0].get();
+        if (!WhichDataType(arg).isUInt64())
+            throw Exception(
+                "Illegal type " + arg->getName() + " of argument " + std::to_string(1) + " of function " + getName() + ". Must be UInt64",
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+
+        return std::make_shared<DataTypeString>();
+    }
+
+    void executeImpl(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count) override
+    {
+        const auto col_hindex = block.getByPosition(arguments[0]).column.get();
+
+        auto col_res = ColumnString::create();
+        auto & vec_res = col_res->getChars();
+        auto & vec_offsets = col_res->getOffsets();
+
+        vec_offsets.resize(input_rows_count);
+        vec_res.resize_fill(input_rows_count * H3_INDEX_STRING_LENGTH, '\0');
+
+        char * begin = reinterpret_cast<char *>(vec_res.data());
+        char * pos = begin;
+
+        for (size_t i = 0; i < input_rows_count; ++i)
+        {
+            const UInt64 hindex = col_hindex->getUInt(i);
+
+            if (!h3IsValid(hindex))
+            {
+                throw Exception("Invalid H3 index: " + std::to_string(hindex), ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+            }
+            h3ToString(hindex, pos, H3_INDEX_STRING_LENGTH);
+
+            // move to end of the index
+            while (*pos != '\0')
+            {
+                pos++;
+            }
+            vec_offsets[i] = ++pos - begin;
+        }
+        vec_res.resize(pos - begin);
+        block.getByPosition(result).column = std::move(col_res);
+    }
+};
+
+
+void registerFunctionH3ToString(FunctionFactory & factory)
+{
+    factory.registerFunction<FunctionH3ToString>();
+}
+
+}
+#endif

dbms/src/Functions/registerFunctionsGeo.cpp

@@ -19,6 +19,13 @@ void registerFunctionH3EdgeLengthM(FunctionFactory &);
 void registerFunctionH3GetResolution(FunctionFactory &);
 void registerFunctionH3IsValid(FunctionFactory &);
 void registerFunctionH3KRing(FunctionFactory &);
+void registerFunctionH3GetBaseCell(FunctionFactory &);
+void registerFunctionH3ToParent(FunctionFactory &);
+void registerFunctionH3ToChildren(FunctionFactory &);
+void registerFunctionH3IndexesAreNeighbors(FunctionFactory &);
+void registerFunctionStringToH3(FunctionFactory &);
+void registerFunctionH3ToString(FunctionFactory &);
+void registerFunctionH3HexAreaM2(FunctionFactory &);
 #endif
 
 
@@ -38,6 +45,13 @@ void registerFunctionsGeo(FunctionFactory & factory)
     registerFunctionH3GetResolution(factory);
     registerFunctionH3IsValid(factory);
     registerFunctionH3KRing(factory);
+    registerFunctionH3GetBaseCell(factory);
+    registerFunctionH3ToParent(factory);
+    registerFunctionH3ToChildren(factory);
+    registerFunctionH3IndexesAreNeighbors(factory);
+    registerFunctionStringToH3(factory);
+    registerFunctionH3ToString(factory);
+    registerFunctionH3HexAreaM2(factory);
 #endif
 }
 

dbms/src/Functions/stringToH3.cpp

@@ -0,0 +1,97 @@
+#include "config_functions.h"
+#if USE_H3
+#    include <Functions/GatherUtils/GatherUtils.h>
+#    include <Functions/GatherUtils/Sources.h>
+#    include <DataTypes/DataTypeString.h>
+#    include <DataTypes/DataTypesNumber.h>
+#    include <Columns/ColumnString.h>
+#    include <Functions/FunctionFactory.h>
+#    include <Functions/IFunction.h>
+#    include <Common/typeid_cast.h>
+
+#    include <h3api.h>
+
+
+namespace DB
+{
+
+using namespace GatherUtils;
+
+class FunctionStringToH3 : public IFunction
+{
+public:
+    static constexpr auto name = "stringToH3";
+
+    static FunctionPtr create(const Context &) { return std::make_shared<FunctionStringToH3>(); }
+
+    std::string getName() const override { return name; }
+
+    size_t getNumberOfArguments() const override { return 1; }
+    bool useDefaultImplementationForConstants() const override { return true; }
+
+    DataTypePtr getReturnTypeImpl(const DataTypes & arguments) const override
+    {
+        auto arg = arguments[0].get();
+        if (!WhichDataType(arg).isStringOrFixedString())
+            throw Exception(
+                "Illegal type " + arg->getName() + " of argument " + std::to_string(1) + " of function " + getName() + ". Must be String or FixedString",
+                ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+
+        return std::make_shared<DataTypeUInt64>();
+    }
+
+    void executeImpl(Block & block, const ColumnNumbers & arguments, size_t result, size_t input_rows_count) override
+    {
+        const auto col_hindex = block.getByPosition(arguments[0]).column.get();
+
+        auto dst = ColumnVector<UInt64>::create();
+        auto & dst_data = dst->getData();
+        dst_data.resize(input_rows_count);
+
+        if (auto * h3index = checkAndGetColumn<ColumnString>(col_hindex))
+            execute<StringSource>(StringSource(*h3index), dst_data);
+        else if (auto * h3index_fixed = checkAndGetColumn<ColumnFixedString>(col_hindex))
+            execute<FixedStringSource>(FixedStringSource(*h3index_fixed), dst_data);
+        else if (const ColumnConst * h3index_const = checkAndGetColumnConst<ColumnString>(col_hindex))
+            execute<ConstSource<StringSource>>(ConstSource<StringSource>(*h3index_const), dst_data);
+        else if (const ColumnConst * h3index_const_fixed = checkAndGetColumnConst<ColumnFixedString>(col_hindex))
+            execute<ConstSource<FixedStringSource>>(ConstSource<FixedStringSource>(*h3index_const_fixed), dst_data);
+        else
+            throw Exception("Illegal column as argument of function " + getName(), ErrorCodes::ILLEGAL_COLUMN);
+
+        block.getByPosition(result).column = std::move(dst);
+    }
+
+private:
+    template <typename H3IndexSource>
+    static void execute(H3IndexSource h3index_source, PaddedPODArray<UInt64> & res_data)
+    {
+        size_t row_num = 0;
+
+        while (!h3index_source.isEnd())
+        {
+            auto h3index = h3index_source.getWhole();
+
+            // covert to std::string and get the c_str to have the delimiting \0 at the end.
+            auto h3index_str = StringRef(h3index.data, h3index.size).toString();
+            res_data[row_num] = stringToH3(h3index_str.c_str());
+
+            if (res_data[row_num] == 0)
+            {
+                throw Exception("Invalid H3 index: " + h3index_str, ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT);
+            }
+
+            h3index_source.next();
+            ++row_num;
+        }
+    }
+};
+
+
+void registerFunctionStringToH3(FunctionFactory & factory)
+{
+    factory.registerFunction<FunctionStringToH3>();
+}
+
+}
+#endif

dbms/tests/queries/0_stateless/01070_h3_get_base_cell.reference

@@ -0,0 +1 @@
+12

dbms/tests/queries/0_stateless/01070_h3_get_base_cell.sql

@@ -0,0 +1 @@
+SELECT h3GetBaseCell(612916788725809151);

dbms/tests/queries/0_stateless/01070_h3_hex_area_m2.reference

@@ -0,0 +1,2 @@
+252903364.5
+43.9

dbms/tests/queries/0_stateless/01070_h3_hex_area_m2.sql

@@ -0,0 +1,2 @@
+SELECT h3HexAreaM2(5);
+SELECT h3HexAreaM2(13);

dbms/tests/queries/0_stateless/01070_h3_indexes_are_neighbors.reference

@@ -0,0 +1,3 @@
+0
+1
+0

dbms/tests/queries/0_stateless/01070_h3_indexes_are_neighbors.sql

@@ -0,0 +1,3 @@
+SELECT h3IndexesAreNeighbors(617420388352917503, 617420388352655359);
+SELECT h3IndexesAreNeighbors(617420388351344639, 617420388352655359);
+SELECT h3IndexesAreNeighbors(617420388351344639, 617420388351344639);

dbms/tests/queries/0_stateless/01070_h3_to_children.sql

@@ -0,0 +1,5 @@
+SELECT arraySort(h3ToChildren(599405990164561919, 3));
+
+SELECT arraySort(h3ToChildren(599405990164561919, 6));
+
+SELECT arraySort(h3ToChildren(599405990164561919, 8));

dbms/tests/queries/0_stateless/01070_h3_to_parent.reference

@@ -0,0 +1,2 @@
+590398848891879423
+576918149140578303

dbms/tests/queries/0_stateless/01070_h3_to_parent.sql

@@ -0,0 +1,2 @@
+SELECT h3ToParent(599405990164561919, 3);
+SELECT h3ToParent(599405990164561919, 0);

dbms/tests/queries/0_stateless/01070_h3_to_string.reference

@@ -0,0 +1 @@
+89184926cdbffff

dbms/tests/queries/0_stateless/01070_h3_to_string.sql

@@ -0,0 +1 @@
+SELECT h3ToString(617420388352917503);

dbms/tests/queries/0_stateless/01070_string_to_h3.reference

@@ -0,0 +1 @@
+617420388351344639

dbms/tests/queries/0_stateless/01070_string_to_h3.sql

@@ -0,0 +1 @@
+SELECT stringToH3('89184926cc3ffff');