# uip pm ingestions, uip pm transformations

> Syntax and options for triggering and inspecting Process Mining data ingestions and dbt transformations with `uip pm ingestions` and `uip pm transformations`.

Part of the [`uip pm`](./uip-pm.md) tool. `ingestions` loads uploaded data files into a process app; `transformations` manages and runs the dbt SQL models that reshape ingested data into the app's queryable tables. Both support `--wait` to block until a run finishes — see [Concepts](./uip-pm.md#concepts) on the parent page.

## Synopsis

```text
uip pm ingestions create <app-id> [--stage dev|published] [--file-format csv|tsv] [--field-delimiter <char>] [--quote-character <char>] [--encoding utf-8|iso-8859-1] [--wait] [--timeout <s>] [--poll-interval <s>]
uip pm ingestions cancel <app-id> <ingestion-id> [--stage dev|published]
uip pm ingestions logs <app-id> <ingestion-id> [--stage dev|published] [--limit <n>] [--offset <n>]

uip pm transformations list <app-id> [--stage dev|published]
uip pm transformations get <app-id> <path> [--stage dev|published] [--destination <file>]
uip pm transformations create <app-id> <path> --file <local-file> [--stage dev|published]
uip pm transformations update <app-id> <path> --file <local-file> --etag <etag> [--stage dev|published]
uip pm transformations run <app-id> [--model <path>] [--wait] [--timeout <s>] [--poll-interval <s>]
uip pm transformations apply <app-id> [--stage dev|published] [--wait] [--timeout <s>] [--poll-interval <s>]
uip pm transformations cancel <app-id>
uip pm transformations status <app-id>
uip pm transformations logs <app-id>
```

## uip pm ingestions create

Trigger an ingestion of the uploaded data files.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |

### Options

| Long | Value | Default | Description |
|---|---|---|---|
| `--stage <stage>` | `dev` \| `published` | `dev` | App stage to ingest into. |
| `--file-format <format>` | `csv` \| `tsv` | `csv` | Data file format. |
| `--field-delimiter <char>` | string | `,` | Field delimiter in the data files. |
| `--quote-character <char>` | string | `"` | Quote character enclosing fields. |
| `--encoding <encoding>` | `utf-8` \| `iso-8859-1` | `utf-8` | File encoding. |
| `--wait` | flag | off | Block until the ingestion reaches a terminal state; exit non-zero on failure. |
| `--timeout <seconds>` | integer | `1800` | Max seconds to wait when `--wait` is set. |
| `--poll-interval <seconds>` | integer | `5` | Seconds between status polls when `--wait` is set. |

### Example

```bash
uip pm ingestions create 9c46289e --file-format csv --encoding iso-8859-1
```

### Data shape (--output json)

Without `--wait`:

```json
{ "Code": "PmIngestionsCreate", "Data": { "Status": "Accepted", "Message": "Ingestion started. Poll 'uip pm apps list' (LastIngestion) for progress." } }
```

With `--wait`:

```json
{ "Code": "PmIngestionsCreate", "Data": { "Status": "SUCCESS", "IngestionId": "1d7e1421" } }
```

On `--wait` failure, exits non-zero with the ingestion's own error-log lines (via `ingestions logs`) folded into the failure message.

## uip pm ingestions cancel

Cancel an ingestion that is still running.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |
| `<ingestion-id>` | yes | Ingestion ID (`uip pm apps get <app-id>` shows `LastIngestion`). |

### Options

| Long | Value | Default | Description |
|---|---|---|---|
| `--stage <stage>` | `dev` \| `published` | `dev` | App stage the ingestion runs on. |

### Example

```bash
uip pm ingestions cancel 9c46289e 1d7e1421
```

### Data shape (--output json)

```json
{ "Code": "PmIngestionsCancel", "Data": { "AppId": "9c46289e", "IngestionId": "1d7e1421", "Status": "Cancelling" } }
```

## uip pm ingestions logs

Get the logs of an ingestion run.

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |
| `<ingestion-id>` | yes | Ingestion ID. |

### Options

| Long | Value | Default | Description |
|---|---|---|---|
| `--stage <stage>` | `dev` \| `published` | `dev` | App stage the ingestion ran on. |
| `--limit <number>` | integer | `100` | Max log entries to fetch (page size). |
| `--offset <number>` | integer | `0` | Number of log entries to skip before the page. |

### Example

```bash
uip pm ingestions logs 9c46289e 1d7e1421 --limit 50 --offset 50
```

### Data shape (--output json)

```json
{ "Code": "PmIngestionsLogs", "Data": [{ "Message": "Data run started" }] }
```

## uip pm transformations list

List the transformation (dbt model) files of a process app.

| Name/Option | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |
| `--stage <stage>` | no | `dev` \| `published`, default `dev`. |

