> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/integracao/mongodb.md).

# MongoDB

## 🍃 MongoDB

O módulo **MongoDB** permite consultar, inserir ou atualizar dados em um banco de dados MongoDB, sem sair do fluxo.

<figure><img src="/files/LpYbcwz2hES2kpsjURmc" alt=""><figcaption><p>Imagem 1 - Visão geral do módulo MongoDB na área de trabalho do fluxo no Hyperflow Integrações.</p></figcaption></figure>

***

### 🧭 Como acessar

1. No menu lateral, clique em **Gerenciamento de aplicativos**.
2. Em seguida, clique em **Fluxos**.
3. Abra ou crie um fluxo e acesse a área de trabalho do fluxo.
4. No painel de módulos, localize a categoria **Integração** (identificada pela cor azul).
5. Arraste o módulo **MongoDB** para a área de trabalho do fluxo.

<figure><img src="/files/P4PwDtRqmHS5uhJ5db0R" alt=""><figcaption><p>Imagem 2 - Painel de módulos com a categoria Integração expandida e o módulo MongoDB visível.</p></figcaption></figure>

{% hint style="warning" %}
**Antes de usar este módulo:** é necessário ter uma integração do tipo **MongoDB** já cadastrada em **Integrações**, com a string de conexão e o nome do banco de dados.
{% endhint %}

***

### 🔍 Conhecendo o módulo

Ao clicar duas vezes no módulo na área de trabalho do fluxo, um painel de configuração é aberto na lateral da tela.

<figure><img src="/files/JhLQ1HVmNS8Iu2anY181" alt=""><figcaption><p>Imagem 3 - Painel de configuração do módulo MongoDB aberto.</p></figcaption></figure>

***

#### 🔌 Integração

No campo **Integração**, selecione a credencial do MongoDB já cadastrada.

***

#### 📝 Body

No campo **Body**, escreva, em formato JSON, a operação que deseja realizar no banco de dados. Você pode usar variáveis do fluxo dentro do JSON.

| Campo        | O que preencher                                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `operation`  | A operação a realizar: `find`, `aggregate`, `insert`, `update`, `delete`, `deleteMany`, `findOneAndUpdate` ou `findOneAndReplace`. |
| `collection` | O nome da coleção (tabela) do banco de dados.                                                                                      |
| `query`      | O filtro (para consultas/exclusões) ou os estágios (para `aggregate`).                                                             |
| `options`    | Opções adicionais de consulta, como `limit`, `skip`, `sort` e `projection` (usadas apenas em `find`).                              |
| `fields`     | Lista de nomes de campos (separados por vírgula) a serem gravados, usada nas operações de inserção e atualização.                  |
| `updateKey`  | Nome do campo usado para identificar qual registro atualizar, nas operações de atualização.                                        |
| `upsert`     | Se `true`, cria um novo registro quando nenhum for encontrado para atualizar.                                                      |

{% hint style="warning" %}
A **coleção precisa já existir** no banco de dados antes de usar este módulo — inclusive para inserir dados pela primeira vez. Crie a coleção diretamente no banco antes de configurar o fluxo.
{% endhint %}

{% hint style="danger" %}
**Nunca insira diretamente, sem nenhuma validação, um texto digitado pelo cliente dentro do campo Body.** Isso pode permitir que alguém manipule a operação para ler, alterar ou apagar dados que não deveriam ser acessados no banco de dados. Sempre que possível, valide ou trate o valor da variável antes de usá-lo no campo Body.
{% endhint %}

**Exemplo — consultar dados:**

```json
{
  "operation": "find",
  "collection": "clientes",
  "query": { "telefone": "{{input.phone}}" }
}
```

**Exemplo — inserir um novo registro:**

```json
{
  "operation": "insert",
  "collection": "pedidos",
  "fields": "nome,telefone,produto"
}
```

{% hint style="warning" %}
Nas operações de inserção e atualização, o campo `fields` é essencial: ele define quais informações, vindas do módulo anterior no fluxo, serão de fato gravadas. Se `fields` não for informado, o registro é salvo vazio.
{% endhint %}

***

#### 🔀 Saídas do módulo

O módulo tem duas saídas:

* **Sucesso** — a operação foi concluída, com o resultado disponível para os próximos módulos do fluxo.
* **Erro** — não foi possível concluir a operação (ex.: coleção inexistente, erro de conexão).

<figure><img src="/files/SNr3Oe8V4h4bWfkrNdZk" alt=""><figcaption><p>Imagem 4 - Módulo na área de trabalho do fluxo mostrando as saídas Sucesso e Erro.</p></figcaption></figure>

***

### 💡 Caso de uso

**Cenário:** uma empresa quer consultar o histórico de compras de um cliente, armazenado em um banco MongoDB próprio.

**Configuração:**

1. Adicione o módulo **MongoDB** ao fluxo.
2. No campo **Integração**, selecione a credencial já cadastrada.
3. No campo **Body**, escreva: `{ "operation": "find", "collection": "compras", "query": { "telefone": "{{input.phone}}" } }`.
4. Conecte a saída **Sucesso** a um módulo que use os dados retornados na conversa.

**Resultado:** o fluxo consulta automaticamente o histórico de compras do cliente pelo telefone informado.

***

### 📌 Dicas úteis

* Sempre teste a consulta com dados reais antes de publicar o fluxo em produção.
* Use o campo `fields` com atenção nas operações de inserção e atualização, para garantir que os dados corretos sejam gravados.
* Evite operações que possam afetar muitos registros de uma vez sem um filtro (`query`) bem definido.
* Sempre conecte a saída **Erro** a algum tratamento, já que operações de banco de dados podem falhar por diversos motivos.

***

### 📝 Resumo

* O módulo **MongoDB** consulta, insere ou atualiza dados em um banco de dados MongoDB.
* A operação é definida em formato JSON no campo **Body**, incluindo a coleção, o filtro e demais opções.
* A coleção usada precisa já existir no banco de dados.
* O módulo tem uma saída de **Sucesso**, com o resultado disponível para o fluxo, e uma saída de **Erro**.