Merge pull request ClickHouse#80544 from ClickHouse/ncb/rename-geotoh3_lon_lat_input_order

better name for geotoh3_lon_lat_input_order

Author: bharatnc

CHANGELOG.md

@@ -18,7 +18,7 @@
 ### <a id="255"></a> ClickHouse release 25.5, 2025-05-22
 
 #### Backward Incompatible Change
-* Function `geoToH3` now accepts the input in the order (lat, lon, res) (which is common for other geometric functions). Users who wish to retain the previous result order (lon, lat, res) can set setting `geotoh3_lon_lat_input_order = true`. [#78852](https://github.com/ClickHouse/ClickHouse/pull/78852) ([Pratima Patel](https://github.com/pratimapatel2008)).
+* Function `geoToH3` now accepts the input in the order (lat, lon, res) (which is common for other geometric functions). Users who wish to retain the previous result order (lon, lat, res) can set setting `geotoh3_argument_order = 'lon_lat'`. [#78852](https://github.com/ClickHouse/ClickHouse/pull/78852) ([Pratima Patel](https://github.com/pratimapatel2008)).
 * Add a filesystem cache setting `allow_dynamic_cache_resize`, by default `false`, to allow dynamic resize of filesystem cache. Why: in certain environments (ClickHouse Cloud) all the scaling events happen through the restart of the process and we would love this feature to be explicitly disabled to have more control over the behaviour + as a safety measure. This PR is marked as backward incompatible, because in older versions dynamic cache resize worked by default without special setting. [#79148](https://github.com/ClickHouse/ClickHouse/pull/79148) ([Kseniia Sumarokova](https://github.com/kssenii)).
 * Removed support for legacy index types `annoy` and `usearch`. Both have been stubs for a long time, i.e. every attempt to use the legacy indexes returned an error anyways. If you still have `annoy` and `usearch` indexes, please drop them. [#79802](https://github.com/ClickHouse/ClickHouse/pull/79802) ([Robert Schulze](https://github.com/rschu1ze)).
 * Remove `format_alter_commands_with_parentheses` server setting. The setting was introduced and disabled by default in 24.2. It was enabled by default in 25.2. As there are no LTS versions that don't support the new format, we can remove the setting. [#79970](https://github.com/ClickHouse/ClickHouse/pull/79970) ([János Benjamin Antal](https://github.com/antaljanosbenjamin)).

docs/en/sql-reference/functions/geo/h3.md

@@ -210,7 +210,7 @@ geoToH3(lat, lon, resolution)
 - Hexagon index number. [UInt64](../../data-types/int-uint.md).
 - 0 in case of error. [UInt64](../../data-types/int-uint.md).
 
-Note: In ClickHouse v25.4 or older, `geoToH3()` takes values in order `(lon, lat)`. As per ClickHouse v25.5, the input values are in order `(lat, lon)`. The previous behaviour can be restored using setting `geotoh3_lon_lat_input_order = true`.
+Note: In ClickHouse v25.4 or older, `geoToH3()` takes values in order `(lon, lat)`. As per ClickHouse v25.5, the input values are in order `(lat, lon)`. The previous behaviour can be restored using setting `geotoh3_argument_order = 'lon_lat'`.
 
 **Example**
 

src/Core/Settings.cpp

@@ -3651,9 +3651,9 @@ If enabled, functions 'least' and 'greatest' return NULL if one of their argumen
     DECLARE(Bool, h3togeo_lon_lat_result_order, false, R"(
 Function 'h3ToGeo' returns (lon, lat) if true, otherwise (lat, lon).
 )", 0) \
-    DECLARE(Bool, geotoh3_lon_lat_input_order, false, R"(
-Function 'geoToH3' accepts (lon, lat) if true, otherwise (lat, lon).
-)", 0) \
+    DECLARE(GeoToH3ArgumentOrder, geotoh3_argument_order, GeoToH3ArgumentOrder::LAT_LON, R"(
+Function 'geoToH3' accepts (lon, lat) if set to 'lon_lat' and (lat, lon) if set to 'lat_lon'.
+)", BETA) \
     DECLARE(UInt64, max_partitions_per_insert_block, 100, R"(
 Limits the maximum number of partitions in a single inserted block
 and an exception is thrown if the block contains too many partitions.

src/Core/Settings.h

@@ -104,7 +104,8 @@ class WriteBuffer;
     M(CLASS_NAME, UInt64) \
     M(CLASS_NAME, UInt64Auto) \
     M(CLASS_NAME, URI) \
-    M(CLASS_NAME, VectorSearchFilterStrategy)
+    M(CLASS_NAME, VectorSearchFilterStrategy) \
+    M(CLASS_NAME, GeoToH3ArgumentOrder)
 
 
 COMMON_SETTINGS_SUPPORTED_TYPES(Settings, DECLARE_SETTING_TRAIT)

src/Core/SettingsChangesHistory.cpp

@@ -75,7 +75,7 @@ const VersionToSettingsChangesMap & getSettingsChangesHistory()
         addSettingsChanges(settings_changes_history, "25.5",
         {
             /// Release closed. Please use 25.6
-            {"geotoh3_lon_lat_input_order", true, false, "A new setting for legacy behaviour to set lon and lat order"},
+            {"geotoh3_argument_order", "lon_lat", "lat_lon", "A new setting for legacy behaviour to set lon and lat argument order"},
             {"secondary_indices_enable_bulk_filtering", false, true, "A new algorithm for filtering by data skipping indices"},
             {"implicit_table_at_top_level", "", "", "A new setting, used in clickhouse-local"},
             {"use_skip_indexes_if_final_exact_mode", 0, 0, "This setting was introduced to help FINAL query return correct results with skip indexes"},

src/Core/SettingsEnums.cpp

@@ -312,4 +312,10 @@ IMPLEMENT_SETTING_ENUM(
      {"prefilter", VectorSearchFilterStrategy::PREFILTER},
      {"postfilter", VectorSearchFilterStrategy::POSTFILTER}})
 
+IMPLEMENT_SETTING_ENUM(
+    GeoToH3ArgumentOrder,
+    ErrorCodes::BAD_ARGUMENTS,
+    {{"lat_lon", GeoToH3ArgumentOrder::LAT_LON},
+     {"lon_lat", GeoToH3ArgumentOrder::LON_LAT}})
+
 }

src/Core/SettingsEnums.h

@@ -405,4 +405,12 @@ enum class VectorSearchFilterStrategy : uint8_t
 
 DECLARE_SETTING_ENUM(VectorSearchFilterStrategy)
 
+enum class GeoToH3ArgumentOrder : uint8_t
+{
+    LAT_LON,
+    LON_LAT,
+};
+
+DECLARE_SETTING_ENUM(GeoToH3ArgumentOrder)
+
 }

src/Functions/geoToH3.cpp

@@ -10,6 +10,7 @@
 #include <Functions/IFunction.h>
 #include <Interpreters/Context.h>
 #include <Core/Settings.h>
+#include <Core/SettingsEnums.h>
 #include <base/range.h>
 
 #include <constants.h>
@@ -20,7 +21,7 @@ namespace DB
 {
 namespace Setting
 {
-    extern const SettingsBool geotoh3_lon_lat_input_order;
+    extern const SettingsGeoToH3ArgumentOrder geotoh3_argument_order;
 }
 namespace ErrorCodes
 {
@@ -37,14 +38,14 @@ namespace
 /// and returns h3 index of this point
 class FunctionGeoToH3 : public IFunction
 {
-    const bool geotoh3_lon_lat_input_order;
+    GeoToH3ArgumentOrder geotoh3_argument_order;
 public:
     static constexpr auto name = "geoToH3";
 
     static FunctionPtr create(ContextPtr context) { return std::make_shared<FunctionGeoToH3>(context); }
 
     explicit FunctionGeoToH3(ContextPtr context)
-    : geotoh3_lon_lat_input_order(context->getSettingsRef()[Setting::geotoh3_lon_lat_input_order])
+    : geotoh3_argument_order(context->getSettingsRef()[Setting::geotoh3_argument_order])
     {
     }
 
@@ -94,7 +95,7 @@ class FunctionGeoToH3 : public IFunction
         const ColumnFloat64 * col_lat = nullptr;
         const ColumnFloat64 * col_lon = nullptr;
 
-        if (geotoh3_lon_lat_input_order)
+        if (geotoh3_argument_order == GeoToH3ArgumentOrder::LON_LAT)
         {
             col_lon = checkAndGetColumn<ColumnFloat64>(non_const_arguments[0].column.get());
             col_lat = checkAndGetColumn<ColumnFloat64>(non_const_arguments[1].column.get());

tests/queries/0_stateless/03404_geotoh3_input_order.sql

@@ -1,7 +1,7 @@
 -- Tags: no-fasttest
 -- no-fasttest: h3ToGeo needs binary with Uber H3 libary
 
--- Test for setting 'geotoh3_lon_lat_input_order'
+-- Test for setting 'geotoh3_argument_order'
 
-SELECT geoToH3(37.79506683, 55.71290588, 15) AS h3Index SETTINGS geotoh3_lon_lat_input_order = true;
-SELECT geoToH3(55.71290588, 37.79506683, 15) AS h3Index SETTINGS geotoh3_lon_lat_input_order = false;
+SELECT geoToH3(37.79506683, 55.71290588, 15) AS h3Index SETTINGS geotoh3_argument_order = 'lon_lat';
+SELECT geoToH3(55.71290588, 37.79506683, 15) AS h3Index SETTINGS geotoh3_argument_order = 'lat_lon';