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

getSchemaDrift: Compare tables with their schema

- run:
    module: collections
    function: getSchemaDrift
    parameters:
      collection: customers
    output: drift

Parameter	Type	Required	Description
`collection`	string	no	Only this collection. All the collections of the namespace when absent

Lists the collections whose database table differs from their schema: the configuration of their Collection instance, or the last schema applied for a collection no instance declares (declaredIn). Reads only, and only the tables of the caller’s workspace (or app).

drift: true
collections:
  - collection: customers
    declaredIn: config
    created: false          # true when the whole table is missing
    columns:
      - column: profile
        from: text
        to: jsonb
        changes: [type]
      - column: last_login
        to: timestamptz
        changes: [added]
    sql: alter table ...    # what the next synchronization would run
excluded: []                # collections whose schema is invalid

PostgreSQL only: on MongoDB, drift is always false.

runSchemaMigrations: Convert columns of a collection

- run:
    module: collections
    function: runSchemaMigrations
    parameters:
      collection: customers
      dryRun: true
      migrations:
        - op: alterColumnType
          column: profile
          from: [text, character varying]
          to: jsonb
          cast: auto
    output: result

Parameter	Type	Required	Description
`collection`	string	yes	Collection name
`migrations`	object[]	no	Migrations to run first, same format as the `migrations` of a Collection instance
`dryRun`	boolean	no	Only report what would be converted, change nothing

Runs the given migrations, then those of the collection’s configuration and the automatic ones, then synchronizes the collection with its schema, like an update of its configuration: in one transaction, with the same workspaces.collections.migrated and workspaces.collections.notMigrated events. Returns applied, failed, skipped (columns left alone, with howTo convert them) and rolledBack. If the synchronization fails, the conversions are rolled back and the error details list them.With dryRun: true, nothing is converted and the table is not locked against reads: planned lists what would run (cast, rows, retyped). The schema is validated as the real run would, but the synchronization that follows the conversions is not tried: one that fails on the data (a unique constraint on duplicate rows…) only shows up in the real run, which then rolls the conversions back.Only conversions to jsonb of properties the schema declares json can be passed in migrations. The synchronization that follows brings every column back to its declared type: any other conversion would be undone at once, after rewriting the data twice. Declare the property json first. Such a migration, or an invalid one (unknown op, cast or to), is refused before anything runs.

Every call without dryRun synchronizes the collection and makes every runtime reload it, even when there is nothing to convert. Call it once to fix a drift, never on a schedule or on each page load.
Do not pass migrations from a request ({{body.migrations}} behind an endpoint): until now only an editor of the workspace could declare a migration, in the configuration. Whoever calls the endpoint could rewrite a column of the collection.
In an app, the collection’s table is shared by every workspace the app is installed in. The schema is read from the app version the calling workspace installed, and the conversion applies to every workspace.

PostgreSQL only: on MongoDB, the result is empty.

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