% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/read_metadata.R
\name{read_zarr_consolidated_metadata}
\alias{read_zarr_consolidated_metadata}
\title{Read consolidated metadata}
\usage{
read_zarr_consolidated_metadata(
  zarr_path,
  consolidate = c("never", "missing", "always"),
  s3_client = NULL
)
}
\arguments{
\item{zarr_path}{A character vector of length 1.  This provides the
path to a Zarr array or group of arrays. This can either be on a local file
system or on S3 storage.}

\item{consolidate}{One of \code{"never"} (default), \code{"missing"} or \code{"always"}.
This controls whether the consolidated metadata needs to be (re)generated
on the fly, in memory. If \code{"never"} then the consolidated metadata is only
read if it already exists, and \code{NULL} is returned otherwise. If \code{"missing"}
then the consolidated metadata is generated if it does not already exist.
If \code{"always"} then the consolidated metadata is always (re)generated, even
if it already exists.}

\item{s3_client}{A list representing an S3 client.  This should be produced
by \code{\link[paws.storage:s3]{paws.storage::s3()}}.}
}
\value{
A list containing the consolidated metadata, formatted as Zarr v3
consolidated metadata.
If \code{consolidate = "never"} and the consolidated metadata does not exist,
\code{NULL} is returned.
}
\description{
Read consolidated metadata
}
\details{
This is stored in the \code{.zmetadata} (Zarr v2) or \code{zarr.json} (Zarr v3) file at
the root of a Zarr store.

Note that it is not documented in the official Zarr specification, because
it is not (yet?) part of the standard.

In particular, it lists the location of all the metadata files for arrays in
the current group, so it is not necessary to crawl to discover them. It
leads to much better performance, in particular when reading arrays from S3
storage.
}
\examples{
z <- system.file("extdata", "zarr_examples", "metadata", "consolidated.zarr", package = "Rarr")
m <- read_zarr_consolidated_metadata(z)
head(m)

}
\references{
\url{https://zarr.readthedocs.io/en/latest/user-guide/consolidated_metadata.html}
}
