Collections Module

Store, query, and manage structured data from automations

The collections module provides structured data storage and querying for automations. It supports 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: "[e-mail]"
    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: "[e-mail]"
        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: "[e-mail]"
        - name: "Bob"
          email: "[e-mail]"
    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: "[e-mail]"
      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: "[e-mail]"
        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: "[e-mail]"
    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