feat(rust/sedona): Improve sd_random_geometry() and expose as a Python function

benchmarks/test_bench_base.py

@@ -43,47 +43,47 @@ def setup_class(self):
                 "points_simple",
                 {
                     "geom_type": "Point",
-                    "target_rows": num_geoms,
+                    "num_rows": num_geoms,
                 },
             ),
             (
                 "segments_large",
                 {
                     "geom_type": "LineString",
-                    "target_rows": num_geoms,
-                    "vertices_per_linestring_range": [2, 10],
+                    "num_rows": num_geoms,
+                    "num_vertices": [2, 10],
                 },
             ),
             (
                 "polygons_simple",
                 {
                     "geom_type": "Polygon",
-                    "target_rows": num_geoms,
-                    "vertices_per_linestring_range": [10, 10],
+                    "num_rows": num_geoms,
+                    "num_vertices": [10, 10],
                 },
             ),
             (
                 "polygons_complex",
                 {
                     "geom_type": "Polygon",
-                    "target_rows": num_geoms,
-                    "vertices_per_linestring_range": [500, 500],
+                    "num_rows": num_geoms,
+                    "num_vertices": [500, 500],
                 },
             ),
             (
                 "collections_simple",
                 {
                     "geom_type": "GeometryCollection",
-                    "target_rows": num_geoms,
-                    "vertices_per_linestring_range": [10, 10],
+                    "num_rows": num_geoms,
+                    "num_vertices": [10, 10],
                 },
             ),
             (
                 "collections_complex",
                 {
                     "geom_type": "GeometryCollection",
-                    "target_rows": num_geoms,
-                    "vertices_per_linestring_range": [500, 500],
+                    "num_rows": num_geoms,
+                    "num_vertices": [500, 500],
                 },
             ),
         ]:
