sidra_collect: Collect one or more planned SIDRA queries

In sidrar: An Interface to IBGE's SIDRA API

Collect one or more planned SIDRA queries

Description

Executes queries sequentially, checks that every batch has the same column names and types, and combines the rows without sorting or deduplicating them. Parallel requests are intentionally not used.

Usage

sidra_collect(
  x,
  value_type = NULL,
  provenance = FALSE,
  batch_size = NULL,
  checkpoint = NULL,
  resume = TRUE
)

Arguments

x	A sidra_query(), sidra_plan(), sidra_split() result, or a non-empty list of sidra_query objects; also accepts a SIDRA values URL.
value_type	Optional value representation overriding the preference stored in each query: "numeric", "character", or "both".
provenance	Logical. Attach URLs, access time, package version, and batch count as a sidrar_provenance attribute. URLs record the endpoint that supplied each batch; requested_urls is also included when a Cloudflare challenge required the official aggregate API fallback.
batch_size	Optional positive integer. Split each input query by period into batches of at most this many periods before downloading. This is not a bound on the number of values: a single period can still exceed the service limit. The default NULL preserves existing batches.
checkpoint	Optional path to a dedicated local directory. Successful batches are saved with checksums and a frozen query inventory. No values are saved to disk by default. Only use checkpoints you trust.
resume	Logical. Reuse verified completed batches in checkpoint (default TRUE). An existing checkpoint must match the original queries, value representation, batch size, and package version. FALSE requires a new directory; existing files are never silently cleared.

Details

Checkpoints are separate from the metadata cache. They preserve successful responses, including their original access times; they are not refreshed automatically and can span upstream revisions. Use a new directory for a fresh collection. Relative periods are resolved once and reused on resume, even if the current catalog has changed. Corruption, incompatible schemas, mismatched settings, and concurrent writers fail explicitly. An interrupted process may leave a .sidrar-lock directory; remove that lock only after confirming that no collector is still running. Results are still combined in memory; checkpoints are not an out-of-core database. Row order is not a key: join different extracts by identifiers. Warnings from completed batches are saved and signaled again on resume, so reuse does not hide incomplete-coverage diagnostics.

Value

A base data.frame(). When provenance = TRUE, its sidrar_provenance attribute can be read with sidra_provenance().

See Also

sidra_query(), sidra_split(), sidra_provenance()

Examples

## Not run: 
query <- sidra_query(
  7060,
  variable = 63,
  period = as.character(202401:202406),
  geo = "Brazil",
  classific = "c315",
  category = list(7169)
)
sidra_collect(sidra_split(query, "period", size = 3))

## End(Not run)

sidrar documentation built on Sept. 28, 2026, 5:07 p.m.