% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ddbs_predicates.R
\name{ddbs_predicate}
\alias{ddbs_predicate}
\alias{ddbs_intersects}
\alias{ddbs_covers}
\alias{ddbs_touches}
\alias{ddbs_is_within_distance}
\alias{ddbs_disjoint}
\alias{ddbs_within}
\alias{ddbs_contains}
\alias{ddbs_overlaps}
\alias{ddbs_crosses}
\alias{ddbs_equals}
\alias{ddbs_covered_by}
\alias{ddbs_intersects_extent}
\alias{ddbs_contains_properly}
\alias{ddbs_within_properly}
\title{Evaluate spatial predicates between geometries}
\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{
\item{x}{Input spatial data. Can be:
\itemize{
\item A \code{duckspatial_df} object (lazy spatial data frame via dbplyr)
\item An \code{sf} object
\item A \code{tbl_lazy} from dbplyr
\item A character string naming a table/view in \code{conn}
}
Data is returned from this object.}

\item{y}{Input spatial data. Can be:
\itemize{
\item A \code{duckspatial_df} object (lazy spatial data frame via dbplyr)
\item An \code{sf} object
\item A \code{tbl_lazy} from dbplyr
\item A character string naming a table/view in \code{conn}
}}

\item{predicate}{A geometry predicate function. Defaults to \code{intersects},
a wrapper of \code{ST_Intersects}. See details for other options.}

\item{conn}{A connection object to a DuckDB database. If \code{NULL}, the function
runs on a temporary DuckDB database.}

\item{conn_x}{A \code{DBIConnection} object to a DuckDB database for the input \code{x}.
If \code{NULL} (default), it is resolved from \code{conn} or extracted from \code{x}.}

\item{conn_y}{A \code{DBIConnection} object to a DuckDB database for the input \code{y}.
If \code{NULL} (default), it is resolved from \code{conn} or extracted from \code{y}.}

\item{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 \code{NULL} (the default), the function returns the result as an
\code{sf} object}

\item{id_x}{Character; optional name of the column in \code{x} whose values will
be used to name the list elements. If \code{NULL}, integer row numbers of \code{x} are used.}

\item{id_y}{Character; optional name of the column in \code{y} whose values will
replace the integer indices returned in each element of the list.}

\item{sparse}{A logical value. If \code{TRUE}, it returns a sparse table/list. If \code{FALSE},
it returns a wide table/matrix.}

\item{distance}{a numeric value specifying the distance for ST_DWithin. Units correspond to
the coordinate system of the geometry (e.g. degrees or meters)}

\item{mode}{Character. Controls the return type. Options:
\itemize{
\item \code{"duckspatial"} (default): Lazy spatial data frame backed by dbplyr/DuckDB
\item \code{"sf"}: Eagerly collected sf object (uses memory)
}
Can be set globally via \code{\link{ddbs_options}(mode = "...")} or
per-function via this argument. Per-function overrides global setting.}

\item{overwrite}{Boolean. whether to overwrite the existing table if it exists. Defaults
to \code{FALSE}. This argument is ignored when \code{name} is \code{NULL}.}

\item{quiet}{A logical value. If \code{TRUE}, suppresses any informational messages.
Defaults to \code{FALSE}.}

\item{...}{Passed to \link{ddbs_predicate}}
}
\value{
Depends on the \code{mode} argument (or global preference set by \code{\link{ddbs_options}}):
\itemize{
\item \code{duckspatial} (default): A \code{tbl_duckdb_connection} (lazy data frame) backed by dbplyr/DuckDB.
\item \code{sf}: An eagerly collected list.
}
When \code{name} is provided, the result is also written as a table or view in DuckDB and the function returns \code{TRUE} (invisibly).
}
\description{
Determines which geometries in one dataset satisfy a specified spatial
relationship with geometries in another dataset, such as intersection,
containment, or touching.
}
\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 \code{x} and \code{y} using the specified predicate.
\subsection{Available Predicates}{
\itemize{
\item \strong{intersects}: Geometries share at least one point
\item \strong{covers}: Geometry \code{x} completely covers geometry \code{y}
\item \strong{touches}: Geometries share a boundary but interiors do not intersect
\item \strong{disjoint}: Geometries have no points in common
\item \strong{within}: Geometry \code{x} is completely inside geometry \code{y}
\item \strong{dwithin}: Geometry \code{x} is completely within a distance of geometry \code{y}
\item \strong{contains}: Geometry \code{x} completely contains geometry \code{y}
\item \strong{overlaps}: Geometries share some but not all points
\item \strong{crosses}: Geometries have some interior points in common
\item \strong{equals}: Geometries are spatially equal
\item \strong{covered_by}: Geometry \code{x} is completely covered by geometry \code{y}
\item \strong{intersects_extent}: Bounding boxes of geometries intersect (faster but less precise)
\item \strong{contains_properly}: Geometry \code{x} contains geometry \code{y} without boundary contact
\item \strong{within_properly}: Geometry \code{x} is within geometry \code{y} without boundary contact
}

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

\code{id_x} or \code{id_y} may be used to replace the default integer indices with the
values of an identifier column in \code{x} or \code{y}, respectively.
}
}
\examples{
\dontrun{
## 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")
}
}
