> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/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

<CardGroup cols={2}>
  <Card title="MongoDB acessível" icon="database">
    Um banco MongoDB (self-hosted ou Atlas) que o worker strattum.ai consiga alcançar na porta configurada (padrão `27017`).
  </Card>

  <Card title="Usuário com role de leitura" icon="user-shield">
    Recomendamos um usuário dedicado com a role `read` no banco. O passo a passo está abaixo.
  </Card>
</CardGroup>

## Configuração

<Steps>
  <Step title="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.
    </Tip>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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)
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.
</Warning>

## 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

<CardGroup cols={2}>
  <Card title="Guia de desenvolvimento local" icon="terminal" href="/data-pipelines/local-development">
    Configure o ambiente local completo com Prefect, worker e Docker Compose.
  </Card>

  <Card title="Quickstart — Data Pipelines" icon="rocket" href="/data-pipelines/quickstart">
    Ative conectores via Console strattum.ai sem precisar de ambiente local.
  </Card>
</CardGroup>