ddbs_predicate: Evaluate spatial predicates between geometries

In duckspatial: R Interface to 'DuckDB' Database with Spatial Extension

Evaluate spatial predicates between geometries

Description

Determines which geometries in one dataset satisfy a specified spatial relationship with geometries in another dataset, such as intersection, containment, or touching.

Usage

ddbs_predicate(
  x,
  y,
  predicate = "intersects",
  conn = NULL,
  conn_x = NULL,
  conn_y = NULL,
  name = NULL,
  id_x = NULL,
  id_y = NULL,
  sparse = TRUE,
  distance = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = TRUE
)

ddbs_intersects(x, y, ...)

ddbs_covers(x, y, ...)

ddbs_touches(x, y, ...)

ddbs_is_within_distance(x, y, distance = NULL, ...)

ddbs_disjoint(x, y, ...)

ddbs_within(x, y, ...)

ddbs_contains(x, y, ...)

ddbs_overlaps(x, y, ...)

ddbs_crosses(x, y, ...)

ddbs_equals(x, y, ...)

ddbs_covered_by(x, y, ...)

ddbs_intersects_extent(x, y, ...)

ddbs_contains_properly(x, y, ...)

ddbs_within_properly(x, y, ...)

Arguments

x	Input spatial data. Can be: A duckspatial_df object (lazy spatial data frame via dbplyr) An sf object A tbl_lazy from dbplyr A character string naming a table/view in conn Data is returned from this object.
y	Input spatial data. Can be: A duckspatial_df object (lazy spatial data frame via dbplyr) An sf object A tbl_lazy from dbplyr A character string naming a table/view in conn
predicate	A geometry predicate function. Defaults to intersects, a wrapper of ST_Intersects. See details for other options.
conn	A connection object to a DuckDB database. If NULL, the function runs on a temporary DuckDB database.
conn_x	A DBIConnection object to a DuckDB database for the input x. If NULL (default), it is resolved from conn or extracted from x.
conn_y	A DBIConnection object to a DuckDB database for the input y. If NULL (default), it is resolved from conn or extracted from y.
name	A character string of length one specifying the name of the table, or a character string of length two specifying the schema and table names. If NULL (the default), the function returns the result as an sf object
id_x	Character; optional name of the column in x whose values will be used to name the list elements. If NULL, integer row numbers of x are used.
id_y	Character; optional name of the column in y whose values will replace the integer indices returned in each element of the list.
sparse	A logical value. If TRUE, it returns a sparse table/list. If FALSE, it returns a wide table/matrix.
distance	a numeric value specifying the distance for ST_DWithin. Units correspond to the coordinate system of the geometry (e.g. degrees or meters)
mode	Character. Controls the return type. Options: "duckspatial" (default): Lazy spatial data frame backed by dbplyr/DuckDB "sf": Eagerly collected sf object (uses memory) Can be set globally via ddbs_options(mode = "...") or per-function via this argument. Per-function overrides global setting.
overwrite	Boolean. whether to overwrite the existing table if it exists. Defaults to FALSE. This argument is ignored when name is NULL.
quiet	A logical value. If TRUE, suppresses any informational messages. Defaults to FALSE.
...	Passed to ddbs_predicate

Details

This function provides a unified interface to all spatial predicate operations in DuckDB's spatial extension. It performs pairwise comparisons between all geometries in x and y using the specified predicate.

Available Predicates

• intersects: Geometries share at least one point

• covers: Geometry x completely covers geometry y

• touches: Geometries share a boundary but interiors do not intersect

• disjoint: Geometries have no points in common

• within: Geometry x is completely inside geometry y

• dwithin: Geometry x is completely within a distance of geometry y

• contains: Geometry x completely contains geometry y

• overlaps: Geometries share some but not all points

• crosses: Geometries have some interior points in common

• equals: Geometries are spatially equal

• covered_by: Geometry x is completely covered by geometry y

• intersects_extent: Bounding boxes of geometries intersect (faster but less precise)

• contains_properly: Geometry x contains geometry y without boundary contact

• within_properly: Geometry x is within geometry y without boundary contact

If x or y are not DuckDB tables, they are automatically copied into a temporary in-memory DuckDB database (unless a connection is supplied via conn).

id_x or id_y may be used to replace the default integer indices with the values of an identifier column in x or y, respectively.

Value

Depends on the mode argument (or global preference set by ddbs_options):

• duckspatial (default): A tbl_duckdb_connection (lazy data frame) backed by dbplyr/DuckDB.

• sf: An eagerly collected list.

When name is provided, the result is also written as a table or view in DuckDB and the function returns TRUE (invisibly).

Examples

## Not run: 
## Load packages
library(duckspatial)
library(dplyr)

## create in-memory DuckDB database
conn <- ddbs_create_conn(dbdir = "memory")

## read countries data, and rivers
countries_ddbs <- ddbs_open_dataset(
  system.file("spatial/countries.geojson", 
  package = "duckspatial")
) |>
  filter(CNTR_ID %in% c("PT", "ES", "FR", "IT"))

rivers_ddbs <- ddbs_open_dataset(
  system.file("spatial/rivers.geojson", 
  package = "duckspatial")
) |>
  ddbs_transform(ddbs_crs(countries_ddbs))

## Store in DuckDB
ddbs_write_vector(conn, countries_ddbs, "countries")
ddbs_write_vector(conn, rivers_ddbs, "rivers")

## Example 1: Check which rivers intersect each country
ddbs_predicate(countries_ddbs, rivers_ddbs, predicate = "intersects")
ddbs_intersects(countries_ddbs, rivers_ddbs)

## Example 2: Find neighboring countries
ddbs_predicate(
  countries_ddbs, 
  countries_ddbs, 
  predicate = "touches",
  id_x = "NAME_ENGL", 
  id_y = "NAME_ENGL"
)

ddbs_touches(
  countries_ddbs, 
  countries_ddbs, 
  id_x = "NAME_ENGL", 
  id_y = "NAME_ENGL"
)

## Example 3: Find rivers that don't intersect countries
ddbs_predicate(
  countries_ddbs, 
  rivers_ddbs, 
  predicate = "disjoint",
  id_x = "NAME_ENGL", 
  id_y = "RIVER_NAME"
)

## Example 4: Use table names inside duckdb
ddbs_predicate("countries", "rivers", predicate = "within", conn, id_x = "NAME_ENGL")
ddbs_within("countries", "rivers", conn,  id_x = "NAME_ENGL")

## End(Not run)

duckspatial documentation built on June 22, 2026, 9:08 a.m.