% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/spatial.R
\name{spatial_dissolve}
\alias{spatial_dissolve}
\title{Dissolve geometries by group}
\usage{
spatial_dissolve(
  x,
  by = NULL,
  ...,
  geom = "geometry",
  crs = NA,
  .fun = NULL,
  flush_rows = NULL
)
}
\arguments{
\item{x}{A \code{vectra_node} (from \code{\link[=tbl]{tbl()}}, \code{\link[=tbl_tiff]{tbl_tiff()}}, any verb chain, ...).
It is consumed by the stream.}

\item{by}{Character vector of attribute columns to dissolve within: one
output feature per distinct combination of their values. \code{NULL} (default)
dissolves the entire layer into a single feature.}

\item{...}{Further arguments passed to \code{\link[sf:st_union]{sf::st_union()}} (e.g.
\code{is_coverage = TRUE}).}

\item{geom}{Name of the input geometry column holding hex-WKB or WKT strings.
Default \code{"geometry"}. Ignored when \code{coords} is given.}

\item{crs}{Coordinate reference system of the input geometry, in any form
\code{\link[sf:st_crs]{sf::st_crs()}} accepts (EPSG integer, WKT, proj string). Defaults to the
CRS the upstream node carries, or unknown.}

\item{.fun}{Optional named list of attribute summaries. Each element is a
function taking the group's data.frame and returning a length-1 value; the
list name becomes the output column (e.g.
\code{.fun = list(total = function(d) sum(d$pop))}). Default \code{NULL} keeps only
the \code{by} columns and the dissolved geometry.}

\item{flush_rows}{Transformed rows buffered before a spill flush. Larger
values mean fewer, bigger temporary files. Defaults to
\code{getOption("vectra.spatial_flush", 5e5)}.}
}
\value{
A \code{vectra_node} of one row per group -- the \code{by} columns, any \code{.fun}
summaries, and the dissolved geometry -- backed by temporary \code{.vtr} spills
removed when the node is garbage-collected, carrying the input CRS for
\code{\link[=collect_sf]{collect_sf()}}.
}
\description{
Unions the geometries within each \code{by} group into a single feature (the GIS
"Dissolve" tool), optionally summarising attributes. Unlike the streamed
per-batch verbs, dissolve needs every geometry of a group together to union
them, so it rides the \strong{partition tier}: \code{x} is spilled once and routed into
one disjoint shard per group in a single bounded pass, then each shard is read
in and unioned with \pkg{sf}. Peak memory is the routing budget during the
pass, then one group's geometries while it is unioned -- partition the input
on a key whose groups fit in memory. With no \code{by}, the whole layer dissolves
into one feature.
}
\details{
Geometry travels through the engine as hex-encoded WKB in a string column and
the CRS is carried on the returned node; use \code{\link[=collect_sf]{collect_sf()}} to materialize.
On projected or unprojected planar data each group is unioned natively on the
GEOS C API straight off the hex-WKB column; geographic coordinates with
spherical geometry on (\code{sf::sf_use_s2()}), or any extra \code{\link[sf:st_union]{sf::st_union()}}
arguments (e.g. \code{is_coverage = TRUE}), union through \pkg{sf} instead. The
\pkg{sf} package is an optional dependency (Suggests).
}
\examples{
\dontshow{if (requireNamespace("sf", quietly = TRUE)) withAutoprint(\{ # examplesIf}
nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
nc$band <- nc$SID74 > 5            # an attribute to dissolve within
f <- tempfile(fileext = ".vtr")
write_vtr(data.frame(
  band = nc$band, BIR74 = nc$BIR74,
  geometry = sf::st_as_binary(sf::st_geometry(nc), hex = TRUE)
), f)

# Merge the counties into two features by `band`, summing births.
merged <- tbl(f) |>
  spatial_dissolve(by = "band", crs = sf::st_crs(nc),
                   .fun = list(births = function(d) sum(d$BIR74)))
collect_sf(merged)
unlink(f)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=spatial_overlay]{spatial_overlay()}} to split overlaps apart rather than merge them,
\code{\link[=offload]{offload()}} for the partition tier this rides on, \code{\link[=collect_sf]{collect_sf()}}.
}
