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")