% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/offload.R
\name{group_map}
\alias{group_map}
\alias{group_map.vectra_partition}
\alias{group_modify}
\alias{group_modify.vectra_partition}
\title{Apply a function to each shard of a partition}
\usage{
group_map(.data, .f, ...)

\method{group_map}{vectra_partition}(.data, .f, ...)

group_modify(.data, .f, ...)

\method{group_modify}{vectra_partition}(.data, .f, ...)
}
\arguments{
\item{.data}{A \code{vectra_partition} from \code{\link[=offload]{offload()}} with a \code{by} key.}

\item{.f}{A function applied to each shard. It receives the shard as a
data.frame and the shard key (a string) as its first two arguments; any
further arguments in \code{...} follow. A purrr-style formula such as
\code{~ lm(y ~ x, .x)} also works, with \code{.x} the shard data and \code{.y} the key.
For \code{group_modify()}, \code{.f} must return a data.frame.}

\item{...}{Additional arguments passed on to \code{.f}.}
}
\value{
\code{group_map()} returns a named list with one element per shard.
\code{group_modify()} returns a single data.frame: the per-shard results
row-bound, with the shard key restored as a column when \code{.f} dropped it.
}
\description{
Run a function once per shard of a partition (\code{offload(x, by = ...)}) and
gather the results. Each shard is read into memory as a data.frame and passed
to \code{.f} together with its key, so a model that couples rows within a group
becomes a set of independent per-shard fits. This is the per-group
counterpart to \code{\link[=collect_chunked]{collect_chunked()}}, which instead merges every shard into a
single accumulator.
}
\details{
\code{group_map()} returns a named list, one element per shard keyed by the shard
key, and places no constraint on what \code{.f} returns. Use it for per-group
results that do not rebind into a table, such as fitted models.

\code{group_modify()} expects \code{.f} to return a data.frame for each shard and binds
those frames into one. When a shard's result does not already carry the
partition key column, the key is added as a leading column (named after the
partition's \code{by}), so every row records the shard it came from. Use it for
per-group summaries that recombine into a single table.

Each shard is materialized in full before \code{.f} sees it, so partition the
query on a key whose groups fit in memory. For a reduction that stays bounded
without ever holding a whole group, fold the partition with
\code{\link[=collect_chunked]{collect_chunked()}} instead.
}
\examples{
f <- tempfile(fileext = ".vtr")
write_vtr(mtcars, f)
p <- offload(tbl(f), by = "cyl")

# One fit per shard, returned as a named list keyed by cyl.
fits <- group_map(p, function(d, cyl) coef(lm(mpg ~ wt, data = d)))
fits

# Per-shard summaries recombined into one table, key restored as a column.
group_modify(p, function(d, cyl)
  data.frame(n = nrow(d), mean_mpg = mean(d$mpg)))
unlink(f)

}
\seealso{
\code{\link[=offload]{offload()}} to build a partition, and \code{\link[=collect_chunked]{collect_chunked()}} for the
partitioned monoidal reduce.
}
