# Record & File Actions

The `record` family reads and writes table records (single and batch). The `file` family performs storage operations — upload, download, generation, and transformation.

## Record — Table CRUD

Operators cover single-row CRUD plus batch operations. Reads/updates/deletes use a [condition group](/en/docs/automation-flow-control) `filter`; creates/updates carry a `data` map. Batch operators iterate over an `items` array (a template resolving to a list).

| Operator      | Props                                                  | Description                                             |
| ------------- | ------------------------------------------------------ | ------------------------------------------------------- |
| `create`      | `table`, `data`                                        | Insert one record.                                      |
| `read`        | `table`, `filter`                                      | Read records matching the filter.                       |
| `update`      | `table`, `data`, `filter`                              | Update records matching the filter.                     |
| `delete`      | `table`, `filter`                                      | Soft-delete records matching the filter.                |
| `upsert`      | `table`, `data`, `filter`                              | Update if a match exists, otherwise create.             |
| `batchCreate` | `table`, `items`, `batchSize?`, `continueOnItemError?` | Insert many records from an array.                      |
| `batchUpdate` | `table`, `items`, `batchSize?`, `continueOnItemError?` | Update many records from an array.                      |
| `batchUpsert` | `table`, `items`, `batchSize?`, `continueOnItemError?` | Upsert many records from an array.                      |
| `batchDelete` | `table`, `filter`, `limit?`                            | Delete records matching the filter (capped by `limit`). |

```yaml
- name: logActivity
  type: record
  operator: create
  props:
    table: activity_log
    data:
      action: 'order.created'
      order_id: '{{trigger.data.id}}'
      occurred_at: '{{now}}'
```

```yaml
- name: importRows
  type: record
  operator: batchCreate
  props:
    table: contacts
    items: '{{parseLeads.result}}'
    batchSize: 100
    continueOnItemError: true
```

:::callout
**Record actions respect table permissions and soft-delete.** Writes go through the same RBAC and validation as the [records API](/en/docs/records-overview); `delete` is soft by default (sets `deleted_at`). See [Table Permissions](/en/docs/table-permissions) and [Records CRUD](/en/docs/records-crud).
:::

## File — Storage Operations

Fourteen operators spanning storage, metadata/access, generation, and advanced transforms. They operate against Sovrium's configured storage (local or S3) — see [File Operations](/en/docs/file-operations).

### Storage

| Operator   | Props                             | Description                    |
| ---------- | --------------------------------- | ------------------------------ |
| `upload`   | `source`, `path?`, `contentType?` | Upload a file to storage.      |
| `download` | `key`                             | Download a stored file by key. |
| `delete`   | `key`                             | Delete a stored file.          |
| `copy`     | `source`, `destination`           | Copy a stored file.            |
| `move`     | `source`, `destination`           | Move/rename a stored file.     |
| `list`     | `prefix`, `limit?`                | List files under a prefix.     |

### Metadata & Access

| Operator      | Props                             | Description                                                                                          |
| ------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `getMetadata` | `key`                             | Read a file's metadata (size, content type, …).                                                      |
| `signUrl`     | `key`, `expiresIn?`, `operation?` | Generate a time-limited signed URL (`download` / `upload`). See [Signed URLs](/en/docs/signed-urls). |

### Generation

| Operator      | Props                                                                                    | Description                                                    |
| ------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `generatePdf` | `template`, `filename`, `data?`, `pageSize?`, `orientation?`, `margins?`, `destination?` | Render an HTML template to a PDF (`A4`/`A3`/`Letter`/`Legal`). |
| `generateCsv` | `data`, `filename`, `columns?`, `delimiter?`, `includeHeaders?`, `destination?`          | Generate a CSV from an array.                                  |

### Advanced

| Operator         | Props                                                                                 | Description                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `parseCsv`       | `source`, `columns?`, `skipRows?`, `delimiter?`                                       | Parse a CSV file into an array of rows.                                                                  |
| `extractText`    | `source`, `format?`                                                                   | Extract text from a document (`plain` / `markdown`).                                                     |
| `transformImage` | `source`, `width?`, `height?`, `fit?`, `format?`, `quality?`, `crop?`, `destination?` | Resize/convert an image (`jpeg`/`png`/`webp`/`avif`). See [Image Transforms](/en/docs/image-transforms). |
| `compress`       | `files`, `filename`, `destination?`                                                   | Zip multiple files into one archive.                                                                     |

```yaml
- name: invoice
  type: file
  operator: generatePdf
  props:
    template: invoice-template
    filename: 'invoice-{{trigger.data.id}}.pdf'
    data: '{{trigger.data}}'
    pageSize: A4
    orientation: portrait
    destination: invoices/
```

```yaml
- name: thumbnail
  type: file
  operator: transformImage
  props:
    source: '{{upload.result.key}}'
    width: 320
    fit: cover
    format: avif
    quality: 70
```

:::callout
**Eco-aware image transforms.** Default to `avif` and lazy delivery for generated images; image transcoding is governed by the operator-controlled `ECO_IMAGE_FORMAT` env. See [Image Transforms](/en/docs/image-transforms).
:::

## Related Pages

- [Records Overview](/en/docs/records-overview) — the records data model and API.
- [Records CRUD](/en/docs/records-crud) — the create/read/update/delete contract.
- [File Operations](/en/docs/file-operations) — the storage layer behind file actions.
- [Signed URLs](/en/docs/signed-urls) — time-limited access links.
- [Image Transforms](/en/docs/image-transforms) — on-the-fly image processing.