```json
{ "Code": "PmTransformationsList", "Data": {} }
```

## uip pm transformations get

Get the content of a transformation file, plus its ETag — which `update` requires as `--etag`.

| Name/Option | Required | Purpose |
|---|---|---|
| `<app-id>` | yes | Process app ID. |
| `<path>` | yes | Transformation file path, e.g. `models/Cases.sql`. |
| `--stage <stage>` | no | `dev` \| `published`, default `dev`. |
| `--destination <local-file>` | no | Write content to this local file instead of the output envelope. |

```json
{ "Code": "PmTransformationsGet", "Data": { "Path": "models/Cases.sql", "ETag": "W/\"...\"", "Content": "select ..." } }
```

## uip pm transformations create

Create a new transformation file from a local file. Use `update` to modify an existing one — this fails if the path already exists.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--file <local-file>` | path | **yes** | Local file with the new content. |
| `--stage <stage>` | `dev` \| `published` | no | Default `dev`. |

```bash
uip pm transformations create 9c46289e models/Workload.sql --file ./Workload.sql
```

```json
{ "Code": "PmTransformationsCreate", "Data": { "Path": "models/Workload.sql", "ETag": "W/\"...\"" } }
```

## uip pm transformations update

Update a transformation file from a local file (ETag-safe).

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--file <local-file>` | path | **yes** | Local file with the new content. |
| `--etag <etag>` | string | **yes** | ETag of the file this edit is based on, from `transformations get`. |
| `--stage <stage>` | `dev` \| `published` | no | Default `dev`. |

```bash
uip pm transformations update 9c46289e models/Cases.sql --file ./Cases.sql --etag 'W/"639204059477096903"'
```

```json
{ "Code": "PmTransformationsUpdate", "Data": { "Path": "models/Cases.sql", "ETag": "W/\"639209312397638135\"" } }
```

A stale `--etag` fails with a conflict — re-read via `transformations get`, redo the edit, and retry.

## uip pm transformations run

Run the dbt transformations on the dev stage — builds only changed/dependent models. Use `apply` to force a full re-run on already-ingested data.

### Options

| Long | Value | Default | Description |
|---|---|---|---|
| `--stage <stage>` | `dev` | `dev` | Only `dev` is supported. |
| `--model <model-path>` | path | — | Run only this model (e.g. `models/Cases.sql`) and its dependents. Omit to run everything. |
| `--wait` | flag | off | Block until the build reaches a terminal state; exit non-zero on failure (auto-prints the dbt error). |
| `--timeout <seconds>` | integer | `1800` | Max seconds to wait. |
| `--poll-interval <seconds>` | integer | `5` | Seconds between polls. |

### Example

```bash
uip pm transformations run 9c46289e --model models/Cases.sql
```

### Data shape (--output json)

```json
{ "Code": "PmTransformationsRun", "Data": { "Status": "Accepted", "Message": "Build started. Re-run with --wait to block until it finishes, or poll 'uip pm transformations status 9c46289e'." } }
```

## uip pm transformations cancel

Cancel the dbt build currently running on dev.

```bash
uip pm transformations cancel 9c46289e
```

```json
{ "Code": "PmTransformationsCancel", "Data": { "AppId": "9c46289e", "Status": "Cancelling" } }
```

## uip pm transformations apply

Re-run the full data transformation on already-ingested data (unlike `run`, which builds only changed dev models).

| Long | Value | Default | Description |
|---|---|---|---|
| `--stage <stage>` | `dev` \| `published` | `dev` | App stage. |
| `--wait` | flag | off | Block until the transform reaches a terminal state; exit non-zero on failure. |
| `--timeout <seconds>` | integer | `1800` | Max seconds to wait. |
| `--poll-interval <seconds>` | integer | `5` | Seconds between polls. |

```bash
uip pm transformations apply 9c46289e
```

```json
{ "Code": "PmTransformationsApply", "Data": { "Status": "Accepted", "Message": "Transform started. Poll 'uip pm apps list' (LastIngestion) for progress." } }
```

## uip pm transformations status

Get the status of the current/last transformation build.

```bash
uip pm transformations status 9c46289e
```

```json
{ "Code": "PmTransformationsStatus", "Data": {} }
```

## uip pm transformations logs

Get the logs of the current/last transformation build.

```bash
uip pm transformations logs 9c46289e
```

```json
{ "Code": "PmTransformationsLogs", "Data": {} }
```

## Related

- [`uip pm`](./uip-pm.md) — overview, `apps`, `files`.
- [`apps model`](./uip-pm-apps-model.md) — model/field/data-mapping changes that need re-ingestion or re-transformation to take effect.
- [`conformance`, `deviations` & `query`](./uip-pm-analysis.md) — analyze the result.

## See also

- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)