Spatial Connected Components Python Module

Spatial connected components identify groups of geometries that are transitively connected through a spatial predicate. Unlike density-based clustering (DBSCAN), they do not require a minimum density: any chain of pairwise-related geometries forms a single component.

Predicate Functions

These eight functions assign a connected component ID to each geometry according to a spatial predicate.

ST_IntersectsCC

Connects geometries that share at least one point. See the ST_IntersectsCC SQL reference.

ST_TouchesCC

Connects geometries that share a boundary point without overlapping interiors. See the ST_TouchesCC SQL reference.

ST_OverlapsCC

Connects geometries of the same dimension that share some, but not all, interior points. See the ST_OverlapsCC SQL reference.

ST_ContainsCC

Connects geometries when one fully contains another. See the ST_ContainsCC SQL reference.

ST_CoversCC

Connects geometries when one covers every point of another. See the ST_CoversCC SQL reference.

ST_WithinCC

Connects geometries when one is completely within another. See the ST_WithinCC SQL reference.

ST_CoveredByCC

Connects geometries when one is covered by another. See the ST_CoveredByCC SQL reference.

ST_CrossesCC

Connects geometries that cross and have a lower-dimensional intersection. See the ST_CrossesCC SQL reference.

Shared Predicate Function API

All eight predicate functions share this signature; replace ST_IntersectsCC with the function name you need:

ST_IntersectsCC(
    geometry: ColumnOrName,
    partition_by: Optional[ColumnOrName] = None,
) -> Column

Parameters

ColumnOrName

required

Geometry column or column name to analyze. Pass the desired GeometryType column explicitly.

Optional[ColumnOrName]

Optional column to partition by before computing connected components. When provided, the spatial predicate is only evaluated between rows that share the same partition value. This can significantly improve performance on large datasets.

Returns

BIGINT

A PySpark Column containing the connected component ID for each row, including singletons (geometries that do not satisfy the predicate with any other geometry).

Usage Examples

from sedona.spark.sql.st_functions import ST_IntersectsCC, ST_TouchesCC

# Find connected components based on intersection
result = df.select("*", ST_IntersectsCC("geometry").alias("component_id"))

# With partition_by to limit comparisons within categories
result = df.select(
    "*", ST_IntersectsCC("geometry", partition_by="category").alias("component_id")
)

# Using ST_TouchesCC for boundary-adjacent geometries
result = df.select("*", ST_TouchesCC("geometry").alias("component_id"))

ST_DWithinCC

Assign a connected component ID to each geometry using a distance-based predicate. See the ST_DWithinCC SQL reference.

ST_DWithinCC(
    geometry: ColumnOrName,
    distance: Union[ColumnOrName, float],
    use_spheroid: Optional[Union[ColumnOrName, bool]] = None,
    partition_by: Optional[ColumnOrName] = None,
) -> Column

Parameters

ColumnOrName

required

Geometry column or column name to analyze.

Union[ColumnOrName, float]

required

The distance threshold. Two geometries within this distance are considered connected.

Optional[Union[ColumnOrName, bool]]

Whether to use spheroidal distance calculation. Default is false.

Optional[ColumnOrName]

Optional column to partition by before computing connected components. When provided, the spatial predicate is only evaluated between rows that share the same partition value.

Returns

BIGINT

A PySpark Column containing the connected component ID for each row.

Usage Examples

from sedona.spark.sql.st_functions import ST_DWithinCC

# Distance-based connected components
result = df.select(
    "*", ST_DWithinCC("geometry", 1.0, use_spheroid=False).alias("component_id")
)

# With partition_by
result = df.select(
    "*", ST_DWithinCC("geometry", 500.0, use_spheroid=True, partition_by="state").alias("component_id")
)

Wherobots Cloud REST API

WherobotsDB

Vector tiles (PMTiles)

Havasu (Iceberg) table management

GeoStats and Map Matching

Rasterflow

Spatial Connected Components Python Module

Predicate Functions

ST_IntersectsCC

ST_TouchesCC

ST_OverlapsCC

ST_ContainsCC

ST_CoversCC

ST_WithinCC

ST_CoveredByCC

ST_CrossesCC

Shared Predicate Function API

Parameters

Returns

Usage Examples

ST_DWithinCC

Parameters

Returns

Usage Examples

​Predicate Functions

​ST_IntersectsCC

​ST_TouchesCC

​ST_OverlapsCC

​ST_ContainsCC

​ST_CoversCC

​ST_WithinCC

​ST_CoveredByCC

​ST_CrossesCC

​Shared Predicate Function API

​Parameters

​Returns

​Usage Examples

​ST_DWithinCC

​Parameters

​Returns

​Usage Examples

Predicate Functions

ST_IntersectsCC

ST_TouchesCC

ST_OverlapsCC

ST_ContainsCC

ST_CoversCC

ST_WithinCC

ST_CoveredByCC

ST_CrossesCC

Shared Predicate Function API

Parameters

Returns

Usage Examples

ST_DWithinCC

Parameters

Returns

Usage Examples