> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  This module is meant to be used through the [**Collection** application](https://docs.prisme.ai/apps-store/marketplace/collection), 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.
</Info>

## Schema Management

<AccordionGroup>
  <Accordion title="updateSchema — Create or update a collection schema">
    ```yaml theme={null}
    - 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.
  </Accordion>

  <Accordion title="listCollections — List all collections">
    ```yaml theme={null}
    - run:
        module: collections
        function: listCollections
        output: collections
    ```

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

  <Accordion title="getCollectionSchemas — Get all schemas">
    ```yaml theme={null}
    - run:
        module: collections
        function: getCollectionSchemas
        output: schemas
    ```

    Returns all schema definitions for the current namespace.
  </Accordion>

  <Accordion title="getCollectionStats — Get collection statistics">
    ```yaml theme={null}
    - 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.).
  </Accordion>

  <Accordion title="inferCollectionSchema — Infer schema from data">
    ```yaml theme={null}
    - 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`.
  </Accordion>

  <Accordion title="deleteCollections — Delete collections">
    ```yaml theme={null}
    - 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 |
  </Accordion>
</AccordionGroup>

## Read Operations

<AccordionGroup>
  <Accordion title="findOne — Find a single document">
    ```yaml theme={null}
    - 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 |
  </Accordion>

  <Accordion title="findMany — Find multiple documents">
    ```yaml theme={null}
    - 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                |
  </Accordion>

  <Accordion title="findAndCount — Find with total count">
    ```yaml theme={null}
    - 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` |
  </Accordion>

  <Accordion title="count — Count documents">
    ```yaml theme={null}
    - 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 |
  </Accordion>

  <Accordion title="distinct — Get distinct values">
    ```yaml theme={null}
    - 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 |
  </Accordion>

  <Accordion title="aggregate — Aggregation pipeline">
    ```yaml theme={null}
    - 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 |
  </Accordion>
</AccordionGroup>

## Write Operations

<AccordionGroup>
  <Accordion title="create — Insert a single document">
    ```yaml theme={null}
    - 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.
  </Accordion>

  <Accordion title="bulkCreate — Insert multiple documents">
    ```yaml theme={null}
    - 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 }` |
  </Accordion>
</AccordionGroup>

## Update Operations

<AccordionGroup>
  <Accordion title="updateOne — Update a single document">
    ```yaml theme={null}
    - 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 }`.

    <Warning>
      An empty query without `allowMatchAll: true` throws an error to prevent accidental mass updates.
    </Warning>
  </Accordion>

  <Accordion title="updateMany — Update multiple documents">
    ```yaml theme={null}
    - 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.
  </Accordion>

  <Accordion title="upsert — Insert or update">
    ```yaml theme={null}
    - 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.
  </Accordion>
</AccordionGroup>

## Delete Operations

<AccordionGroup>
  <Accordion title="deleteOne — Delete a single document">
    ```yaml theme={null}
    - 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 }`.

    <Warning>
      An empty query without `allowMatchAll: true` throws an error to prevent accidental mass deletion.
    </Warning>
  </Accordion>

  <Accordion title="deleteMany — Delete multiple documents">
    ```yaml theme={null}
    - run:
        module: collections
        function: deleteMany
        parameters:
          collection: customers
          query:
            status: inactive
        output: result
    ```

    Same parameters as `deleteOne`, but deletes all matching documents.
  </Accordion>
</AccordionGroup>

## Query Syntax

Queries use MongoDB-style operators:

```yaml theme={null}
# 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

```yaml theme={null}
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
```