You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sedona.apache.org by ji...@apache.org on 2026/10/18 05:36:46 UTC
(sedona) branch master updated: [GH-3020] Add ST_H3Uncompact (#3474)
This is an automated email from the ASF dual-hosted git repository.
jiayuasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sedona.git
The following commit(s) were added to refs/heads/master by this push:
new c9d9c6bcdb1 [GH-3020] Add ST_H3Uncompact (#3474)
c9d9c6bcdb1 is described below
commit c9d9c6bcdb1c8da8d7c7a6f72d888ad2930d71fd
Author: Simen Omholt-Jensen <41...@users.noreply.github.com>
AuthorDate: Sun Oct 18 07:36:40 2026 +0200
[GH-3020] Add ST_H3Uncompact (#3474)
---
.../java/org/apache/sedona/common/Functions.java | 13 +++++
.../org/apache/sedona/common/FunctionsTest.java | 66 ++++++++++++++++++++++
docs/api/flink/Geometry-Functions.md | 1 +
docs/api/flink/Spatial-Indexing/ST_H3Uncompact.md | 58 +++++++++++++++++++
docs/api/sql/Geometry-Functions.md | 1 +
docs/api/sql/Spatial-Indexing/ST_H3Uncompact.md | 58 +++++++++++++++++++
.../main/java/org/apache/sedona/flink/Catalog.java | 1 +
.../apache/sedona/flink/expressions/Functions.java | 12 ++++
.../java/org/apache/sedona/flink/FunctionTest.java | 63 +++++++++++++++++++++
python/sedona/spark/sql/st_functions.py | 14 +++++
python/tests/sql/test_dataframe_api.py | 13 +++++
python/tests/sql/test_function.py | 33 +++++++++++
.../scala/org/apache/sedona/sql/UDF/Catalog.scala | 1 +
.../sql/sedona_sql/expressions/Functions.scala | 8 +++
.../expressions/InferredExpression.scala | 5 +-
.../sql/sedona_sql/expressions/st_functions.scala | 9 +++
.../apache/sedona/sql/dataFrameAPITestScala.scala | 16 ++++++
.../sedona/sql/functions/STH3Functions.scala | 59 +++++++++++++++++++
18 files changed, 430 insertions(+), 1 deletion(-)
diff --git a/common/src/main/java/org/apache/sedona/common/Functions.java b/common/src/main/java/org/apache/sedona/common/Functions.java
index b67a56ee82a..62b9fffdfe6 100644
--- a/common/src/main/java/org/apache/sedona/common/Functions.java
+++ b/common/src/main/java/org/apache/sedona/common/Functions.java
@@ -2088,6 +2088,19 @@ public class Functions {
return H3Utils.h3.cellToChildren(cell, resolution).toArray(new Long[0]);
}
+ /**
+ * Expands a collection of H3 cells to the requested resolution.
+ *
+ * @param cells the H3 cells, which may have different resolutions
+ * @param resolution the target resolution, at least that of every input cell and at most 15
+ * @return the H3 cells at the target resolution
+ */
+ public static Long[] h3Uncompact(long[] cells, int resolution) {
+ return H3Utils.h3
+ .uncompactCells(Arrays.stream(cells).boxed().collect(Collectors.toList()), resolution)
+ .toArray(new Long[0]);
+ }
+
/**
* gets the polygon for each h3 index provided
*
diff --git a/common/src/test/java/org/apache/sedona/common/FunctionsTest.java b/common/src/test/java/org/apache/sedona/common/FunctionsTest.java
index aebd72051c7..41205d1f841 100644
--- a/common/src/test/java/org/apache/sedona/common/FunctionsTest.java
+++ b/common/src/test/java/org/apache/sedona/common/FunctionsTest.java
@@ -1650,6 +1650,72 @@ public class FunctionsTest extends TestBase {
assertThrows(H3Exception.class, () -> Functions.h3ToChildren(cell, 4));
}
+ @Test
+ public void h3UncompactMixedResolutions() {
+ long parent = H3Utils.coordinateToCell(new Coordinate(1, 2), 5);
+ long other = H3Utils.coordinateToCell(new Coordinate(10, 20), 6);
+ for (int resolution : new int[] {6, 7}) {
+ Long[] cells = Functions.h3Uncompact(new long[] {parent, other}, resolution);
+ Set<Long> expected = new HashSet<>(H3Utils.h3.cellToChildren(parent, resolution));
+ expected.addAll(H3Utils.h3.cellToChildren(other, resolution));
+ assertEquals(resolution == 6 ? 8 : 56, cells.length);
+ assertEquals(expected, new HashSet<>(Arrays.asList(cells)));
+ for (long cell : cells) {
+ assertEquals(resolution, H3Utils.h3.getResolution(cell));
+ }
+ }
+ }
+
+ @Test
+ public void h3UncompactEqualResolutionAndEmpty() {
+ for (int resolution : new int[] {0, 5, 15}) {
+ long cell = H3Utils.coordinateToCell(new Coordinate(1, 2), resolution);
+ assertArrayEquals(new Long[] {cell}, Functions.h3Uncompact(new long[] {cell}, resolution));
+ assertArrayEquals(new Long[0], Functions.h3Uncompact(new long[0], resolution));
+ }
+ }
+
+ @Test
+ public void h3UncompactPentagon() {
+ long pentagon = H3Utils.h3.getPentagons(5).iterator().next();
+ for (int resolution : new int[] {6, 7}) {
+ Long[] cells = Functions.h3Uncompact(new long[] {pentagon}, resolution);
+ assertEquals(resolution == 6 ? 6 : 41, cells.length);
+ assertEquals(cells.length, new HashSet<>(Arrays.asList(cells)).size());
+ for (long cell : cells) {
+ assertEquals(resolution, H3Utils.h3.getResolution(cell));
+ assertEquals(pentagon, H3Utils.h3.cellToParent(cell, 5));
+ }
+ }
+ }
+
+ @Test
+ public void h3UncompactRoundTrip() {
+ long cell = H3Utils.coordinateToCell(new Coordinate(1, 2), 6);
+ List<Long> original = H3Utils.h3.gridDisk(cell, 2);
+ long[] compacted =
+ H3Utils.h3.compactCells(original).stream().mapToLong(Long::longValue).toArray();
+ assertTrue(compacted.length < original.size());
+ Long[] uncompacted = Functions.h3Uncompact(compacted, 6);
+ assertEquals(original.size(), uncompacted.length);
+ assertEquals(new HashSet<>(original), new HashSet<>(Arrays.asList(uncompacted)));
+ }
+
+ @Test
+ public void h3UncompactInvalidResolution() {
+ long parent = H3Utils.coordinateToCell(new Coordinate(1, 2), 5);
+ long child = H3Utils.h3.cellToCenterChild(parent, 6);
+ for (int resolution : new int[] {-1, 16}) {
+ assertThrows(
+ IllegalArgumentException.class,
+ () -> Functions.h3Uncompact(new long[] {parent}, resolution));
+ assertThrows(
+ IllegalArgumentException.class, () -> Functions.h3Uncompact(new long[0], resolution));
+ }
+ assertThrows(H3Exception.class, () -> Functions.h3Uncompact(new long[] {parent}, 4));
+ assertThrows(H3Exception.class, () -> Functions.h3Uncompact(new long[] {parent, child}, 5));
+ }
+
@Test
public void geometricMedian() throws Exception {
MultiPoint multiPoint =
diff --git a/docs/api/flink/Geometry-Functions.md b/docs/api/flink/Geometry-Functions.md
index c88821a65d5..2f4ae587ef0 100644
--- a/docs/api/flink/Geometry-Functions.md
+++ b/docs/api/flink/Geometry-Functions.md
@@ -353,6 +353,7 @@ These functions work with spatial indexing systems including Bing Tiles, H3, Hil
| [ST_H3ToChildren](Spatial-Indexing/ST_H3ToChildren.md) | `Array<Long>` | Returns the children of an H3 cell at the requested resolution. | v2.0.0 |
| [ST_H3ToGeom](Spatial-Indexing/ST_H3ToGeom.md) | `Array<Geometry>` | Return the result of H3 function [cellsToMultiPolygon(cells)](https://h3geo.org/docs/api/regions#cellstolinkedmultipolygon--cellstomultipolygon). | v1.6.0 |
| [ST_H3ToParent](Spatial-Indexing/ST_H3ToParent.md) | Long | Returns the parent of an H3 cell at the requested resolution. | v2.0.0 |
+| [ST_H3Uncompact](Spatial-Indexing/ST_H3Uncompact.md) | `Array<Long>` | Expands H3 cells to the requested resolution. | v2.0.0 |
| [ST_HilbertDistance](Spatial-Indexing/ST_HilbertDistance.md) | Long | Maps the midpoint of a geometry's envelope to an unsigned Hilbert-curve address within a supplied extent. | v2.0.0 |
| [ST_S2CellIDs](Spatial-Indexing/ST_S2CellIDs.md) | `Array<Long>` | Cover the geometry with Google S2 Cells, return the corresponding cell IDs with the given level. The level indicates the [size of cells](https://s2geometry.io/resources/s2cell_statistics.html). With... | v1.4.0 |
| [ST_S2ToGeom](Spatial-Indexing/ST_S2ToGeom.md) | `Array<Geometry>` | Returns an array of Polygons for the corresponding S2 cell IDs. | v1.6.0 |
diff --git a/docs/api/flink/Spatial-Indexing/ST_H3Uncompact.md b/docs/api/flink/Spatial-Indexing/ST_H3Uncompact.md
new file mode 100644
index 00000000000..0ad1c6e1aa4
--- /dev/null
+++ b/docs/api/flink/Spatial-Indexing/ST_H3Uncompact.md
@@ -0,0 +1,58 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+
+# ST_H3Uncompact
+
+Introduction: Expands an array of H3 cell IDs to the requested resolution using H3's [uncompactCells(cells, resolution)](https://h3geo.org/docs/api/hierarchy#uncompactcells).
+
+The input cells may have different resolutions and do not need to come from a compaction operation. Each coarser cell is replaced by its descendants at the target resolution. Cells already at the target resolution are retained.
+
+The requested resolution must be between 0 and 15, inclusive, and at least as fine as every input cell's resolution. A lower resolution or a resolution outside this range raises an error. An empty input array returns an empty array. A null array or resolution returns null.
+
+Input cells should be unique and non-overlapping; duplicate or overlapping cells may produce duplicates in the output. The order of the returned cells is not guaranteed. The result can grow rapidly when expanding to a much finer resolution.
+
+Format: `ST_H3Uncompact(cells: Array<Long>, resolution: Int)`
+
+Return type: `Array<Long>`
+
+Since: `v2.0.0`
+
+SQL Example
+
+```sql
+SELECT ST_H3Uncompact(ARRAY[601041811137363967], 5)
+```
+
+Output:
+
+```text
+[601041811137363967]
+```
+
+To expand this resolution 5 hexagon to its seven immediate children:
+
+```sql
+SELECT CARDINALITY(ST_H3Uncompact(ARRAY[601041811137363967], 6)) AS cell_count
+```
+
+Output:
+
+```text
+7
+```
diff --git a/docs/api/sql/Geometry-Functions.md b/docs/api/sql/Geometry-Functions.md
index ccbf2c9affd..b4cb3760111 100644
--- a/docs/api/sql/Geometry-Functions.md
+++ b/docs/api/sql/Geometry-Functions.md
@@ -361,6 +361,7 @@ These functions work with spatial indexing systems including Bing Tiles, H3, Hil
| [ST_H3ToChildren](Spatial-Indexing/ST_H3ToChildren.md) | `Array<Long>` | Returns the children of an H3 cell at the requested resolution. | v2.0.0 |
| [ST_H3ToGeom](Spatial-Indexing/ST_H3ToGeom.md) | `Array<Geometry>` | Return the result of H3 function [cellsToMultiPolygon(cells)](https://h3geo.org/docs/api/regions#cellstolinkedmultipolygon--cellstomultipolygon). | v1.6.0 |
| [ST_H3ToParent](Spatial-Indexing/ST_H3ToParent.md) | Long | Returns the parent of an H3 cell at the requested resolution. | v2.0.0 |
+| [ST_H3Uncompact](Spatial-Indexing/ST_H3Uncompact.md) | `Array<Long>` | Expands H3 cells to the requested resolution. | v2.0.0 |
| [ST_HilbertDistance](Spatial-Indexing/ST_HilbertDistance.md) | Long | Maps the midpoint of a geometry's envelope to an unsigned Hilbert-curve address within a supplied extent. | v2.0.0 |
| [ST_S2CellIDs](Spatial-Indexing/ST_S2CellIDs.md) | `Array<Long>` | Cover the geometry with Google S2 Cells, return the corresponding cell IDs with the given level. The level indicates the [size of cells](https://s2geometry.io/resources/s2cell_statistics.html). With... | v1.4.0 |
| [ST_S2ToGeom](Spatial-Indexing/ST_S2ToGeom.md) | `Array<Geometry>` | Returns an array of Polygons for the corresponding S2 cell IDs. | v1.6.0 |
diff --git a/docs/api/sql/Spatial-Indexing/ST_H3Uncompact.md b/docs/api/sql/Spatial-Indexing/ST_H3Uncompact.md
new file mode 100644
index 00000000000..fb9b476d612
--- /dev/null
+++ b/docs/api/sql/Spatial-Indexing/ST_H3Uncompact.md
@@ -0,0 +1,58 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+
+# ST_H3Uncompact
+
+Introduction: Expands an array of H3 cell IDs to the requested resolution using H3's [uncompactCells(cells, resolution)](https://h3geo.org/docs/api/hierarchy#uncompactcells).
+
+The input cells may have different resolutions and do not need to come from a compaction operation. Each coarser cell is replaced by its descendants at the target resolution. Cells already at the target resolution are retained.
+
+The requested resolution must be between 0 and 15, inclusive, and at least as fine as every input cell's resolution. A lower resolution or a resolution outside this range raises an error. An empty input array returns an empty array. A null array or resolution returns null.
+
+Input cells should be unique and non-overlapping; duplicate or overlapping cells may produce duplicates in the output. The order of the returned cells is not guaranteed. The result can grow rapidly when expanding to a much finer resolution.
+
+Format: `ST_H3Uncompact(cells: Array<Long>, resolution: Int)`
+
+Return type: `Array<Long>`
+
+Since: `v2.0.0`
+
+SQL Example
+
+```sql
+SELECT ST_H3Uncompact(array(601041811137363967), 5)
+```
+
+Output:
+
+```text
+[601041811137363967]
+```
+
+To expand this resolution 5 hexagon to its seven immediate children:
+
+```sql
+SELECT SIZE(ST_H3Uncompact(array(601041811137363967), 6)) AS cell_count
+```
+
+Output:
+
+```text
+7
+```
diff --git a/flink/src/main/java/org/apache/sedona/flink/Catalog.java b/flink/src/main/java/org/apache/sedona/flink/Catalog.java
index ab7270ec3d8..7a077703947 100644
--- a/flink/src/main/java/org/apache/sedona/flink/Catalog.java
+++ b/flink/src/main/java/org/apache/sedona/flink/Catalog.java
@@ -112,6 +112,7 @@ public class Catalog {
new Functions.ST_H3ToGeom(),
new Functions.ST_H3ToParent(),
new Functions.ST_H3ToChildren(),
+ new Functions.ST_H3Uncompact(),
new Functions.ST_HilbertDistance(),
new Functions.ST_BingTile(),
new Functions.ST_BingTileAt(),
diff --git a/flink/src/main/java/org/apache/sedona/flink/expressions/Functions.java b/flink/src/main/java/org/apache/sedona/flink/expressions/Functions.java
index 80ad4a9d7c3..b6ead43f3bd 100644
--- a/flink/src/main/java/org/apache/sedona/flink/expressions/Functions.java
+++ b/flink/src/main/java/org/apache/sedona/flink/expressions/Functions.java
@@ -2974,6 +2974,18 @@ public class Functions {
}
}
+ public static class ST_H3Uncompact extends ScalarFunction {
+ @DataTypeHint(value = "ARRAY<BIGINT>")
+ public Long[] eval(
+ @DataTypeHint("ARRAY<BIGINT>") Long[] cells, @DataTypeHint("INTEGER") Integer resolution) {
+ if (cells == null || resolution == null) {
+ return null;
+ }
+ return org.apache.sedona.common.Functions.h3Uncompact(
+ Arrays.stream(cells).mapToLong(Long::longValue).toArray(), resolution);
+ }
+ }
+
// =========================================================================
// Bing Tile functions
// =========================================================================
diff --git a/flink/src/test/java/org/apache/sedona/flink/FunctionTest.java b/flink/src/test/java/org/apache/sedona/flink/FunctionTest.java
index 4109434724c..fe97d462e53 100644
--- a/flink/src/test/java/org/apache/sedona/flink/FunctionTest.java
+++ b/flink/src/test/java/org/apache/sedona/flink/FunctionTest.java
@@ -23,12 +23,15 @@ import static org.apache.flink.table.api.Expressions.*;
import static org.junit.Assert.*;
import java.util.Arrays;
+import java.util.Collections;
import java.util.HashSet;
import java.util.List;
import java.util.Objects;
+import java.util.Set;
import java.util.stream.Collectors;
import org.apache.commons.codec.binary.Hex;
import org.apache.commons.lang3.tuple.Pair;
+import org.apache.flink.api.common.typeinfo.Types;
import org.apache.flink.table.api.Table;
import org.apache.flink.types.Row;
import org.apache.sedona.common.geometryObjects.Box2D;
@@ -2421,6 +2424,66 @@ public class FunctionTest extends TestBase {
}
}
+ @Test
+ public void testH3Uncompact() {
+ long parent = H3Utils.coordinateToCell(new Coordinate(1, 2), 5);
+ long other = H3Utils.coordinateToCell(new Coordinate(10, 20), 6);
+ Long[] cells =
+ (Long[])
+ first(
+ tableEnv.sqlQuery(
+ "SELECT ST_H3Uncompact(cells, resolution) FROM (VALUES (ARRAY["
+ + parent
+ + ", "
+ + other
+ + "], 6)) AS input(cells, resolution)"))
+ .getField(0);
+ assertNotNull(cells);
+ assertEquals(8, cells.length);
+ Set<Long> expected = new HashSet<>(H3Utils.h3.cellToChildren(parent, 6));
+ expected.add(other);
+ assertEquals(expected, new HashSet<>(Arrays.asList(cells)));
+ assertArrayEquals(
+ new Long[] {parent},
+ (Long[])
+ first(tableEnv.sqlQuery("SELECT ST_H3Uncompact(ARRAY[" + parent + "], 5)"))
+ .getField(0));
+ assertArrayEquals(
+ new Long[0],
+ (Long[])
+ first(
+ tableEnv
+ .fromDataStream(
+ env.fromCollection(
+ Collections.singletonList(new Long[0]),
+ Types.OBJECT_ARRAY(Types.LONG)))
+ .select(call("ST_H3Uncompact", $("f0"), 6)))
+ .getField(0));
+
+ long pentagon = H3Utils.h3.getPentagons(5).iterator().next();
+ Long[] pentagonCells =
+ (Long[])
+ first(tableEnv.sqlQuery("SELECT ST_H3Uncompact(ARRAY[" + pentagon + "], 7)"))
+ .getField(0);
+ assertNotNull(pentagonCells);
+ assertEquals(41, pentagonCells.length);
+ for (long cell : pentagonCells) {
+ assertEquals(pentagon, H3Utils.h3.cellToParent(cell, 5));
+ }
+
+ Row nulls =
+ first(
+ tableEnv.sqlQuery(
+ "SELECT ST_H3Uncompact(CAST(NULL AS ARRAY<BIGINT>), 6), "
+ + "ST_H3Uncompact(ARRAY["
+ + parent
+ + "], CAST(NULL AS INT)), "
+ + "ST_H3Uncompact(CAST(NULL AS ARRAY<BIGINT>), CAST(NULL AS INT))"));
+ for (int i = 0; i < 3; i++) {
+ assertNull(nulls.getField(i));
+ }
+ }
+
@Test
public void testGeometricMedian() throws ParseException {
Table pointTable =
diff --git a/python/sedona/spark/sql/st_functions.py b/python/sedona/spark/sql/st_functions.py
index c3c15b1b638..56d274baffe 100644
--- a/python/sedona/spark/sql/st_functions.py
+++ b/python/sedona/spark/sql/st_functions.py
@@ -1030,6 +1030,20 @@ def ST_H3ToChildren(
return _call_st_function("ST_H3ToChildren", args)
+@validate_argument_types
+def ST_H3Uncompact(
+ cells: Union[ColumnOrName, list], resolution: Union[ColumnOrName, int]
+) -> Column:
+ """Expand H3 cells to the requested resolution.
+ :param cells: H3 cells, which may have different resolutions
+ :param resolution: target resolution, at least that of every input cell and at most 15
+ :return: H3 cells at the target resolution
+ :rtype: List[long]
+ """
+ args = (cells, resolution)
+ return _call_st_function("ST_H3Uncompact", args)
+
+
# =========================================================================
# Bing Tile functions
# =========================================================================
diff --git a/python/tests/sql/test_dataframe_api.py b/python/tests/sql/test_dataframe_api.py
index 7c46cbae2da..a02063919e9 100644
--- a/python/tests/sql/test_dataframe_api.py
+++ b/python/tests/sql/test_dataframe_api.py
@@ -2021,6 +2021,19 @@ class TestDataFrameAPI(TestBase):
assert by_name == by_column == by_literal
assert df.select(stf.ST_H3ToChildren("cell", 5)).first()[0] == [parent]
+ def test_st_h3_uncompact(self):
+ parent = 601041811137363967
+ df = self.spark.createDataFrame([([parent], 6)], ["cells", "resolution"])
+ by_name, by_column, by_literal = df.select(
+ stf.ST_H3Uncompact("cells", 6),
+ stf.ST_H3Uncompact(f.col("cells"), f.col("resolution")),
+ stf.ST_H3Uncompact([parent], 6),
+ ).first()
+ assert len(by_name) == len(set(by_name)) == 7
+ assert by_name == by_column == by_literal
+ assert df.select(stf.ST_H3Uncompact("cells", 5)).first()[0] == [parent]
+ assert df.select(stf.ST_H3Uncompact([], 6)).first()[0] == []
+
def test_coverage_validation_catalog_calls(self):
rows = self.spark.createDataFrame(
[
diff --git a/python/tests/sql/test_function.py b/python/tests/sql/test_function.py
index 84131d8ccef..9b631af082e 100644
--- a/python/tests/sql/test_function.py
+++ b/python/tests/sql/test_function.py
@@ -2461,6 +2461,39 @@ class TestPredicateJoin(TestBase):
""").first()
assert all(value is None for value in nulls)
+ def test_st_h3_uncompact(self):
+ parent = 601041811137363967
+ children = self.spark.sql(f"SELECT ST_H3ToChildren({parent}, 6)").first()[0]
+ # Mix a resolution 6 child with a sibling's resolution 7 descendants.
+ mixed = [children[0]] + self.spark.sql(
+ f"SELECT ST_H3ToChildren({children[1]}, 7)"
+ ).first()[0]
+ result = self.spark.sql(
+ f"SELECT ST_H3Uncompact(array({','.join(map(str, mixed))}), 7)"
+ ).first()[0]
+ expected = (
+ self.spark.sql(f"SELECT ST_H3ToChildren({children[0]}, 7)").first()[0]
+ + mixed[1:]
+ )
+ assert len(result) == len(set(result)) == 14
+ assert set(result) == set(expected)
+ unchanged = self.spark.sql(
+ f"SELECT ST_H3Uncompact(array({parent}), 5)"
+ ).first()[0]
+ assert unchanged == [parent]
+ assert (
+ self.spark.sql(
+ "SELECT ST_H3Uncompact(CAST(array() AS ARRAY<BIGINT>), 6)"
+ ).first()[0]
+ == []
+ )
+ nulls = self.spark.sql(f"""
+ SELECT ST_H3Uncompact(CAST(NULL AS ARRAY<BIGINT>), 6),
+ ST_H3Uncompact(array({parent}), CAST(NULL AS INT)),
+ ST_H3Uncompact(CAST(NULL AS ARRAY<BIGINT>), CAST(NULL AS INT))
+ """).first()
+ assert all(value is None for value in nulls)
+
def test_st_h3_togeom(self):
df = self.spark.sql("""
SELECT
diff --git a/spark/common/src/main/scala/org/apache/sedona/sql/UDF/Catalog.scala b/spark/common/src/main/scala/org/apache/sedona/sql/UDF/Catalog.scala
index 58373df5bf9..080ec3bb641 100644
--- a/spark/common/src/main/scala/org/apache/sedona/sql/UDF/Catalog.scala
+++ b/spark/common/src/main/scala/org/apache/sedona/sql/UDF/Catalog.scala
@@ -319,6 +319,7 @@ object Catalog extends AbstractCatalog with Logging {
function[ST_H3ToGeom](),
function[ST_H3ToParent](),
function[ST_H3ToChildren](),
+ function[ST_H3Uncompact](),
function[ST_HilbertDistance](),
function[ST_S2CellIDs](),
function[ST_S2ToGeom](),
diff --git a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala
index feeeea9ee0b..5ddc42b645e 100644
--- a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala
+++ b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala
@@ -1743,6 +1743,14 @@ private[apache] case class ST_H3ToChildren(inputExpressions: Seq[Expression])
}
}
+private[apache] case class ST_H3Uncompact(inputExpressions: Seq[Expression])
+ extends InferredExpression(Functions.h3Uncompact _) {
+
+ protected def withNewChildrenInternal(newChildren: IndexedSeq[Expression]) = {
+ copy(inputExpressions = newChildren)
+ }
+}
+
// =========================================================================
// Bing Tile expressions
// =========================================================================
diff --git a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/InferredExpression.scala b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/InferredExpression.scala
index 09bebbccca1..658bf923b54 100644
--- a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/InferredExpression.scala
+++ b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/InferredExpression.scala
@@ -230,7 +230,10 @@ object InferredTypes {
} else if (t =:= typeOf[String]) { expr => input =>
expr.asString(input)
} else if (t =:= typeOf[Array[Long]]) { expr => input =>
- expr.eval(input).asInstanceOf[ArrayData].toLongArray()
+ expr.eval(input).asInstanceOf[ArrayData] match {
+ case null => null
+ case arrayData: ArrayData => arrayData.toLongArray()
+ }
} else if (t =:= typeOf[Array[String]]) { expr => input =>
expr.eval(input).asInstanceOf[ArrayData] match {
case null => null
diff --git a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala
index bdd410d266c..23957413802 100644
--- a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala
+++ b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala
@@ -320,6 +320,15 @@ object st_functions {
def ST_H3ToChildren(cell: Long, resolution: Integer): Column =
wrapExpression[ST_H3ToChildren](cell, resolution)
+ def ST_H3Uncompact(cells: Column, resolution: Column): Column =
+ wrapExpression[ST_H3Uncompact](cells, resolution)
+
+ def ST_H3Uncompact(cells: Column, resolution: Integer): Column =
+ wrapExpression[ST_H3Uncompact](cells, resolution)
+
+ def ST_H3Uncompact(cells: Array[Long], resolution: Integer): Column =
+ wrapExpression[ST_H3Uncompact](cells, resolution)
+
def ST_HilbertDistance(
geometry: Column,
xmin: Column,
diff --git a/spark/common/src/test/scala/org/apache/sedona/sql/dataFrameAPITestScala.scala b/spark/common/src/test/scala/org/apache/sedona/sql/dataFrameAPITestScala.scala
index 1f576a768b8..bd5ac48ca6a 100644
--- a/spark/common/src/test/scala/org/apache/sedona/sql/dataFrameAPITestScala.scala
+++ b/spark/common/src/test/scala/org/apache/sedona/sql/dataFrameAPITestScala.scala
@@ -2116,6 +2116,22 @@ class dataFrameAPITestScala extends TestBaseScala {
}
}
+ it("Passed ST_H3Uncompact") {
+ val cell = 601041811137363967L
+ val result = sparkSession
+ .sql(s"SELECT array($cell) AS cells, 6 AS resolution")
+ .select(
+ ST_H3Uncompact(col("cells"), col("resolution")),
+ ST_H3Uncompact(col("cells"), 6),
+ ST_H3Uncompact(Array(cell), 6))
+ .first()
+ val cells = result.getSeq[Long](0)
+ assert(cells.size == 7)
+ assert(cells.toSet == org.apache.sedona.common.Functions.h3ToChildren(cell, 6).toSet)
+ assert(result.getSeq[Long](1) == cells)
+ assert(result.getSeq[Long](2) == cells)
+ }
+
it("Passed ST_DistanceSphere") {
val baseDf = sparkSession.sql(
"SELECT ST_GeomFromWKT('POINT (0 0)') AS geom1, ST_GeomFromWKT('POINT (90 0)') AS geom2")
diff --git a/spark/common/src/test/scala/org/apache/sedona/sql/functions/STH3Functions.scala b/spark/common/src/test/scala/org/apache/sedona/sql/functions/STH3Functions.scala
index 3475d47dd3d..f2d53be4ab3 100644
--- a/spark/common/src/test/scala/org/apache/sedona/sql/functions/STH3Functions.scala
+++ b/spark/common/src/test/scala/org/apache/sedona/sql/functions/STH3Functions.scala
@@ -185,6 +185,65 @@ class STH3Functions extends TestBaseScala with Matchers with GeometrySample with
(0 until 3).foreach(i => result.isNullAt(i) should be(true))
}
+ it("should uncompact cells at mixed resolutions") {
+ val parent = H3Utils.coordinateToCell(new Coordinate(1, 2), 5)
+ val other = H3Utils.coordinateToCell(new Coordinate(10, 20), 6)
+ val cells = Seq((Seq(parent, other), 6))
+ .toDF("cells", "resolution")
+ .select(expr("ST_H3Uncompact(cells, resolution)"))
+ .first()
+ .getSeq[Long](0)
+ cells.size should equal(8)
+ cells.toSet should equal(Functions.h3ToChildren(parent, 6).toSet + other)
+
+ val pentagon = H3Utils.h3.getPentagons(5).iterator().next().longValue()
+ sparkSession
+ .sql(s"SELECT ST_H3Uncompact(array($pentagon), 7)")
+ .first()
+ .getSeq[Long](0)
+ .size should equal(41)
+ }
+
+ it("should preserve cells at the target resolution and return empty arrays") {
+ val cell = H3Utils.coordinateToCell(new Coordinate(1, 2), 5)
+ val result = sparkSession
+ .sql(s"""SELECT ST_H3Uncompact(array($cell), 5),
+ |ST_H3Uncompact(CAST(array() AS ARRAY<BIGINT>), 6)
+ |""".stripMargin)
+ .first()
+ result.getSeq[Long](0) should equal(Seq(cell))
+ result.getSeq[Long](1) should be(empty)
+ }
+
+ it("should propagate null inputs to ST_H3Uncompact") {
+ val result = sparkSession
+ .sql("""SELECT
+ |ST_H3Uncompact(CAST(NULL AS ARRAY<BIGINT>), 6),
+ |ST_H3Uncompact(array(601041811137363967L), CAST(NULL AS INT)),
+ |ST_H3Uncompact(CAST(NULL AS ARRAY<BIGINT>), CAST(NULL AS INT))
+ |""".stripMargin)
+ .first()
+ (0 until 3).foreach(i => result.isNullAt(i) should be(true))
+
+ val inputs = Seq((None, Some(6)), (Some(Seq(601041811137363967L)), None), (None, None))
+ inputs
+ .toDF("cells", "resolution")
+ .select(expr("ST_H3Uncompact(cells, resolution)"))
+ .collect()
+ .foreach(row => row.isNullAt(0) should be(true))
+ }
+
+ it("should reject a target resolution coarser than an input cell") {
+ val cell = H3Utils.coordinateToCell(new Coordinate(1, 2), 6)
+ val error = intercept[Exception] {
+ sparkSession.sql(s"SELECT ST_H3Uncompact(array($cell), 5)").collect()
+ }
+ Iterator
+ .iterate[Throwable](error)(_.getCause)
+ .takeWhile(_ != null)
+ .exists(_.isInstanceOf[com.uber.h3core.exceptions.H3Exception]) should be(true)
+ }
+
it("should return the parent cell at the requested resolution") {
Given("DataFrame with a valid Geometry")
val geometryTable = Seq("POINT(1 2)").map(geom => Tuple1(wktReader.read(geom))).toDF("geom")