Skip to contents

Performs spatial filter of two geometries using SedonaDB

Source: R/sx_filter.R
sx_filter.Rd

Filters an sf object spatially based on its relationship with another sf object or geometry. All calculations are performed in SedonaDB for efficiency. Supports lazy evaluation returning sedonadb_dataframe objects.

Usage

sx_filter(
  x,
  y,
  predicate = "intersects",
  distance = NULL,
  output = NULL,
  view_name = NULL,
  verbosity = NULL,
  use_s2 = NULL,
  ...
)

Arguments

x

A sedonadb_dataframe, sf object, or view name (character) in SedonaDB representing features to filter.

y

A sedonadb_dataframe, sf object, or view name (character) in SedonaDB representing the filtering geometry.

predicate

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".

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.

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.

...

Additional arguments passed to methods.

Value

An sf object or sedonadb_dataframe (depending on output).

Examples

# \donttest{
library(sf)
nc <- st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
box <- st_bbox(nc[1:10, ]) |> st_as_sfc() |> st_as_sf()

# -------------------------------------------------------------------
# Example 1: Using sf objects (most common)
# -------------------------------------------------------------------
# Default lazy return
lazy_result <- sx_filter(nc, box, predicate = "intersects")

# Materialize to sf
sf_result <- sx_collect(lazy_result)

# Or request sf directly
sf_result <- sx_filter(nc, box, output = "sf")

# -------------------------------------------------------------------
# Example 2: Using sedonadb_dataframe (chain lazy operations)
# -------------------------------------------------------------------
# First filter returns lazy result
step1 <- sx_filter(nc, box, predicate = "intersects", output = "lazy")

# Chain with another operation (filter by a different geometry)
box2 <- st_bbox(nc[20:25, ]) |> st_as_sfc() |> st_as_sf()
step2 <- sx_filter(step1, box2, predicate = "intersects", output = "lazy")

# Collect final result
final <- sx_collect(step2)

# -------------------------------------------------------------------
# Example 3: Using pre-registered view names
# -------------------------------------------------------------------
sx_as_view(nc, "nc_counties")
sx_as_view(box, "filter_box")

# Filter using view names
result <- sx_filter("nc_counties", "filter_box", output = "sf")

# -------------------------------------------------------------------
# Example 4: Different predicates
# -------------------------------------------------------------------
# Filter with "within" predicate
within_result <- sx_filter(nc, box, predicate = "within", output = "sf")

# -------------------------------------------------------------------
# Example 5: Interoperability Outputs
# -------------------------------------------------------------------
# Export as geoarrow for Arrow/Parquet workflows
geoarrow_result <- sx_filter(nc, box, output = "geoarrow")

# Export as raw WKB for DuckDB/PostGIS import
raw_result <- sx_filter(nc, box, output = "raw")
# }