Collections Module

Runtime modules are the built-in capabilities you call from automations on the foundation, and the collections module is one of them. It provides structured data storage and querying for automations, supporting both MongoDB and SQL backends, with automatic namespace isolation per workspace and app.

This module is meant to be used through the Collection application, which provides a ready-to-use UI for managing collections and schemas. The functions below are available directly via the run instruction for advanced use cases.

Schema Management

updateSchema: Create or update a collection schema

- run:
    module: collections
    function: updateSchema
    parameters:
      collection: customers
      schema: customers
      properties:
        name:
          type: string
        email:
          type: string
        age:
          type: number
      indexes:
        - properties: [email]
      uniques:
        - properties: [email]
    output: result

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`schema`	string	yes	Schema name
`properties`	object	yes	Field definitions (name, type, nullable, etc.)
`indexes`	array	no	Index definitions
`uniques`	array	no	Unique constraint definitions
`oldCollection`	string	no	Previous collection name (for renaming)
`oldSchema`	string	no	Previous schema name (for renaming)

All collections automatically include createdAt, updatedAt, createdBy, and updatedBy fields.

listCollections: List all collections

- run:
    module: collections
    function: listCollections
    output: collections

Returns an array of collection names in the current workspace/app namespace.

getCollectionSchemas: Get all schemas

- run:
    module: collections
    function: getCollectionSchemas
    output: schemas

Returns all schema definitions for the current namespace.

getCollectionStats: Get collection statistics

- run:
    module: collections
    function: getCollectionStats
    parameters:
      collection: customers
    output: stats

Parameter	Type	Required	Description
`collection`	string	yes	Collection name

Returns usage statistics (document count, size, etc.).

inferCollectionSchema: Infer schema from data

- run:
    module: collections
    function: inferCollectionSchema
    parameters:
      collection: customers
    output: inferred

Parameter	Type	Required	Description
`collection`	string	no	Infer from an existing collection
`data`	object[]	no	Infer from sample data

Analyzes data and returns an inferred schema with warnings. Provide either collection or data.

deleteCollections: Delete collections

- run:
    module: collections
    function: deleteCollections
    parameters:
      collections:
        - old-collection
        - temp-data
    output: result

Parameter	Type	Required	Description
`collections`	string[]	no	Specific collections to delete
`all`	boolean	no	Delete all collections in the namespace

Read Operations

findOne: Find a single document

- run:
    module: collections
    function: findOne
    parameters:
      collection: customers
      query:
        email: "jane@example.com"
    output: customer

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`query`	object	yes	Filter criteria

findMany: Find multiple documents

- run:
    module: collections
    function: findMany
    parameters:
      collection: customers
      query:
        age:
          $gte: 18
      opts:
        sort:
          createdAt: -1
        limit: 50
        page: 1
    output: customers

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`query`	object	yes	Filter criteria
`opts.sort`	object	no	Sort order (`1` ascending, `-1` descending)
`opts.limit`	number	no	Maximum documents to return
`opts.page`	number	no	Page number (1-indexed)
`opts.skip`	number	no	Number of documents to skip
`opts.fields`	string[]	no	Fields to include in results

findAndCount: Find with total count

- run:
    module: collections
    function: findAndCount
    parameters:
      collection: customers
      query: {}
      opts:
        limit: 10
        page: 1
    output: result

Returns [entities, totalCount], useful for paginated UIs.

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`query`	object	yes	Filter criteria
`opts`	object	no	Same options as `findMany`

count: Count documents

- run:
    module: collections
    function: count
    parameters:
      collection: customers
      query:
        status: active
    output: total

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`query`	object	yes	Filter criteria

distinct: Get distinct values

- run:
    module: collections
    function: distinct
    parameters:
      collection: customers
      query: {}
      field: country
    output: countries

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`query`	object	yes	Filter criteria
`field`	string	yes	Field to get distinct values for

aggregate: Aggregation pipeline

- run:
    module: collections
    function: aggregate
    parameters:
      collection: orders
      query: {}
      steps:
        - $group:
            _id: "$status"
            count:
              $sum: 1
            totalAmount:
              $sum: "$amount"
    output: stats

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`query`	object	yes	Initial filter criteria
`steps`	object[]	yes	Aggregation pipeline stages

Write Operations

create: Insert a single document