@@ -97,7 +97,7 @@ def setup_class(self):
                 {
                     "seed": 42,
                     "bounds": [0.0, 0.0, 80.0, 100.0],  # Slightly left-leaning
-                    "size_range": [
+                    "size": [
                         1.0,
                         15.0,
                     ],  # Medium-sized geometries for good intersection chance
@@ -110,7 +110,7 @@ def setup_class(self):
                 {
                     "seed": 43,
                     "bounds": [20.0, 0.0, 100.0, 100.0],  # Slightly right-leaning
-                    "size_range": [1.0, 15.0],  # Same size range for fair comparison
+                    "size": [1.0, 15.0],  # Same size range for fair comparison
                 }
             )
 

benchmarks/test_knn.py

@@ -30,9 +30,9 @@ def setup_class(self):
         # Create building-like polygons (index side - fewer, larger geometries)
         building_options = {
             "geom_type": "Polygon",
-            "target_rows": 2_000,
-            "vertices_per_linestring_range": [4, 8],
-            "size_range": [0.001, 0.01],
+            "num_rows": 2_000,
+            "num_vertices": [4, 8],
+            "size": [0.001, 0.01],
             "seed": 42,
         }
 
@@ -51,7 +51,7 @@ def setup_class(self):
         # Create trip pickup points (probe side)
         trip_options = {
             "geom_type": "Point",
-            "target_rows": 10_000,
+            "num_rows": 10_000,
             "seed": 43,
         }
 

python/sedonadb/python/sedonadb/context.py

@@ -14,15 +14,18 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
+
 import os
 import sys
+from functools import cached_property
 from pathlib import Path
 from typing import Any, Dict, Iterable, Literal, Optional, Union
 
 from sedonadb._lib import InternalContext, configure_proj_shared
+from sedonadb._options import Options
 from sedonadb.dataframe import DataFrame, _create_data_frame
+from sedonadb.functions import Functions
 from sedonadb.utility import sedona  # noqa: F401
-from sedonadb._options import Options
 
 
 class SedonaContext:
@@ -272,6 +275,11 @@ def register_udf(self, udf: Any):
         """
         self._impl.register_udf(udf)
 
+    @cached_property
+    def funcs(self) -> Functions:
+        """Access Python wrappers for SedonaDB functions"""
+        return Functions(self)
+
 
 def connect() -> SedonaContext:
     """Create a new [SedonaContext][sedonadb.context.SedonaContext]"""

python/sedonadb/python/sedonadb/functions/__init__.py

@@ -0,0 +1,40 @@
+# 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.
+
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sedonadb.functions.table import TableFunctions
+
+
+class Functions:
+    """Functions accessor
+
+    This class provides Pythonic wrappers to call SedonaDB functions
+    given a specific SedonaDB context.
+    """
+
+    def __init__(self, ctx):
+        self._ctx = ctx
+
+    @cached_property
+    def table(self) -> "TableFunctions":
+        """Access SedonaDB Table functions"""
+        from sedonadb.functions.table import TableFunctions
+
+        return TableFunctions(self._ctx)

python/sedonadb/python/sedonadb/functions/table.py

@@ -0,0 +1,114 @@
+# 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.
+
+import json
+from typing import Optional, Literal, Union, Tuple, Iterable
+
+from sedonadb.dataframe import DataFrame
+from sedonadb.utility import sedona  # noqa: F401
+
+
+class TableFunctions:
+    def __init__(self, ctx):
+        self._ctx = ctx
+
+    def sd_random_geometry(
+        self,
+        geom_type: Optional[
+            Literal[
+                "Geometry",
+                "Point",
+                "LineString",
+                "Polygon",
+                "MultiPoint",
+                "MultiLineString",
+                "MultiPolygon",
+                "GeometryCollection",
+            ]
+        ] = None,
+        num_rows: Optional[int] = None,
+        *,
+        num_vertices: Union[int, Tuple[int, int], None] = None,
+        num_parts: Union[int, Tuple[int, int], None] = None,
+        size: Union[float, Tuple[float, float], None] = None,
+        bounds: Optional[Iterable[float]] = None,
+        hole_rate: Optional[float] = None,
+        empty_rate: Optional[float] = None,
+        null_rate: Optional[float] = None,
+        seed: Optional[int] = None,
+    ) -> DataFrame:
+        """
+        Generate a DataFrame with random geometries for testing purposes.
+        This function creates a DataFrame containing randomly generated geometries with
+        configurable parameters for geometry type, size, complexity, and spatial distribution.
+        Returns a DataFrame with columns 'id', 'dist', and 'geometry' containing randomly
+        generated geometries and distances.
+
+        Parameters
+        ----------
+        geom_type : str, default "Point"
+            The type of geometry to generate. One of "Geometry",
+            "Point", "LineString",  "Polygon", "MultiPoint", "MultiLineString",
+            "MultiPolygon", or "GeometryCollection".
+        num_rows : int, default 1024
+            Number of rows to generate.
+        num_vertices : int or tuple of (int, int), default 4
+            Number of vertices per geometry. If a tuple, specifies (min, max) range.
+        num_parts : int or tuple of (int, int), default (1, 3)
+            Number of parts for multi-geometries. If a tuple, specifies (min, max) range.
+        size : float or tuple of (float, float), default (1.0, 10.0)
+            Spatial size of geometries. If a tuple, specifies (min, max) range.
+        bounds : iterable of float, default [0.0, 0.0, 100.0, 100.0]
+            Spatial bounds as [xmin, ymin, xmax, ymax] to constrain generated geometries.
+        hole_rate : float, default 0.0
+            Rate of polygons with holes, between 0.0 and 1.0.
+        empty_rate : float, default 0.0
+            Rate of empty geometries, between 0.0 and 1.0.
+        null_rate : float, default 0.0
+            Rate of null geometries, between 0.0 and 1.0.
+        seed : int, optional
+            Random seed for reproducible geometry generation. If omitted, the result is
+            non-deterministic.
+
+        Examples
+        --------
+        >>> sd = sedona.db.connect()
+        >>> sd.funcs.table.sd_random_geometry("Point", 1, seed=938).show()
+        ┌───────┬───────────────────┬────────────────────────────────────────────┐
+        │   id  ┆        dist       ┆                  geometry                  │
+        │ int32 ┆      float64      ┆                  geometry                  │
+        ╞═══════╪═══════════════════╪════════════════════════════════════════════╡
+        │     0 ┆ 58.86528701627309 ┆ POINT(94.77686827801787 17.65107885959438) │
+        └───────┴───────────────────┴────────────────────────────────────────────┘
+        """
+
+        args = {
+            "bounds": bounds,
+            "empty_rate": empty_rate,
+            "geom_type": geom_type,
+            "null_rate": null_rate,
+            "num_parts": num_parts,
+            "hole_rate": hole_rate,
+            "seed": seed,
+            "size": size,
+            "num_rows": num_rows,
+            "num_vertices": num_vertices,
+        }
+
+        args = {k: v for k, v in args.items() if v is not None}
+
+        return self._ctx.sql(f"SELECT * FROM sd_random_geometry('{json.dumps(args)}')")

python/sedonadb/python/sedonadb/testing.py

@@ -14,8 +14,8 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-import os
 import math
+import os
 import warnings
 from pathlib import Path
 from typing import TYPE_CHECKING, List, Tuple
@@ -29,6 +29,17 @@
     import sedonadb
 
 
+def random_geometry(*args, **kwargs) -> "sedonadb.dataframe.DataFrame":
+    """
+    Generate a DataFrame with random geometries for testing purposes by
+    calling sd_random_geometry() on an isolated SedonaDB session.
+    """
+    import sedonadb
+
+    sd = sedonadb.connect()
+    return sd.funcs.table.sd_random_geometry(*args, **kwargs)
+
+
 def skip_if_not_exists(path: Path):
     """Skip a test using pytest.skip() if path does not exist
 

python/sedonadb/tests/test_funcs.py

@@ -0,0 +1,26 @@
+# 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.
+
+
+def test_random_geometry(con):
+    df = con.funcs.table.sd_random_geometry("Point", 5, seed=99873)
+
+    # Ensure we produce the correct number of rows
+    assert df.count() == 5
+
+    # Ensure the output is reproducible
+    assert df.to_arrow_table() == df.to_arrow_table()