ST_H3Bins

ST_H3Bins takes a geometry column and a numeric H3 resolution and returns an array column. The result array contains h3 bins that cover the spatial extent of each record in the input column. H3 is a hierarchical geospatial indexing system that partitions the world sphere into hexagonal and pentagonal tiles. H3 supports 16 resolutions ranging from 0 to 15, where 0 results in the largest bins and 15 the smallest. For detailed information on the number of bins and average bin areas at every resolution, please refer to the H3 Tables of Cell Statistics Across Resolutions.

You can optionally specify a numeric value for padding, which conceptually applies a buffer of the specified distance to the input geometry before creating the H3 bins. The padding is in the units of meters. Use ST_BinGeometry to obtain the geometry of each result bin.

ST_H3Bins requires the spatial reference to be set to World Geodetic System 1984 (EPSG:4326). If the input geometry is in a different spatial reference, the function automatically transforms the geometry into World Geodetic System 1984. To learn more about spatial references, see Coordinate systems and transformations.

Java bindings for H3 are required to run ST_H3Bins. For example, on Spark local mode, you can start a PySpark session with the H3 Java bindings by adding --packages com.uber:h3:4.0.1 as shown below.

Windows

Linux

Use dark colors for code blocksCopy
pyspark --jars C:\engine\geoanalytics.jar ^
        --py-files C:\data\engine\geoanalytics.zip ^
        --conf spark.plugins=com.esri.geoanalytics.Plugin ^
        --conf spark.serializer=org.apache.spark.serializer.KryoSerializer ^
        --conf spark.kryo.registrator=com.esri.geoanalytics.KryoRegistrator ^
        --packages com.uber:h3:4.0.1

Function	Syntax
Python	`h3_bins(geometry, h3_resolution, padding=0.0)`
SQL	`ST_H3Bins(geometry, h3_resolution, padding)`
Scala	`h3Bins(geometry, h3Resolution, padding)`

For more details, go to the GeoAnalytics Engine API reference for h3_bins.

Python and SQL Example

Python

SQL

Use dark colors for code blocksCopy
from geoanalytics.sql import functions as ST
from pyspark.sql import functions as F

data = [
    ("POINT (-117.05 34.22)",),
    ("LINESTRING (-116.89 33.96, -116.71 34.01, -116.66 34.08)", ),
    ("POLYGON ((-117.27 34.05, -117.22 33.91, -116.96 33.64, -116.66 33.71, -117.08 33.91, -117.16 34.09, -117.27 34.05))", )
]

df = spark.createDataFrame(data, ["wkt"]) \
          .withColumn("geometry", ST.geom_from_text("wkt", srid=4326))

bins = df.select(ST.h3_bins("geometry", 6).alias("h3_bins"))

bin_geometries = bins.select(F.explode("h3_bins").alias("bins")).select(ST.bin_geometry("bins"))

ax = df.st.plot("geometry", facecolor="none", edgecolor="red")
bin_geometries.st.plot(ax=ax, facecolor="none", edgecolor="blue")

Plotting example for ST_H3Bins — Plotted result for ST_H3Bins.

Scala Example

Scala
Use dark colors for code blocksCopy
import com.esri.geoanalytics.sql.{functions => ST}
import org.apache.spark.sql.{functions => F}

case class GeometryRow(wkt: String)
val data = Seq(GeometryRow("POINT (-117.05 34.22)"),
               GeometryRow("LINESTRING (-116.89 33.96, -116.71 34.01, -116.66 34.08)"),
               GeometryRow("POLYGON ((-117.27 34.05, -117.22 33.91, -116.96 33.64, -116.66 33.71, -117.08 33.91, -117.16 34.09, -117.27 34.05))"))

val df = spark.createDataFrame(data)
              .withColumn("geometry", ST.geomFromText($"wkt", F.lit(4326)))
              .select(ST.h3Bins($"geometry", 6, 0).alias("h3_bins"))

df.show()

Result
Use dark colors for code blocksCopy
+--------------------+
|             h3_bins|
+--------------------+
|[bin#604214655010...|
|[bin#604214647762...|
|[bin#604214676619...|
+--------------------+

Version table

Release	Notes
1.1.0	Python and SQL functions introduced
1.5.0	Scala function introduced

ST_H3Bins

Python and SQL Example

Scala Example

Version table

Related topics