Read before:
../conectores.md(state map) andfichas.md(index of sheets).
What it is#
Reads an aggregate from SIDRA (IPCA, PNAD, PIB…) by variable, period and locality and the list of IBGE municipalities, and loads into the Bronze layer.
Supported ingestion modes:
- Nós buscamos — We fetch the data from its source.
What it’s for#
Bring IBGE (SIDRA) data into your datalake and make it available to the Bronze/Silver/Gold layers, BI models and the natural language question wizard.
When to use / when not to use#
Use when you need to consolidate this source into the datalake on a scheduled basis, with isolation by workspace.
Remember that the first run with a real credential is followed by our team before the connector is fully released.
Plan and permissions#
- Plan: core product (connectors are part of all plans; the limit is the number of sources in the plan).
- Access: requires an active workspace — with overdue, suspended or canceled subscription, the execution is blocked.
- Shutdown: ingestion execution can be turned off temporarily (maintenance or incident). When that happens, the screen indicates the resource is currently unavailable.
Prerequisites#
- No credentials: the data is public.
- No credential required: the SIDRA aggregate APIs and IBGE localities APIs are public. Provide the aggregate (SIDRA table number, e.g.: 1419 IPCA), the variable (e.g.: 63 monthly variation), the periods (e.g.: -12 = last 12) and the localities (e.g.: N1[all] = Brazil, N3[all] = all states). The list of municipalities does not depend on those fields.
Credentials#
Authentication method: No credential — public data.
This connector does not require its own secrets (upload mode / no credential on the platform).
Secrets are never re-displayed and are redacted in every error/log (raw token, URL-encoded and in JSON).
Form fields#
| Campo | Rótulo | Tipo | Obrigatório | Observação |
|---|---|---|---|---|
agregado | Agregado (tabela SIDRA) | texto | sim | padrão: 1419; Número da tabela no SIDRA. Ex.: 1419 (IPCA), 6381 (PNAD — desocupação), 5938 (PIB dos municípios). |
variavel | Variável | texto | sim | padrão: 63; Código da variável dentro do agregado (ex.: 63 = IPCA variação mensal). all traz todas as variáveis. |
periodos | Períodos | texto | sim | padrão: -12; -12 = últimos 12 períodos; 202401-202412 = intervalo; all = toda a série (pode ser grande). |
localidades | Localidades | texto | sim | padrão: N1[all]; N1[all] = Brasil; N3[all] = todas as UFs; N6[3550308] = um município (código IBGE). Combine com |. |
Step by step#
- In the menu Dados → Conexões, use Nova conexão.
- Choose IBGE (SIDRA) in the catalog.
- Fill in the form fields (see the table above).
- Use Testar conexão. The result is shown separated by Network (server reach), Authentication (user and password) and Read (list tables) — each with OK, Failed, Not applicable or Not tested.
- Use Salvar conexão. Saving does NOT start any ingestion.
- On the connection card, use Montar extração (or go to Orquestração → Pipelines and use Conectar fonte). The pipeline points to the saved connection — the credential is not copied.
- In review, Publicar (agenda desligada) creates version 1 without running anything. Afterwards, Ativar agenda and Executar agora are separate actions.
Example — connection test#
Example configuration (all values are fictitious; secrets appear masked):
# Exemplo sintético (valores fictícios — não são credenciais reais)
agregado = 1419
variavel = 63
periodos = -12
localidades = N1[all]Expected result#
The Testar conexão returns the list of discovered tables/resources. After the first load, the rows appear in the Bronze layer of your workspace, ready for the pipeline.
Limits and costs#
- Pagination: hard limit per execution (default 10,000 pages / 5,000,000 rows); anti-loop guard.
- Carga SaaS: default
batchSize5.000,maxRows200.000 por recurso. - Estimated volume: ~0.02 GB/month (catalog estimate, not measurement).
- Cost: the extraction itself is not charged by the platform; the Bronze load consumes datalake processing (billable).
Security#
- Workspace scope: each client reads and writes only to their own datalake (
<prefix>_bronze/_silver/_gold); there is never leakage between workspaces. - Encrypted secrets: sensitive material is encrypted with AES-256-GCM before being stored. The external credential vault is optional and enabled per connection; without it, the encrypted value stays in the database. Changing the value here DOES NOT revoke the credential at the origin.
- Redaction: every error/log is passed through secret redaction (raw, URL-encoded and in JSON).
- Production does not mock: a path that would fall into a mock triggers the production guard (explicit failure instead of simulating success).
Common errors#
- Credential rejected (401/403) — the provider did not accept the credential: expired, revoked or lacking necessary permission. Reconnect the source (the source and its history are preserved; do not recreate the source).
- Rate limit (429) — the provider asked to wait. The extraction respects
Retry-Afterand retries; if it repeats, wait and reduce the schedule frequency. - Resource not found — check the resource identifier (account, object, report) and the granted permissions.
- Pagination cursor stuck — the extraction stops when the API cursor does not advance (anti-loop guard). If it happens in consecutive executions, open a support ticket with the connector and resource information.
- Empty records path — the response arrived without records in the expected place. Check the selected resource and filters (period, account, status) before assuming there is no data.
Troubleshooting#
- Use Testar conexão to isolate credential/network issues before scheduling.
- Monitor executions in the connector observability (error rate, p50/p95, freshness).
- A schema change at the source is signaled by schema drift (new column = info; removed column/type changed = attention).
Related#
../conectores.md— connector catalog by state../ingestao-incremental-backfill.md— full, incremental by watermark, backfill and checkpoint../pipeline-medalhao.md— Bronze/Silver/Gold layers and quality../agendamento-retry-dlq.md— scheduling, retry/backoff and DLQ../custo-limites-seguranca.md— cost, limits and workspace security
Last review: 2026-10-04. Sheet automatically generated from the product connectors catalog.