sedona.spark.geopandas.tools

sedona.spark.geopandas.tools.sjoin.sjoin(left_df: GeoDataFrame, right_df: GeoDataFrame, how='inner', predicate='intersects', lsuffix='left', rsuffix='right', distance=None, on_attribute=None, **kwargs) → GeoDataFrame[source]

Spatial join of two GeoDataFrames.

Parameters:

  • left_df (GeoDataFrames) –

  • right_df (GeoDataFrames) –

  • how (string, default 'inner') –

    The type of join:

    • ’left’: use keys from left_df; retain only left_df geometry column

    • ’right’: use keys from right_df; retain only right_df geometry column

    • ’inner’: use intersection of keys from both dfs; retain only left_df geometry column

  • predicate (string, default 'intersects') – Binary predicate. Valid values are determined by the spatial index used. You can check the valid values in left_df or right_df as left_df.sindex.valid_query_predicates or right_df.sindex.valid_query_predicates Replaces deprecated op parameter.

  • lsuffix (string, default 'left') – Suffix to apply to overlapping column names (left GeoDataFrame).

  • rsuffix (string, default 'right') – Suffix to apply to overlapping column names (right GeoDataFrame).

  • distance (number or array_like, optional) – Distance(s) around each input geometry within which to query the tree for the ‘dwithin’ predicate. If array_like, must be one-dimensional with length equal to length of left GeoDataFrame. Required if predicate='dwithin'.

  • on_attribute (string, list or tuple) – Column name(s) to join on as an additional join restriction on top of the spatial predicate. These must be found in both DataFrames. If set, observations are joined only if the predicate applies and values in specified columns match.

Returns:

The joined GeoDataFrame.

Return type:

GeoDataFrame

Examples

>>> from sedona.spark.geopandas.tools import sjoin
>>> groceries_w_communities = sjoin(groceries, chicago)
>>> groceries_w_communities.head()  
   OBJECTID       community                           geometry
0        16          UPTOWN  MULTIPOINT ((-87.65661 41.97321))
1        18     MORGAN PARK  MULTIPOINT ((-87.68136 41.69713))
2        22  NEAR WEST SIDE  MULTIPOINT ((-87.63918 41.86847))
3        23  NEAR WEST SIDE  MULTIPOINT ((-87.65495 41.87783))
4        27         CHATHAM  MULTIPOINT ((-87.62715 41.73623))
[5 rows x 95 columns]

Notes

Every operation in GeoPandas is planar, i.e. the potential third dimension is not taken into account.

Point nearest joins using Sedona’s existing KNN execution strategies.

sedona.spark.geopandas.tools.sjoin_nearest.sjoin_nearest(left_df, right_df, how='inner', max_distance=None, lsuffix='left', rsuffix='right', distance_col=None, exclusive=False)[source]

Join each left point to its nearest right point using planar distance.

This initial implementation supports point inputs, how='inner', exclusive=False, default suffixes, unique string column names and single-level indexes (including duplicate index values). Null and empty geometries do not match. The left geometry, CRS and index are retained.

Parameters:

  • left_df (GeoDataFrame) – Distributed point frames to join.

  • right_df (GeoDataFrame) – Distributed point frames to join.

  • how (str, default 'inner') – Only inner joins are supported.

  • max_distance (float, optional) – Positive finite distance in CRS units. Filters nearest results; it does not reduce the KNN search radius.

  • lsuffix (str, default 'left', 'right') – Only the default suffixes are supported for overlapping columns.

  • rsuffix (str, default 'left', 'right') – Only the default suffixes are supported for overlapping columns.

  • distance_col (str, optional) – New output column for the distance. Must not replace an input column.

  • exclusive (bool, default False) – Only False is supported; equal points can match at distance zero.

Returns:

Nearest matches, with no guaranteed row order.

Return type:

GeoDataFrame

Notes

Ties follow spark.sedona.join.knn.includeTieBreakers (default False). False chooses one nearest candidate with unspecified tie selection. True includes ties, but Sedona may omit distinct rows with identical candidate geometries. Unlike GeoPandas, all equidistant rows are not guaranteed. This function does not change that session setting.

Distances are planar and ignore Z. Use a projected CRS for meaningful distance units. Scalar validation summaries are evaluated eagerly on Spark; input geometry rows remain distributed.