> 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/connectors/structured-data/object-store.md).

# Object Store

Discover more about the Object Store connector and how to use it on the Digibee Integration Platform.

**Object Store** performs operations to store any document in Digibee's Object Store. It's a simple, quick way to save useful JSON-type information, offering operations that support multiple use cases during pipeline creation.

{% hint style="info" %}
Object Store isn't enabled by default in new realms. Contact [Digibee support](/documentation/troubleshooting/help-and-faq/support.md) to request it.
{% endhint %}

## **Parameters**

The table below lists all configuration parameters for the connector. Parameters that support [Double Braces expressions](/documentation/connectors-and-triggers/double-braces/overview.md) are marked with ✅ in the **Supports DB** column.

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

<table><thead><tr><th width="112">Parameter</th><th width="231.20001220703125">Description</th><th width="83.199951171875">Type</th><th width="80.800048828125">Supports DB</th><th width="100">Default value</th><th width="124.800048828125">Visible when</th></tr></thead><tbody><tr><td><strong>Account</strong></td><td>Account to be used by the connector. This item can't be changed.</td><td>String</td><td>❌</td><td><code>Digibee Object Store Account</code></td><td>—</td></tr><tr><td><strong>Operation</strong></td><td>Operation to be executed inside 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, and 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>Name of the collection to be used to record or read information. If it doesn't exist, the connector creates it automatically.</td><td>String</td><td>❌</td><td><code>sales</code></td><td>—</td></tr><tr><td><strong>Expire After Seconds</strong></td><td>Defines the number of seconds after which a document from the Object Store expires.</td><td>Integer</td><td>✅</td><td><code>0</code></td><td><strong>Operation</strong> is <strong>Create Index</strong></td></tr><tr><td><strong>Object ID</strong></td><td>Identifier of the object to be stored or searched. It can be a unique number or a UUID.</td><td>String</td><td>✅</td><td><code>1</code></td><td><strong>Operation</strong> is <strong>Find by Object ID</strong>, <strong>Insert</strong>, <strong>Update by Object ID</strong>, or <strong>Delete by Object ID</strong></td></tr><tr><td><strong>Query</strong></td><td>JSON object that defines the query.</td><td>String</td><td>✅</td><td><code>N/A</code></td><td><strong>Operation</strong> is <strong>Find by Query</strong>, <strong>Aggregate</strong>, <strong>Update by Query</strong>, <strong>Delete by Query</strong>, <strong>Create Index</strong>, or <strong>Drop Index</strong></td></tr><tr><td><strong>Document</strong></td><td>JSON field with the object's data or update instructions for the operation.</td><td>String</td><td>✅</td><td><code>N/A</code></td><td><strong>Operation</strong> is <strong>Insert</strong>, <strong>Update by Object ID</strong>, or <strong>Update by Query</strong></td></tr><tr><td><strong>Limit</strong></td><td>Maximum number of objects to be returned in a search.</td><td>Integer</td><td>✅</td><td><code>0</code></td><td><strong>Operation</strong> is <strong>Find by Object ID</strong> or <strong>Find by Query</strong></td></tr><tr><td><strong>Skip</strong></td><td>Number of objects to skip before the query returns results. Use this parameter together with <strong>Limit</strong> to enable pagination.</td><td>Integer</td><td>✅</td><td><code>0</code></td><td><strong>Operation</strong> is <strong>Find by Object ID</strong> or <strong>Find by Query</strong></td></tr><tr><td><strong>Sort</strong></td><td>Defines the sort order for the query.</td><td>String</td><td>✅</td><td><code>N/A</code></td><td><strong>Operation</strong> is <strong>Find by Object ID</strong> or <strong>Find by Query</strong></td></tr><tr><td><strong>queryTimeoutMs</strong></td><td>Maximum time, in milliseconds, that a query can run on the server before it's aborted. Applies only to the <strong>Find by Object ID</strong>, <strong>Find By Query</strong>, and <strong>Aggregate</strong> operations; write operations aren't affected.</td><td>Integer</td><td>✅</td><td><code>295000</code></td><td><strong>Operation</strong> is <strong>Find by Object ID</strong>, <strong>Find by Query</strong>, or <strong>Aggregate</strong></td></tr><tr><td><strong>totalTimeoutMs</strong></td><td>Total time limit in milliseconds for the whole read (initial query plus every batch fetched from the cursor, including retries). Empty or <code>0</code> means no limit.</td><td>Integer</td><td>✅</td><td>N/A</td><td><strong>Operation</strong> is <strong>Find by Object ID</strong>, <strong>Find by Query</strong>, or <strong>Aggregate</strong></td></tr><tr><td><strong>Unique Index</strong></td><td>When enabled, the connector creates an index that accepts unique Object ID values only. When disabled, it creates a non-unique index.</td><td>Boolean</td><td>❌</td><td><code>true</code></td><td>—</td></tr><tr><td><strong>Isolated</strong></td><td>When enabled, the connector scopes all queries to the current execution.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Upsert</strong></td><td>When enabled, the connector inserts the provided object into the collection if it doesn't already exist.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td><strong>Operation</strong> is <strong>Update By Object ID</strong> or <strong>Update By Query</strong></td></tr><tr><td><strong>Fail On Error</strong></td><td>When enabled, the connector stops pipeline execution if an error occurs. When disabled, execution continues, but the result sets the "success" property to 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="120.20001220703125">Parameter</th><th width="231">Description</th><th width="100">Type</th><th width="110.4000244140625">Supports DB</th><th width="146.79058837890625">Default value</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Optional field to describe the connector configuration and any relevant business rules.</td><td>String</td><td>❌</td><td><code>N/A</code></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### **How the timeout parameters work**

