# Using this Actor from an agent

If you are an agent configuring this Actor, write a config file and pass it
as `pipeline`. Set `sourceDatasetId` to the same dataset the file's
`source.dataset_id` names. The source is
`{"format": "apify_dataset", "dataset_id": "<id>"}`.

Set `dryRun` to true to check the file. That run writes nothing, reads every
input, and returns the document, the output columns, and every configuration
error. It does not apply the spending limit or the size check.

Set `previewRows` (1–1,000) to run the real operations on that many items
and write nothing. The columns in that sample can differ from the whole
dataset. Do not set `previewRows` together with `dryRun`.

The form calls the file **Config file** (`pipeline`) or **Config file URL**
(`pipelineUrl`, an `https://` URL). Use one, not both. When either is set,
`job` is ignored.

Every other dataset the file reads must be listed in `additionalDatasetIds`.
A dataset named only inside the file cannot be read.

The JSON Schema lists each operation's own fields (`column`, `on_error`, and
the rest). A file that does not match it is not a file this Actor can run.
A file that matches can still be refused: a named column is missing, or an
operation that changes the row count sits between two operations that can
reject rows.

Read a finished run from `OUTPUT` in the run's key-value store.

- `outcome` is `completed`, `completed_with_rejects`, or `unreconciled`. A run that did not finish is `failed`.
- `reconciles` is false when the counts do not add up.
- `outputs.accepted.dataset` is the cleaned rows.
- `outputs.quarantined` is null only when the run has no quarantine output. Otherwise `outputs.quarantined.dataset` is that dataset's name and `outputs.quarantined.rows` is how many rows were rejected. The dataset is created only when a row was rejected.
- `rows.accepted`, `rows.quarantined`, `rows.dropped`, and `rows.in` are the counts.
- `document` is the file that ran.
- `output_schema` is the columns.

A rejection names the field and not the value while `redactValues` is true,
which is the default. The rejected row still has the value in its column.
`original_value` inside `__errors` is null.

## Have a model write the file

1. Copy the prompt below.
2. Add a few rows and what should be done.
3. Put the result in `pipeline` and run with `dryRun` true.
4. If it reports errors, send those errors back and ask for a corrected file.
   A dry run writes nothing and lists every configuration error at once.

> You are writing a PureStream config file, the JSON document for an Apify
> Actor that cleans datasets. The JSON Schema is at
> `https://api.apify.com/v2/key-value-stores/AhmedMohamed~purestream-contract/records/pipeline-document.schema.json`
> and the operation reference is at
> `https://api.apify.com/v2/key-value-stores/AhmedMohamed~purestream-contract/records/pipeline-document.md`.
> Read both, then write the document. Rules: every operation acts on a column
> I name. Never guess a column from its name. Never infer a number or date
> format; state it. The source is `{"format": "apify_dataset", "dataset_id":
"..."}`. An operation that can reject rows needs a `quarantine` destination.
> These operations change the row count and must not sit between two
> operations that can reject rows: `deduplicate`, `filter`, `limit`,
> `drop_nulls`, `group_by`, `union`, `join`, `explode`. Put them after the
> last operation that can reject. Output only the JSON.
>
> My data looks like this: _(paste a few rows)_
> What I want: _(describe it)_

A Job run with `dryRun` true returns, in `document`, the file that job
built. Hand that file over with the description when you want a working
example.