Spatial join

Draft: written, not yet checked by a person Operation · spatial-join

Adds the fields of features in one layer to features of another, matching by a spatial relationship.

Pitfall. A feature matching several features on the other side becomes several rows unless the engine aggregates them.

Pitfall. Features that share only a boundary count as intersecting.

About this operation
Also called	Join attributes by location, sjoin, location join
Group	`vector/join`
Checks	`crs.agreement, join.unmatched, join.many_to_many`
Pitfalls	2 listed above
Columbus tool	`vector_op · spatial_join`
Notes	Not stated
Status	active
Broader	Not stated
Narrower	Not stated
Related	`attribute-join` `intersect`

Parameters

Name	Type	Required	Default	Values	Note
`predicate`	enum	no	`intersects`	`intersects, within, contains, touches, crosses, overlaps`	Not stated
`how`	enum	no	`left`	`left, inner`	Not stated

Direction	Name	Type	Geometry	Note
Input	`left`	vector	Not stated	Not stated
Input	`right`	vector	Not stated	Not stated
Output	`output`	vector	Not stated	Not stated

Engine	Tool	Parameters	Differences
`dask-geopandas`	`dask_geopandas.sjoin`	`predicate` → `predicate` `how` → `how` `left` → `left` `right` → `right`	Defaults to an inner join (unmatched left features dropped); Columbus defaults to left. Lazy: returns a dask GeoDataFrame; call compute() for the result.
`geopandas`	`geopandas.sjoin`	`predicate` → `predicate` `how` → `how` `left` → `left_df` `right` → `right_df`	Defaults to an inner join (unmatched left features dropped); Columbus defaults to left.
`qgis`	`native:joinattributesbylocation`	`predicate` → `PREDICATE` : intersects = 0; contains = 1; touches = 3; overlaps = 4; within = 5; crosses = 6 `how` → `DISCARD_NONMATCHING` : left = no; inner = yes `left` → `INPUT` `right` → `JOIN` `output` → `OUTPUT`	METHOD 0 (used here) gives one row per match, like Columbus; QGIS's default keeps only the first match. Preset: `{"METHOD":0}`
`sf`	`sf::st_join`	`predicate` → `join` : intersects = st_intersects; within = st_within; contains = st_contains; touches = st_touches; crosses = st_crosses; overlaps = st_overlaps. join takes the predicate function itself (st_intersects), not its name as text. `how` left = TRUE (the default) keeps unmatched rows; left = FALSE is an inner join. Passed through ... `left` → `x` `right` → `y`	None noted