% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ddbs_union.R
\name{ddbs_intersection_agg}
\alias{ddbs_intersection_agg}
\title{Aggregate the intersection of geometries}
\usage{
ddbs_intersection_agg(
  x,
  by = NULL,
  conn = NULL,
  name = NULL,
  mode = NULL,
  overwrite = FALSE,
  quiet = FALSE
)
}
\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{by}{Character vector of one or more column names to group by. The
intersection is computed within each group. When \code{NULL} (default), all
geometries are intersected into a single geometry.}

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

\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{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}.}
}
\value{
Depends on the \code{mode} argument (or global preference set by \code{\link{ddbs_options}}):
\itemize{
\item \code{duckspatial} (default): A \code{duckspatial_df} (lazy spatial data frame) backed by dbplyr/DuckDB.
\item \code{sf}: An eagerly collected object in R memory, that will return the same data type as the
\code{sf} equivalent (e.g. \code{sf} or \code{units} vector).
}
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{
Computes the geometric intersection of a set of geometries — the area common
to all of them — using DuckDB's \code{ST_Intersection_Agg()} aggregate. This is the
intersection counterpart to \code{\link[=ddbs_union_agg]{ddbs_union_agg()}}.
}
\examples{
\dontrun{
## load package
library(duckspatial)

## create a connection and three overlapping polygons
conn <- ddbs_create_conn()
polys <- sf::st_as_sf(
  data.frame(grp = c("a", "a", "a")),
  geometry = sf::st_sfc(
    sf::st_polygon(list(matrix(c(0,0, 3,0, 3,3, 0,3, 0,0), ncol = 2, byrow = TRUE))),
    sf::st_polygon(list(matrix(c(1,1, 4,1, 4,4, 1,4, 1,1), ncol = 2, byrow = TRUE))),
    sf::st_polygon(list(matrix(c(2,2, 5,2, 5,5, 2,5, 2,2), ncol = 2, byrow = TRUE))),
    sf::st_polygon(list(matrix(c(3,3, 6,3, 6,6, 3,6, 3,3), ncol = 2, byrow = TRUE)))
  ),
  crs = 4326
)

## intersect all geometries into their common area
polys_inters <- ddbs_intersection_agg(polys, mode = "sf")

## intersect within groups
polys_inters_grp <- ddbs_intersection_agg(polys, by = "grp", mode = "sf")

## plot them
plot(polys["grp"], key.pos = NULL, reset = FALSE)
plot(polys_inters_grp["grp"], pal = c("red", "blue"), add = TRUE)
plot(sf::st_geometry(polys_inters), col = "black", pch = 19, cex = 2, add = TRUE)
}
}
