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

# Impact Simulation

> Run a policy version against historical execution data to measure impact before deploying.

## What is Impact Simulation?

An **Impact Simulation** runs a policy version against a large set of historical execution data, then compares the results against a baseline version. Think of it as a **regression test suite** — before deploying a new version, you can see exactly how it would have performed on past traffic.

<Info>
  **Impact Simulation vs Dry Run:** A [Dry Run](/guides/dry-run) tests **one input** at a time for quick iteration. An Impact Simulation tests **hundreds or thousands** of inputs at once and produces aggregate metrics (match rate, metric deltas, per-rule statistics). Use Dry Runs during development; use Impact Simulation before deployment.
</Info>

## What You Get

| Metric             | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| **Match Rate**     | Percentage of inputs where at least one rule matched          |
| **Per-Rule Stats** | How many times each rule matched and its metric contribution  |
| **Metric Delta**   | Difference in aggregate output between baseline and candidate |
| **Policy Impact**  | Matched count delta, match rate delta, metric value delta     |

## Running a Simulation

### Console

Navigate to a policy group → **Simulation** tab → select candidate version, baseline version, date range → click **Start**.

### CLI

```bash theme={null}
lexq analytics simulation start --json '{
  "policyVersionId": "<candidate-version-id>",
  "dataset": {
    "type": "HISTORICAL",
    "source": "EXECUTION_LOGS",
    "from": "2025-01-01",
    "to": "2025-01-31"
  },
  "options": {
    "baselinePolicyVersionId": "<baseline-version-id>",
    "includeRuleStats": true,
    "maxRecords": 10000,
    "metricConfig": {
      "targetVariable": "payment_amount__delta",
      "aggregationType": "SUM"
    }
  }
}'
```

<Info>
  `metricConfig.targetVariable` points at any key in the response — input facts, mutated facts, or `generatedVariables` (including `{key}__delta` keys produced by `MUTATE_FACT` and `INCREMENT_FACT`). Pick the variable whose aggregate behavior you want to compare across versions.
</Info>

Simulations run asynchronously. Poll until status is `COMPLETED` or `FAILED`:

```bash theme={null}
lexq analytics simulation status --id <simulationId>
```

## Dataset Types

| Type         | Source           | Description                                                |
| ------------ | ---------------- | ---------------------------------------------------------- |
| `HISTORICAL` | `EXECUTION_LOGS` | Re-run past execution inputs from the specified date range |
| `MANUAL`     | `REQUEST_BODY`   | Provide inputs directly in the request body                |
| `UPLOADED`   | `S3_BUCKET`      | Use a pre-uploaded CSV or JSON dataset from S3             |

## File Upload Dataset

Upload a CSV or JSON file to use as simulation input. This is useful when you have custom test data that doesn't come from execution history.

### Supported Formats

<Tabs>
  <Tab title="CSV">
    First row must be a header with fact keys. Each subsequent row is one test record.

    ```csv theme={null}
    payment_amount,customer_tier,is_first_purchase
    150000,VIP,true
    50000,REGULAR,false
    80000,VIP,false
    ```

    **Type inference:** Numbers, booleans (`true`/`false`), and strings are automatically detected. Empty values become `null`. Quoted fields with commas are supported.
  </Tab>

  <Tab title="JSON">
    A JSON array of objects, where each object is a set of facts.

    ```json theme={null}
    [
        {"payment_amount": 150000, "customer_tier": "VIP", "is_first_purchase": true},
        {"payment_amount": 50000, "customer_tier": "REGULAR", "is_first_purchase": false}
    ]
    ```

    Single-object format is also accepted (wraps into a 1-element array):

    ```json theme={null}
    {"facts": {"payment_amount": 150000, "customer_tier": "VIP"}}
    ```
  </Tab>
</Tabs>

**Max file size:** 10 MB

### Download a Template

Don't know the expected columns? Download a template pre-filled with example values based on the version's required facts:

<Tabs>
  <Tab title="Console">
    In the **New Simulation** dialog, select **File Upload (CSV / JSON)** as dataset type. Click **CSV** or **JSON** under "Download template."
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    lexq analytics dataset template \
    --group-id <groupId> \
    --version-id <versionId> \
    --format csv \
    --output template.csv
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    GET /api/v1/partners/analytics/groups/{groupId}/versions/{versionId}/dataset-template?format=csv
    ```
  </Tab>
</Tabs>

### Upload & Run Simulation

<Tabs>
  <Tab title="Console">
    1. Go to **Impact Simulations** → **New Simulation**
    2. Select policy group and target version
    3. Set **Dataset Type** to **File Upload (CSV / JSON)**
    4. Drag & drop your file or click to select
    5. Wait for the **Uploaded** badge
    6. Click **Start Simulation**
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # Step 1: Upload the file
    lexq analytics dataset upload --file ./my-data.csv
    # → path: datasets/my-tenant/a1b2c3d4e5f6.csv

    # Step 2: Start simulation with the uploaded path
    lexq analytics simulation start --json '{
        "policyVersionId": "<versionId>",
        "dataset": {
            "type": "UPLOADED",
            "source": "S3_BUCKET",
            "path": "datasets/my-tenant/a1b2c3d4e5f6.csv"
        },
        "options": {
            "includeRuleStats": true,
            "maxRecords": 10000
        }
    }'
    ```
  </Tab>

  <Tab title="MCP">
    ```
    1. lexq_dataset_template → get expected format
    2. lexq_dataset_upload → upload inline CSV/JSON content
    3. lexq_simulation_start → use returned path with type UPLOADED
    ```
  </Tab>
</Tabs>

## Managing Simulations

```bash theme={null}
lexq analytics simulation list
lexq analytics simulation list --status COMPLETED
lexq analytics simulation cancel --id <simulationId>
lexq analytics simulation export --id <simulationId> --format json
lexq analytics simulation export --id <simulationId> --format csv
```

## Best Practices

1. **Always set a baseline.** Without a baseline version, you only see absolute numbers — no deltas.
2. **Use a meaningful date range.** At least 7 days of data for statistically significant results.
3. **Check `maxRecords`.** Start with 5,000–10,000 for quick validation.
4. **Run simulation before every production deployment.**

<Warning>
  Impact Simulation re-executes rules against historical **input facts** — it does not replay external side effects (webhooks, notifications). Integration calls are always mocked during simulation, and [Decision Replay](/guides/decision-replay) carries the same guarantee.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Dry Run" icon="flask-vial" href="/guides/dry-run">
    Quick single-input validation during development.
  </Card>

  <Card title="A/B Testing" icon="shuffle" href="/guides/ab-testing">
    Compare versions with live production traffic.
  </Card>
</CardGroup>