> For the complete documentation index, see [llms.txt](https://docs.digibee.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/structured-data/object-store.md).

# Object Store

Descubra mais sobre o conector Object Store e saiba como utilizá-lo na Digibee Integration Platform.

O **Object Store** realiza operações para armazenar qualquer documento no Object Store da Digibee. É uma maneira rápida e fácil de salvar informações úteis do tipo JSON, que possui operações para auxiliar em diversos usos durante a criação de um pipeline.

{% hint style="info" %}
O Object Store não vem habilitado por padrão em novos realms. Solicite a habilitação ao [suporte Digibee](/documentation/troubleshooting/pt-br/help-and-faq/support.md).
{% endhint %}

## **Parâmetros**

A tabela abaixo lista todos os parâmetros de configuração do conector. Os parâmetros que suportam [expressões Double Braces](/documentation/connectors-and-triggers/pt-br/double-braces/overview.md) são marcados com ✅ na coluna **Suporta DB**.

{% tabs %}
{% tab title="General" %}

<table><thead><tr><th width="112">Parâmetro</th><th width="231.20001220703125">Descrição</th><th width="83.199951171875">Tipo</th><th width="80.800048828125">Suporta DB</th><th width="100">Valor padrão</th><th width="124.7999267578125">Visível quando</th></tr></thead><tbody><tr><td><strong>Account</strong></td><td>Conta a ser usada pelo conector. Esse item não pode ser alterado.</td><td>String</td><td>❌</td><td><code>Digibee Object Store Account</code></td><td>—</td></tr><tr><td><strong>Operation</strong></td><td>Operação a ser executada dentro do Object Store: Find by Object ID, Find By Query, Insert, Aggregate, Update By Object ID, Update By Query, Delete By Object ID, Delete By Query, Create Index, List Indexes e Drop Index.</td><td>String</td><td>❌</td><td><code>Find by Object ID</code></td><td>—</td></tr><tr><td><strong>Object Store Name</strong></td><td>Nome da coleção a ser usada para gravar ou ler informações. Se ela não existir, o conector a cria automaticamente.</td><td>String</td><td>❌</td><td><code>sales</code></td><td>—</td></tr><tr><td><strong>Expire After Seconds</strong></td><td>Define o número de segundos após o qual um documento do Object Store expira.</td><td>Integer</td><td>✅</td><td><code>0</code></td><td><strong>Operation</strong> é <strong>Create Index</strong></td></tr><tr><td><strong>Object ID</strong></td><td>Identificador do objeto a ser armazenado ou buscado. Pode ser um número único ou um UUID.</td><td>String</td><td>✅</td><td><code>1</code></td><td><strong>Operation</strong> é <strong>Find by Object ID</strong>, <strong>Insert</strong>, <strong>Update by Object ID</strong> ou <strong>Delete by Object ID</strong></td></tr><tr><td><strong>Query</strong></td><td>Objeto JSON que define a query.</td><td>String</td><td>✅</td><td><code>N/A</code></td><td><strong>Operation</strong> é <strong>Find by Query</strong>, <strong>Aggregate</strong>, <strong>Update by Query</strong>, <strong>Delete by Query</strong>, <strong>Create Index</strong> ou <strong>Drop Index</strong></td></tr><tr><td><strong>Document</strong></td><td>Campo JSON com os dados do objeto ou as instruções de atualização para a operação.</td><td>String</td><td>✅</td><td><code>N/A</code></td><td><strong>Operation</strong> é <strong>Insert</strong>, <strong>Update by Object ID</strong> ou <strong>Update by Query</strong></td></tr><tr><td><strong>Limit</strong></td><td>Número máximo de objetos a serem retornados em uma busca.</td><td>Integer</td><td>✅</td><td><code>0</code></td><td><strong>Operation</strong> é <strong>Find by Object ID</strong> ou <strong>Find by Query</strong></td></tr><tr><td><strong>Skip</strong></td><td>Número de objetos a serem ignorados antes que a query retorne os resultados. Use esse parâmetro junto com <strong>Limit</strong> para habilitar a paginação.</td><td>Integer</td><td>✅</td><td><code>0</code></td><td><strong>Operation</strong> é <strong>Find by Object ID</strong> ou <strong>Find by Query</strong></td></tr><tr><td><strong>Sort</strong></td><td>Define a ordem de classificação da query.</td><td>String</td><td>✅</td><td><code>N/A</code></td><td><strong>Operation</strong> é <strong>Find by Object ID</strong> ou <strong>Find by Query</strong></td></tr><tr><td><strong>queryTimeoutMs</strong></td><td>Tempo máximo, em milissegundos, que uma query pode rodar no servidor antes de ser abortada. Aplica-se apenas às operações <strong>Find by Object ID</strong>, <strong>Find By Query</strong> e <strong>Aggregate</strong>; operações de escrita não são afetadas.</td><td>Integer</td><td>✅</td><td><code>295000</code></td><td><strong>Operation</strong> é <strong>Find by Object ID</strong>, <strong>Find by Query</strong> ou <strong>Aggregate</strong></td></tr><tr><td><strong>totalTimeoutMs</strong></td><td>Tempo limite total, em milissegundos, para toda a leitura (consulta inicial mais cada lote buscado a partir do cursor, incluindo novas tentativas). Vazio ou <code>0</code> significa sem limite.</td><td>Integer</td><td>✅</td><td>N/A</td><td><strong>Operation</strong> é <strong>Find by Object ID</strong>, <strong>Find by Query</strong> ou <strong>Aggregate</strong></td></tr><tr><td><strong>Unique Index</strong></td><td>Quando ativado, o conector cria um índice que aceita apenas valores únicos de Object ID. Quando desativado, cria um índice não único.</td><td>Boolean</td><td>❌</td><td><code>true</code></td><td>—</td></tr><tr><td><strong>Isolated</strong></td><td>Quando ativado, o conector delimita todas as queries à execução atual.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Upsert</strong></td><td>Quando ativado, o conector insere o objeto informado na coleção caso ele ainda não exista.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td><strong>Operation</strong> é <strong>Update By Object ID</strong> ou <strong>Update By Query</strong></td></tr><tr><td><strong>Fail On Error</strong></td><td>Quando ativado, o conector interrompe a execução do pipeline se ocorrer um erro. Quando desativado, a execução continua, mas o resultado define a propriedade "success" como false.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr></tbody></table>
{% endtab %}

{% tab title="Documentation" %}

<table><thead><tr><th width="122.59991455078125">Parâmetro</th><th width="231.4000244140625">Descrição</th><th width="100">Tipo</th><th width="110.4000244140625">Suporta DB</th><th width="149.59063720703125">Valor padrão</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Campo opcional para descrever a configuração do conector e quaisquer regras de negócio relevantes.</td><td>String</td><td>❌</td><td><code>N/A</code></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### **Como funcionam os parâmetros de timeout**

O `queryTimeoutMs` limita o tempo do primeiro comando enviado ao servidor. O `totalTimeoutMs` limita o tempo da leitura completa, incluindo os lotes buscados depois.

{% hint style="info" %}
Valores inválidos nesses parâmetros não geram erro no pipeline. O conector ignora o valor e registra um aviso nos logs. Com isso, você pode configurar os dois parâmetros com [expressões Double Braces](/documentation/connectors-and-triggers/pt-br/double-braces/overview.md) resolvidas em tempo de execução.
{% endhint %}

#### **queryTimeoutMs**

O `queryTimeoutMs` aceita valores maiores que `0` e até `295000` milissegundos (295 segundos). O parâmetro permite reduzir esse limite, mas não aumentá-lo. Se o valor estiver fora desse intervalo ou não for numérico, o conector usa o valor padrão.

Se a consulta atingir o timeout, o conector retorna um erro imediatamente e não faz novas tentativas, diferente do que acontece com falhas temporárias. Dessa forma, consultas lentas falham rapidamente e não bloqueiam a etapa por vários minutos.

Se o `totalTimeoutMs` também estiver configurado, o `queryTimeoutMs` não pode ultrapassar o tempo restante do limite total.

#### **totalTimeoutMs**

O `queryTimeoutMs` se aplica apenas ao primeiro comando. Resultados grandes são buscados em lotes e, sem o `totalTimeoutMs`, essa busca não tem limite de tempo.

Se o campo estiver vazio ou com `0`, a leitura não tem limite de tempo. Valores negativos ou não numéricos são ignorados. O limite é contado por mensagem, e as novas tentativas dessa mensagem consomem o mesmo tempo.

Se a leitura atingir o limite, o conector fecha o cursor e retorna um erro de timeout com o número de documentos lidos até o momento. Esse erro não gera novas tentativas. Se a opção **Fail On Error** estiver desabilitada, a etapa retorna `"success": false`.

{% hint style="warning" %}
Se um lote estiver sendo buscado quando o limite for atingido, apenas o timeout global do socket (300 segundos) pode interromper a busca.
{% endhint %}

Recomendamos usar o `totalTimeoutMs` como medida de segurança e não como a principal forma de controlar leituras longas. Para coleções grandes, use paginação com **Limit** e **Skip** e crie um índice no campo definido em **Sort**.

## **Boas práticas**

O Object Store é um banco de dados NoSQL auxiliar para integrações. Ele torna o desenvolvimento de integrações mais ágil e prático. As boas práticas a seguir mostram como usar o conector com eficácia:

* O conector Object Store funciona como um banco de dados intermediário, ou seja, ele faz a mediação de informações entre os fluxos de uma integração. Por isso, use-o apenas para armazenar informações relevantes para essa integração.
* O Object Store é um banco de dados temporário. Depois que a informação já cumpriu seu papel no fluxo da integração, remova regularmente os dados antigos e desnecessários. Você pode removê-los manualmente ou criar um índice com um mecanismo de TTL para expirá-los automaticamente.
* Por ser um banco auxiliar, use o conector Object Store apenas em casos específicos para apoiar o desenvolvimento de integrações, e não como um banco de dados permanente.
* A Digibee Integration Platform armazena todos os dados com segurança. No entanto, recomendamos criptografar os dados sensíveis armazenados no Object Store usando os conectores de criptografia disponíveis no canvas.

## **Fluxo de mensagens**

### **Entrada**

Para esse conector, a única entrada obrigatória é um objeto JSON. O parâmetro de entrada suporta a sintaxe Double Braces, então você pode enviar a mensagem recebida diretamente para o conector.

### **Saída**

* **Insert**

```json
{
    "data": [],
    "updateCount": 1
}
```

* **Find**

```json
{
   "data": [
       {
           "name": "Galaxy s20",
           "uuid": "123",
           "_oId": "1"
       }
   ],
   "rowCount": 1
}
```

* **Update**

```json
{
    "data": [],
    "updateCount": 1
}
```

* **Delete**

```json
{
    "data": [],
    "updateCount": 1
}
```

* **Aggregate**

```json
{
    "data": [],
    "rowCount": 0
}
```

## **Object Store em ação**

Os exemplos acima mostraram a saída de cada operação. Os exemplos a seguir demonstram como configurar o conector corretamente para obter um resultado específico:

### **Inserir vários itens de uma vez em uma coleção**

Ao enviar um array de objetos no campo Document, o conector insere cada item separadamente na coleção selecionada.

Configure o conector com os seguintes parâmetros:

* **Operation**: `Insert`
* **Unique Index**: `False`
* **Document**:

```json
[
   {
       "id": 1,
       "name": "Galaxy s20",
       "price": 5000
   },
   {
       "id": 2,
       "name": "Samsung 4k 55\"",
       "price": 5000
   },
   {
       "id": 3,
       "name": "Galaxy A10",
       "price": 699
   },
   {
       "id": 4,
       "name": "Galaxy A51",
       "price": 1620
   }
]
```

#### **Saída**

```json
{
    "data": [],
    "updateCount": 4
}
```

{% hint style="info" %}
Você só pode inserir vários objetos de uma vez em coleções criadas com **Unique Index** definido como **False**. Você define a propriedade **Unique Index** na criação da coleção, e não é possível alterá-la depois.&#x20;
{% endhint %}

### **Buscar itens a partir de uma query determinada**

Por exemplo, considere um Object Store que já tem itens do tipo produto cadastrados, cada um com um nome e um preço.

Configure o conector com os seguintes parâmetros:

* **Operation**: `Find By Query`
* **Query**:

```javascript
{
    "product.price": { $gt: 2000 }
}
```

#### **Saída**

```json
{
   "data": [
       {
           "product": {
               "id": 1,
               "name": "Galaxy s20",
               "price": 5000
           },
           "_oId": "1"
       },
       {
           "product": {
               "id": 2,
               "name": "Samsung 4k 55\"",
               "price": 5000
           },
           "_oId": "2"
       }
   ],
   "rowCount": 2
}
```

### **Buscar todos os itens de uma query**

Por exemplo, considere um Object Store que já tem itens do tipo produto cadastrados, cada um com um nome e um preço.

Configure o conector com os seguintes parâmetros:

* **Operation**: `Find By Query`
* **Limit**: `10`
* **Query**: `{}`

#### **Saída**

```json
{
   "data": [
       {
           "product": {
               "id": 1,
               "name": "Galaxy s20",
               "price": 5000
           },
           "_oId": "1"
       },
       {
           "product": {
               "id": 2,
               "name": "Samsung 4k 55\"",
               "price": 5000
           },
           "_oId": "2"
       },
       {
           "product": {
               "id": 3,
               "name": "Galaxy A10",
               "price": 699
           },
           "_oId": "3"
       },
       {
           "product": {
               "id": 4,
               "name": "Galaxy A51",
               "price": 1620
           },
           "_oId": "4"
       }
   ],
   "rowCount": 4
}
```

Neste exemplo, o parâmetro **Limit** evita uma sobrecarga desnecessária ao retornar objetos do Object Store. Sem ele, o pipeline pode lançar um erro "Out Of Memory". Definir o **Limit** permite controlar quantos objetos a resposta retorna.

### **Atualizar um item a partir de um ID específico**

Por exemplo, considere um Object Store que já tem itens do tipo produto cadastrados, cada um com um nome e um preço.

Configure o conector com os seguintes parâmetros:

* **Operation**: `Update By Object ID`
* **Object ID**: `3`
* **Document**:

```javascript
{
   $set: {
       "product": {
         "id": 3,
         "name": "Galaxy A10",
         "price": 605
       }
   }
}
```

#### **Saída**

```json
{
    "data": [],
    "updateCount": 1
}
```

Neste exemplo, a saída apenas identifica que uma atualização aconteceu. Para confirmar se o objeto foi atualizado corretamente, repita o cenário de busca por ID.

{% hint style="info" %}
Quando o conector Object Store atualiza registros dentro de um conector de iteração, como o [**For Each**](/documentation/connectors-and-triggers/pt-br/connectors/logic/for-each.md) ou o [**Stream File Reader**](/documentation/connectors-and-triggers/pt-br/connectors/files/stream-file-reader.md), e roda em paralelo, instruções de atualização idênticas podem criar uma condição de corrida. Nesse caso, uma instrução retorna `"updateCount": 1` e a outra retorna `"updateCount": 0`.

Isso acontece quando dois registros idênticos entram no pool de operações do Object Store ao mesmo tempo, e suas instruções de atualização ou inserção (com **Upsert** ativado) rodam sequencialmente. A primeira instrução atualiza o registro. A segunda instrução encontra o registro já atualizado, determina que nenhuma mudança é necessária e retorna `"updateCount": 0`.
{% endhint %}

### **Remover um item a partir de um ID específico**

Por exemplo, considere um Object Store que já tem itens do tipo produto cadastrados, cada um com um nome e um preço.

Configure o conector com os seguintes parâmetros:

* **Operation**: `Delete By Object Id`
* **Object ID**: `4`

#### **Saída**

```json
{
    "data": [],
    "updateCount": 1
}
```

Neste exemplo, a saída apenas identifica que uma exclusão aconteceu. Para confirmar se o objeto foi excluído corretamente, repita o cenário de busca por ID.

### **Agregação para copiar a coleção**

Por exemplo, considere um Object Store chamado `product` que já tem itens do tipo produto cadastrados, cada um com um nome e um preço. A partir dessa coleção, crie um novo Object Store chamado `product-backup` e copie todos os itens para ele.

Informe um array de objetos com o pipeline de agregação da query no parâmetro **Document**.

Configure o conector com os seguintes parâmetros:

* **Operation**: `Aggregate`
* **Query**:

```javascript
[
   {
       $merge: {
           into: "product-backup",
           on: "_id",
           whenMatched: "replace",
           whenNotMatched: "insert"
       }
   }
]
```

Neste exemplo, a query substitui os itens existentes pelos novos na coleção.

#### **Saída**

```json
{
    "data": [],
    "rowCount": 0
}
```

Para confirmar se a coleção foi criada corretamente com os itens esperados, repita o cenário de busca para todos os itens, usando a nova coleção.

### **Agregação para filtrar itens da coleção**

Informe um array de objetos com o pipeline de agregação da query no parâmetro **Document**.

Configure o conector com os seguintes parâmetros:

* **Operation**: `Aggregate`
* **Query**:

```javascript
[
   {
       $match: {
           "product.price": {
               $gt: 3000
           }
       }
   },
   {
       $group: {
           _id: null,
           count: {
               $sum: 1
           }
       }
   }
]
```

Neste exemplo, a query busca produtos com preço acima de um valor específico e retorna a soma deles.

#### **Saída**

```json
{
    "data": [{
        "count": 2
    }],
    "rowCount": 0
}
```

### **Criar um índice com tempo de expiração**

O Object Store permite criar um índice com um atributo TTL (Time to live), com o qual você pode definir uma estratégia de expiração para seus documentos. O parâmetro **Expire after seconds** controla esse comportamento. Os exemplos a seguir mostram como criar índices com estratégias de expiração:

#### **Criar um índice com TTL constante**

Configure o conector com os seguintes parâmetros:

* **Operation**: `Create Index`
* **Expire After Seconds**: `300`
* **Query**: `{"expiresAt": 1}`&#x20;

O nome do campo deve corresponder ao atributo de data do seu documento que controla o tempo de vida do objeto. A plataforma exclui automaticamente todos os documentos com esse campo após o número de segundos especificado no parâmetro **Expire after seconds**.

**Saída**

```json
{
    "data": "expiresAt_1",
    "rowCount": 0
}
```

#### **Criar um índice com datas personalizadas**

Configure o conector com os seguintes parâmetros:

* **Operation**: `Create Index`
* **Expire After Seconds**: `0`
* **Query**: `{"expiresAt": 1}`&#x20;

O nome do campo deve corresponder ao atributo de data do seu documento que controla o tempo de vida do objeto. Defina também o parâmetro **Expire after seconds** como 0.

Nesse cenário, a expiração é definida pelo valor de datetime do campo correspondente no parâmetro **Query**.

{% hint style="info" %}
&#x20;Ao inserir novos documentos, certifique-se de que o campo configurado no índice tenha um valor de data.&#x20;
{% endhint %}

```javascript
{
    "id": 1,
    "name": "Galaxy s20",
    "price": 5000,
    "expiresAt": new Date()
}
```

{% hint style="info" %}
O índice TTL não garante que os dados expirados sejam excluídos imediatamente. Pode haver um atraso entre o momento em que um documento expira e o momento em que o Object Store o remove do banco de dados, porque a tarefa em segundo plano que remove documentos expirados roda a cada 60 segundos.
{% endhint %}

### **Listar todos os índices**

Essa operação lista todos os índices que você criou em um Object Store.

#### **Saída**

```json
{
  "data": [
    {
      "v": 2,
      "key": {
        "expiresAt": 1
      },
      "name": "expiresAt_1",
      "expireAfterSeconds": 0
    }
  ],
  "rowCount": 1
}
```

### **Remover um índice existente**

Essa operação permite remover um índice criado anteriormente.

Configure o conector com os seguintes parâmetros:

* **Operation**: `Drop Index`
* **Query**: `{"expiresAt": 1}`

#### **Saída**

```json
{
    "data": "expiresAt_1",
    "rowCount": 0
}
```

## **Tecnologia**

O Object Store usa operadores de busca e agregação de objetos semelhantes à sintaxe do MongoDB. Veja a [documentação do MongoDB](https://www.mongodb.com/docs/manual/reference/operator/) para saber mais.

{% hint style="info" %}
Os dados do Object Store são isolados entre ambientes. No entanto, o ambiente de **Test** compartilha dados com o [**Painel de Execução**](/documentation/developer-guide/pt-br/development-cycle/build-overview/canvas/execution-panel.md).&#x20;
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/structured-data/object-store.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.