Impact Simulation

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.

Impact Simulation vs Dry Run: A 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.

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

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"
    }
  }
}'

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.

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

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

CSV
JSON

First row must be a header with fact keys. Each subsequent row is one test record.

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.

A JSON array of objects, where each object is a set of facts.

[
    {"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):

{"facts": {"payment_amount": 150000, "customer_tier": "VIP"}}

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:

Console
CLI
API

In the New Simulation dialog, select File Upload (CSV / JSON) as dataset type. Click CSV or JSON under “Download template.”

lexq analytics dataset template \
--group-id <groupId> \
--version-id <versionId> \
--format csv \
--output template.csv

GET /api/v1/partners/analytics/groups/{groupId}/versions/{versionId}/dataset-template?format=csv

Upload & Run Simulation

Console
CLI
MCP

Go to Impact Simulations → New Simulation
Select policy group and target version
Set Dataset Type to File Upload (CSV / JSON)
Drag & drop your file or click to select
Wait for the Uploaded badge
Click Start Simulation

# 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
    }
}'

lexq_dataset_template → get expected format
lexq_dataset_upload → upload inline CSV/JSON content
lexq_simulation_start → use returned path with type UPLOADED

Managing Simulations

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

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

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 carries the same guarantee.

Getting Started

Core Concepts

Features

What is Impact Simulation?

What You Get

Running a Simulation

Console

CLI

Dataset Types

File Upload Dataset

Supported Formats

Download a Template

Upload & Run Simulation

Managing Simulations

Best Practices

Next Steps

Dry Run

A/B Testing

​What is Impact Simulation?

​What You Get

​Running a Simulation

​Console

​CLI

​Dataset Types

​File Upload Dataset

​Supported Formats

​Download a Template

​Upload & Run Simulation

​Managing Simulations

​Best Practices

​Next Steps

Dry Run

A/B Testing

What is Impact Simulation?

What You Get

Running a Simulation

Console

CLI

Dataset Types

File Upload Dataset

Supported Formats

Download a Template

Upload & Run Simulation

Managing Simulations

Best Practices

Next Steps