- run:
    module: collections
    function: create
    parameters:
      collection: customers
      data:
        name: "Jane Doe"
        email: "jane@example.com"
        age: 28
    output: result

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`data`	object	yes	Document to insert
`outputMode`	string	no	`"entity"` to return full document, `"simple"` (default) to return `{ acknowledged, insertedId }`

createdAt and updatedAt are set automatically.

bulkCreate: Insert multiple documents

- run:
    module: collections
    function: bulkCreate
    parameters:
      collection: customers
      data:
        - name: "Alice"
          email: "alice@example.com"
        - name: "Bob"
          email: "bob@example.com"
    output: result

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`data`	object[]	yes	Documents to insert
`outputMode`	string	no	`"entity"` for full documents, `"simple"` (default) for `{ acknowledged, insertedCount, insertedIds }`

Update Operations

updateOne: Update a single document

- run:
    module: collections
    function: updateOne
    parameters:
      collection: customers
      query:
        email: "jane@example.com"
      data:
        age: 29
    output: result

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`query`	object	yes	Filter to find the document
`data`	object	yes	Fields to update
`allowMatchAll`	boolean	no	Allow empty query (updates first match)

updatedAt is set automatically. Returns { modifiedCount, matchedCount }.

An empty query without allowMatchAll: true throws an error to prevent accidental mass updates.

updateMany: Update multiple documents

- run:
    module: collections
    function: updateMany
    parameters:
      collection: customers
      query:
        status: inactive
      data:
        archived: true
    output: result

Same parameters and behavior as updateOne, but affects all matching documents.

upsert: Insert or update

- run:
    module: collections
    function: upsert
    parameters:
      collection: customers
      data:
        email: "jane@example.com"
        name: "Jane Doe"
        lastSeen: "{{run.date}}"
      opts:
        onConflictFields:
          - email
        onInsertValues:
          source: "signup"
    output: result

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`data`	object	yes	Document data
`opts.onConflictFields`	string[]	yes	Fields to match for conflict detection
`opts.onInsertValues`	object	no	Additional values set only on insert
`outputMode`	string	no	`"entity"` for full document, `"simple"` (default) for `{ acknowledged, upsertedCount, modifiedCount }`

createdAt is set only on insert; updatedAt is always set.

Delete Operations

deleteOne: Delete a single document

- run:
    module: collections
    function: deleteOne
    parameters:
      collection: customers
      query:
        email: "jane@example.com"
    output: result

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`query`	object	yes	Filter to find the document
`allowMatchAll`	boolean	no	Allow empty query

Returns { deletedCount }.

An empty query without allowMatchAll: true throws an error to prevent accidental mass deletion.

deleteMany: Delete multiple documents

- run:
    module: collections
    function: deleteMany
    parameters:
      collection: customers
      query:
        status: inactive
    output: result

Same parameters as deleteOne, but deletes all matching documents.

Query Syntax

Queries use MongoDB-style operators:

# Exact match
query:
  status: active

# Comparison
query:
  age:
    $gte: 18
    $lt: 65

# Logical operators
query:
  $or:
    - status: active
    - role: admin

# Pattern matching
query:
  name:
    $regex: "^Jane"

Complete Example

slug: manage-contacts
name: Manage Contacts
do:
  # Create a contact
  - run:
      module: collections
      function: create
      parameters:
        collection: contacts
        data:
          name: "{{body.name}}"
          email: "{{body.email}}"
          tags: "{{body.tags}}"
      output: created

  # Find contacts by tag
  - run:
      module: collections
      function: findMany
      parameters:
        collection: contacts
        query:
          tags:
            $in:
              - vip
        opts:
          sort:
            createdAt: -1
          limit: 20
      output: vipContacts

  # Update a contact
  - run:
      module: collections
      function: updateOne
      parameters:
        collection: contacts
        query:
          id: "{{contactId}}"
        data:
          lastContacted: "{{run.date}}"
      output: updated

Overview

Chat

Agent Creator

Knowledges

Collections

Builder

Governe

Engage

Insights

Collections Module

Schema Management

Read Operations

Write Operations

Update Operations

Delete Operations

Query Syntax

Complete Example

​Schema Management

​Read Operations

​Write Operations

​Update Operations

​Delete Operations

​Query Syntax

​Complete Example

Schema Management

Read Operations

Write Operations

Update Operations

Delete Operations

Query Syntax

Complete Example