`queryTimeoutMs` limits the first command sent to the server, and `totalTimeoutMs` limits the entire read, including every batch fetched afterward.

{% hint style="info" %}
Invalid values in either parameter never cause a pipeline error. The connector ignores them and logs a warning, so you can safely resolve both parameters from [Double Braces expressions](/documentation/connectors-and-triggers/double-braces/overview.md) at runtime.
{% endhint %}

#### **queryTimeoutMs**

`queryTimeoutMs` accepts values greater than `0` and up to `295000` milliseconds (295 seconds). You can use it to reduce this limit, but not to raise it. For values outside this range or non-numeric values, the connector uses the default value.

When a query reaches the timeout, the connector returns an error immediately and does not retry it as a transient failure. As a result, slow queries fail fast and explicitly and don't block the step for several minutes.

If `totalTimeoutMs` is also set, the time left in the total limit caps `queryTimeoutMs`.

#### **totalTimeoutMs**

`queryTimeoutMs` covers only the first command. Large results are then fetched in batches, and without `totalTimeoutMs`, this fetching has no time limit.

If you leave the field empty or set it to `0`, reads have no time limit. Negative and non-numeric values are ignored. The limit is counted per message, and any retries of that message draw from the same time budget.

When a read hits the limit, the connector closes the cursor and returns a timeout error with the number of documents read up to that point. This error isn't retried. If **Fail On Error** is disabled, the step returns `"success": false`.

{% hint style="warning" %}
If a batch request is already in progress when the limit is reached, only the global socket timeout (300 seconds) can interrupt it.
{% endhint %}

Because of this, `totalTimeoutMs` works best as a safeguard, not as the main way to control long reads. For large collections, use paging with **Limit** and **Skip**, plus an index on the **Sort** field.

## **Best practices**

Object Store is an auxiliary NoSQL database for integrations. It makes integration development faster and more practical. The following best practices show how to use the connector effectively:

* The Object Store connector acts as an intermediary database, that is, it mediates information between the flows of an integration. Use it only to store information relevant to that integration.
* Object Store is a temporary database. After information has served its purpose in the integration flow, remove old and unnecessary data regularly. You can remove it manually or create an index with a TTL mechanism to expire it automatically.
* Because it's an auxiliary database, use the Object Store connector only in specific cases to support integration development, not as a permanent database.
* The Digibee Integration Platform stores all data securely. However, we recommend encrypting sensitive data stored in Object Store using the encryption connectors available on the canvas.

## **Messages flow**

### **Input**

For this connector, the only mandatory input is a JSON object. The input parameter supports Double Braces syntax, so you can send the received message directly to the connector.

### **Output**

* **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 in action**

The examples above showed the output of each operation. The following examples demonstrate how to configure the connector correctly to get a specific result:

### **Insert multiple items at once in a collection**

When you send an array of objects in the Document field, the connector inserts each item separately into the selected collection.

Configure the connector with the following parameters:

