> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB

> Configure o conector MongoDB para ingerir coleções de bancos NoSQL na plataforma strattum.ai.

O conector MongoDB ingere coleções de bancos MongoDB na infraestrutura strattum.ai. Você seleciona quais coleções sincronizar, cada uma em modo incremental ou full refresh, e os documentos aparecem no Data Catalog com o schema inferido por amostragem.

## Capacidades

* Sincroniza coleções específicas de um ou mais bancos.
* Carga incremental por campo de cursor (`_id` ou um campo de data) ou full refresh a cada ciclo.
* Inferência automática do schema a partir de uma amostra de 100 documentos por coleção.
* Conexão via `mongodb://` ou `mongodb+srv://` (clusters Atlas).

## Objetos suportados

O conector trabalha sobre as coleções que você seleciona. Cada coleção vira um recurso no formato `{database}__{collection}`.

| Objeto | O que vem |
| - | - |
| Coleção (modo incremental) | Apenas documentos novos ou alterados desde o último ciclo, usando o campo de cursor definido |
| Coleção (modo full refresh) | A coleção inteira, recarregada a cada ciclo |

## Pré-requisitos

> **MongoDB acessível**
>
> Um banco MongoDB (self-hosted ou Atlas) que o worker strattum.ai consiga alcançar na porta configurada (padrão `27017`).

> **Usuário com role de leitura**
>
> Recomendamos um usuário dedicado com a role `read` no banco. O passo a passo está abaixo.

## Configuração

**1. Crie um usuário read-only**

Conectado ao MongoDB com um usuário administrador, execute:

```javascript theme={null}
use admin
db.createUser({
  user: "strattum_reader",
  pwd: "senha_segura",
  roles: [{ role: "read", db: "nome_do_banco" }]
})
```

> [!TIP]
>
> Para ler de vários bancos, adicione uma entrada `{ role: "read", db: "..." }` por banco.

**2. Libere o acesso de rede**

Garanta que o worker strattum.ai alcança o banco. Em Atlas, adicione o IP ou o CIDR do ambiente strattum.ai à lista de IPs permitidos do cluster. Self-hosted, libere a porta `27017` no firewall.

**3. Adicione o conector no Console**

No menu lateral do Console, clique em **Conectores → + Nova Conexão** e selecione **MongoDB**. Preencha os campos:

* **Nome do Conector** — identificador na lista de conectores (Obrigatório)
* **URI de conexão** — string `mongodb://user:pass@host:27017/...` ou `mongodb+srv://...` (Obrigatório)
* **Nome do banco** — banco de onde as coleções serão lidas (Obrigatório)

**4. Teste e salve**

Clique em **Testar Conexão** para validar a URI e, em seguida, em **Salvar Conector**. Selecione as coleções e o modo de carga de cada uma.

## Autenticação e escopos

A autenticação é pela URI de conexão, que carrega usuário e senha. O acesso é controlado pelas roles do MongoDB — não há escopos de API.

| Role | Para que serve |
| - | - |
| `read` no banco a sincronizar | Ler documentos e listar coleções durante a extração |

> [!WARNING]
>
> A plataforma nunca escreve na fonte. Não conceda `readWrite` nem roles administrativas ao usuário do conector.

## Frequência de sync

O conector sincroniza **a cada 1 hora**. A primeira execução após a ativação roda como sample sync (amostra) e, ao concluir, o ciclo completo passa a rodar no schedule padrão.

## Limitações conhecidas

* O modo incremental exige um campo de cursor comparável (`_id` ObjectId ou um campo de data). Sem ele, use full refresh.
* Documentos deletados na origem não são removidos automaticamente em modo incremental.
* O schema é inferido de uma amostra de 100 documentos; campos raros que não apareçam na amostra podem não ser detectados no primeiro ciclo.
* Editar a conexão substitui as credenciais por completo; não há atualização parcial.

## Troubleshooting

| Sintoma | Causa provável | O que fazer |
| - | - | - |
| `Unrecognised MongoDB URI scheme` | URI não começa com `mongodb://` ou `mongodb+srv://` | Corrija o esquema da URI de conexão |
| `Authentication failed` | Usuário ou senha incorretos, ou role ausente | Revise as credenciais na URI e a role `read` do usuário |
| `connection timed out` | IP não liberado no Atlas ou firewall | Adicione o IP do worker strattum.ai à lista de IPs permitidos |
| Campo esperado ausente no schema | Não apareceu na amostra de 100 documentos | Aguarde o próximo ciclo ou verifique a consistência dos documentos |

## Próximos passos

> **[Guia de desenvolvimento local](https://docs.strattum.ai/data-pipelines/local-development.md)**
>
> Configure o ambiente local completo com Prefect, worker e Docker Compose.

> **[Quickstart — Data Pipelines](https://docs.strattum.ai/data-pipelines/quickstart)**
>
> Ative conectores via Console strattum.ai sem precisar de ambiente local.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.