Skip to contents

Spatial join for sf objects using SedonaDB

Source: R/sx_join.R
sx_join.Rd

Performs a spatial join between two sf objects or a spatial object and a registered SedonaDB view.

Usage

sx_join(
  x,
  y,
  join = "intersects",
  distance = NULL,
  left = TRUE,
  largest = FALSE,
  output = NULL,
  view_name = NULL,
  overwrite = FALSE,
  verbosity = NULL,
  use_s2 = NULL,
  ...
)

Arguments

x

A sedonadb_dataframe, sf object, or view name (character) in SedonaDB representing the left-hand side of the join.

y

A sedonadb_dataframe, sf object, or view name (character) in SedonaDB representing the right-hand side of the join.

join

Character. Spatial predicate to use. One of: intersects (default), contains, within, touches, crosses, overlaps, covers, covered_by, disjoint, equals, contains_properly, or dwithin.

distance

Numeric (optional). Distance threshold for the dwithin predicate. Required when predicate = "dwithin".

left

Logical. If TRUE (default), performs a left join returning all features from x with NA values for non-matching y attributes. If FALSE, performs an inner join returning only features from x that match y. Matches sf::st_join behavior.

largest

Logical. If TRUE, returns only the y feature with the largest overlap for each x feature. If FALSE (default), returns all matching y features. Overlap is measured by area for polygons, length for lines, and treated as equal (1.0) for points. Matches sf::st_join behavior.

output

Character or NULL. Output type: sedonadb_dataframe (default), sf, tibble, geoarrow, or raw. If NULL, uses getOption("sx.output_type", "sedonadb_dataframe").

Output types:

  • sedonadb_dataframe: Lazy data frame (no collection).

  • sf: Materialized sf object.

  • tibble: Tibble without geometry.

  • geoarrow: Tibble with geoarrow_vctr geometry (Arrow-native).

  • raw: Tibble with geometry as raw WKB bytes (for database import).

view_name

Character (optional). Name to register the result as a persistent view in the active backend. If NULL (default), returns the result directly without creating a view.

Not all backends support named views. Check backend-specific documentation for availability.

overwrite

Logical. If TRUE, overwrites any existing view with the same name. Default is FALSE.

verbosity

Character or NULL. Controls message output for this function call.

  • "quiet": Suppress all informational messages.

  • "info": Show standard progress and status messages.

  • "debug": Show additional diagnostic messages for troubleshooting.

If NULL (the default), uses the global sx.verbosity option. See sx_options() for persistent configuration.

use_s2

Logical or NULL. Controls spherical geometry (S2) for this operation.

  • TRUE: Use S2 spherical geometry (accurate for geographic coordinates).

  • FALSE: Use planar geometry (faster, appropriate for projected CRS).

  • NULL (default): Uses the global sx_use_s2() setting.

...

Ignored. Used to catch and warn about unsupported sf arguments.

Value

Depends on output. Defaults to sedonadb_dataframe.

Examples

# \donttest{
library(sf)
nc <- st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)

# Create points to join against counties
set.seed(42)
pts <- st_sample(st_union(nc), 50) |> st_as_sf()
pts$point_id <- seq_len(nrow(pts))

# -------------------------------------------------------------------
# Example 1: Using sf objects (most common)
# -------------------------------------------------------------------
# Join point attributes to the county that contains them
joined <- sx_join(pts, nc, join = "within")

# -------------------------------------------------------------------
# Example 2: Using pre-registered view names
# -------------------------------------------------------------------
sx_as_view(nc, "nc_counties")
sx_as_view(pts, "sample_points")

# Join using view names
joined_from_views <- sx_join("sample_points", "nc_counties", join = "within")

# -------------------------------------------------------------------
# Example 3: Create a persistent view (named output)
# -------------------------------------------------------------------
# Instead of returning sf, create a named view for later use
sx_join(pts, nc, join = "intersects", view_name = "points_with_county")

# The view can now be used in other operations
result <- sx_collect("points_with_county")

# -------------------------------------------------------------------
# Example 4: Interoperability
# -------------------------------------------------------------------
# Export as raw WKB for database import
wkb_result <- sx_join(pts, nc, output = "raw")
# }