* **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
   }
]
```

#### **Output**

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

{% hint style="info" %}
You can only insert multiple objects at once in collections created with **Unique Index** set to **False**. You set the **Unique Index** property when you create the collection, and you can't change it afterward.
{% endhint %}

### **Find items from a determined query**

For example, consider an Object Store that already has product-type items registered, each with a name and a price.

Configure the connector with the following parameters:

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

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

#### **Output**

```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
}
```

### **Find all the items from a query**

For example, consider an Object Store that already has product-type items registered, each with a name and a price.

Configure the connector with the following parameters:

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

#### **Output**

```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
}
```

In this example, the **Limit** parameter prevents an unnecessary overload when returning objects from Object Store. Without it, the pipeline can throw an "Out Of Memory" error. Setting **Limit** lets you control how many objects the response returns.

### **Update an item from a specific ID**

For example, consider an Object Store that already has product-type items registered, each with a name and a price.

Configure the connector with the following parameters:

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

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

#### **Output**

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

In this example, the output only identifies that an update happened. To confirm the object updated correctly, repeat the ID search scenario.

{% hint style="info" %}
When the Object Store connector updates records inside an iteration connector, such as [**For Each**](/documentation/connectors-and-triggers/connectors/logic/for-each.md) or [**Stream File Reader**](/documentation/connectors-and-triggers/connectors/files/stream-file-reader.md), and runs in parallel, identical update instructions can create a race condition. In that case, one instruction returns `"updateCount": 1` and the other returns `"updateCount": 0`.

This happens when two identical records enter the Object Store operation pool at the same time, and their update or insert instructions (with **Upsert** enabled) run sequentially. The first instruction updates the record. The second instruction finds the record already updated, determines that no change is needed, and returns `"updateCount": 0`.
{% endhint %}

### **Remove an item from a specific ID**

For example, consider an Object Store that already has product-type items registered, each with a name and a price.

Configure the connector with the following parameters:

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

#### **Output**

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

In this example, the output only identifies that a deletion happened. To confirm the object was deleted correctly, repeat the ID search scenario.

### **Aggregation to copy the collection**

For example, consider an Object Store called `product` that already has product-type items registered, each with a name and a price. From that collection, create a new Object Store called `product-backup` and copy all the items into it.

Provide an object array with the query aggregation pipeline in the **Document** parameter.

Configure the connector with the following parameters:

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

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

In this example, the query replaces existing items with the new ones in the collection.

#### **Output**

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

To confirm the collection was created correctly with the expected items, repeat the search scenario for all items, using the new collection.

### **Aggregation to filter collection items**

Provide an object array with the query aggregation pipeline in the **Document** parameter.

Configure the connector with the following parameters:

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

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

In this example, the query searches for products with a price above a specific value and returns their sum.

#### **Output**

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

### **Create an index with expiration time**

Object Store lets you create an index with a TTL (Time to live) attribute, so you can define an expiration strategy for your documents. The **Expire after seconds** parameter controls this behavior. The following examples show how to create indexes with expiration strategies:

#### **Create an index with constant TTL**

Configure the connector with the following parameters:

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

The field name must match the date attribute in your document that controls the object's lifetime. The platform automatically deletes all documents with this field after the number of seconds specified in the **Expire after seconds** parameter.

**Output**

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

#### **Create an index with custom dates**

Configure the connector with the following parameters:

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

The field name must match the date attribute in your document that controls the object's lifetime. Also set the **Expire after seconds** parameter to 0.

In this scenario, the expiration date comes from the datetime value of the corresponding field in the **Query** parameter.

{% hint style="info" %}
When you insert new documents, make sure the field you configured in the index has a date value.
{% endhint %}

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

{% hint style="info" %}
The TTL index doesn't guarantee that expired data is deleted immediately. There can be a delay between when a document expires and when Object Store removes it from the database, because the background task that removes expired documents runs every 60 seconds.
{% endhint %}

### **List all indexes**

This operation lists all indexes you created in an Object Store.

#### **Output**

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

### **Drop an existing index**

This operation lets you drop an index you created previously.

Configure the connector with the following parameters:

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

#### **Output**

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

## **Technology**

Object Store uses search operators and object aggregation similar to MongoDB syntax. See the [MongoDB documentation](https://www.mongodb.com/docs/manual/reference/operator/) to learn more.

{% hint style="info" %}
Object Store data is isolated between environments. However, the **Test** environment shares data with the **Execution panel**.
{% 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/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.