DataStore - Data Storage

What is the DataStore

The DataStore is a key-value storage system with grouping and tagging capabilities. It allows workflows to persist, query, and manage structured data without the need for external databases.

Data is stored in the datastores table of the system database, providing an integrated mechanism accessible from any workflow node.

---

Key Concepts

• Group (group): Logical grouping of records. Functions as a conceptual “table” or “collection”. Examples: "clients", "orders", "configuration".
• Key (key): Unique identifier within a group. Equivalent to a primary key within that group.
• Data (row_data): JSON object with the record data. Can contain any valid JSON structure.
• Tags: Labels to categorize and filter records. They are free-form text strings separated by commas.

The combination of group + key is unique. If a record is inserted with a group and key that already exist, an automatic UPSERT is performed (update instead of error).

---

Available Operations

The operation to execute is defined in the config.action parameter.

add - Insert or update a record

Inserts a new record or updates an existing one if the group + key combination already exists.

• If the key already exists in the group, updates the data
• If it does not exist, inserts a new record
• Emits the insert or update event accordingly (usable by DataStore Triggers)

bulk - Bulk insert/update

Allows processing multiple records in a single operation.

• Receives an array of records
• keyField: field within each record used as the unique key
• Optimized for large data volumes

filter - Query records

Searches and returns records that match the specified criteria.

• Filter by group, key, tags
• tagMode: defines how tag filters are applied:
  • any (OR between tags)
  • all (AND between tags)
  • exclude (exclude tags)
• Returns an array of matching records

getField - Get a specific field

Extracts a single field from a record identified by group + key.

• Useful when only a specific value from a record is needed
• Returns only the value of the requested field

exists / isFoundKey - Check existence

Checks whether a record exists in the DataStore.

• Returns true or false depending on whether the record exists or not
• Searched by group + key

delete - Delete records

Deletes records from the DataStore.

• Can delete by direct ID or by the group + key combination

modifyTags - Manage tags

Allows adding and/or removing tags from existing records.

• New tags can be added to a record
• Existing tags can be removed from a record
• Both operations can be performed in a single call

map - Map keys to values

Given an array of keys, gets the value of a specific field for each one.

• Useful for bulk data resolution (for example, getting names from IDs)
• Supports transformations: uppercase, lowercase, trim

logs - Change history

Queries the change log of a record.

• Allows auditing modifications made to a record
• Returns the operation history with their details

---

Common Parameters

Parameter	Type	Description
action	select	Operation to perform (add, bulk, filter, getField, exists, delete, modifyTags, map, logs)
group	text	Name of the group the record belongs to
key	text	Unique key of the record within the group
row	json/textarea	Record data in JSON format
tags	text	Comma-separated tags
tagMode	select	Tag filtering mode: any, all, exclude

---

Example: Basic CRUD

Save a client

{
  "action": "add",
  "group": "clientes",
  "key": "CLI-001",
  "row": {
    "nombre": "Juan Perez",
    "email": "juan@email.com",
    "plan": "premium"
  },
  "tags": "activo,premium"
}

If the record clientes / CLI-001 does not exist, it is inserted. If it already exists, the data and tags are updated.

Search for premium clients

{
  "action": "filter",
  "group": "clientes",
  "tags": "premium",
  "tagMode": "any"
}

Returns all records in the clientes group that have the premium tag.

Get a client’s email

{
  "action": "getField",
  "group": "clientes",
  "key": "CLI-001",
  "field": "email"
}

Returns only the value "juan@email.com".

Check if a client exists

{
  "action": "exists",
  "group": "clientes",
  "key": "CLI-001"
}

Returns true if the record exists, false otherwise.

Delete a client

{
  "action": "delete",
  "group": "clientes",
  "key": "CLI-001"
}

---

DataStore Trigger

The DataStore Trigger node allows starting a workflow automatically when records are modified in the DataStore.

Available Events

• insert: Fires when a new record is inserted
• update: Fires when an existing record is updated
• bulk_insert: Fires during bulk insertions
• bulk_update: Fires during bulk updates

Received Data

When the trigger fires, the node receives:

• The current record data
• previousRecord for update events, which allows comparing previous values with new ones

Usage Example

Scenario: Send a welcome email when a new client is registered.

DataStore Trigger (event: insert, group: "clientes")
  -> SendMail (to: {{email}}, subject: "Welcome {{nombre}}")
  -> End

The trigger detects the insertion in the clientes group and the workflow automatically sends an email using the data from the inserted record.

---

Tags and Advanced Filtering

Tags are free-form text strings assigned to records to categorize them. Examples: "active", "premium", "pending", "urgent".

Filtering Modes (tagMode)

• any (OR): Returns records that have AT LEAST one of the specified tags.

  Example: tags "premium,vip" with tagMode any returns records that are premium OR vip (or both).

• all (AND): Returns records that have ALL the specified tags.

  Example: tags "activo,premium" with tagMode all returns only records that are both active AND premium.

• exclude: Returns records that DO NOT have any of the specified tags.

  Example: tags "inactivo,eliminado" with tagMode exclude returns records that are neither inactive nor deleted.

Combination with Group

It is recommended to combine tag filtering with group filtering for more precise results. For example, filtering by group "clientes" and tags "premium" with tagMode any returns only clients that are premium, without affecting other groups.

---

Example: Complete Workflow with DataStore

Below is a workflow that manages orders using the DataStore to persist data and tags to control status.

Scenario: Order Processing with Stock Control

Webhook (receives order)
  -> DataStore (add: save order with tags "nuevo,pendiente")
  -> HTTP (check stock in external API)
  -> Decision (is stock available?)
    -> true: DataStore (modifyTags: remove "pendiente", add "confirmado")
    -> false: DataStore (modifyTags: remove "pendiente", add "sin_stock")
  -> Merge -> End

Detail of Each Step

1. Webhook - Receives the order data:

{
  "pedido_id": "PED-2024-100",
  "producto": "Camiseta Azul",
  "cantidad": 3,
  "cliente_email": "cliente@email.com"
}

2. DataStore (add) - Saves the order:

{
  "action": "add",
  "group": "pedidos",
  "key": "PED-2024-100",
  "row": {
    "producto": "Camiseta Azul",
    "cantidad": 3,
    "cliente_email": "cliente@email.com",
    "fecha": "2026-03-23T10:00:00.000Z"
  },
  "tags": "nuevo,pendiente"
}

3. HTTP Request - Checks the product stock in an external API.

4. Decision - Evaluates whether there is sufficient stock based on the API response.

5a. DataStore (modifyTags - true branch) - If there is stock, updates the status:

{
  "action": "modifyTags",
  "group": "pedidos",
  "key": "PED-2024-100",
  "removeTags": "pendiente",
  "addTags": "confirmado"
}

5b. DataStore (modifyTags - false branch) - If there is no stock:

{
  "action": "modifyTags",
  "group": "pedidos",
  "key": "PED-2024-100",
  "removeTags": "pendiente",
  "addTags": "sin_stock"
}

6. Merge -> End - Both branches converge and the workflow finishes.

Subsequently, a DataStore Trigger can be used on the "pedidos" group to detect status changes and trigger additional workflows, such as sending notifications to the customer or generating invoices.