Refresh & Execution

Refresh a Dataset from its Datasource, and benchmark the query behind it.

POST /api/datasets/{id}/_refresh

Refresh the Dataset: run its query against the Datasource and rebuild the search index from the results.

Authentication: Required

Permission: dataset:refresh (delegates to dataset:write: Data Wizard or above on the owning team)

Path Parameters:

Parameter	Type	Description
id	string	Dataset UUID or ownerId:slug natural id

Request Body (all optional):

Field	Type	Default	Description
params	object	—	Query parameter values for this run
progress	string	—	Progress channel id for tracking
syncFields	boolean	true	Rebuild field definitions from the new mapping
updateTypeMapping	boolean	true	Store each field's index type mapping
disableRefreshInterval	boolean	true	Suspend index refresh during the bulk write (faster indexing)

Refresh a Dataset from its DatasourcePOST /api/datasets/admin:northwind-orders/_refresh

Runs the query, rebuilds the index, and syncs fields. Responds 200 with an empty body when the refresh completes; errors answer with the failure.

Request body

{}

Response · 200 · no body

Captured from the API examples test suite; ids and timestamps are normalized.

Behavior:

1. Executes the Dataset query (with params applied)
2. Streams results into a fresh index, then swaps it in
3. Syncs field definitions and updates records/dataUpdatedAt
4. Rows that fail indexing are recorded as exceptions
5. Responds 200 with an empty body when complete

Long-Running Operation

The route has no socket timeout; the response arrives when the refresh finishes. Pass progress to follow along.

There is also an internal variant, POST /api/datasets/{id}/_refresh-internal, used by Informer's own template and job machinery. It is marked internal and answers 404 over HTTP.

---

POST /api/datasets/{id}/_run

Legacy variant of _refresh: first persists the payload's params onto the Dataset, then performs the same full refresh.

Authentication: Required

Permission: dataset:write (Data Wizard or above on the owning team)

Request Body:

Field	Type	Description
params	object	Saved onto the Dataset, then used by the refresh
progress	string	Progress channel id

Run a DatasetPOST /api/datasets/admin:northwind-orders/_run

Legacy variant of _refresh: persists params onto the Dataset first, then performs the same full refresh. Responds 200 with an empty body.

Request body

{}

Response · 200 · no body

Captured from the API examples test suite; ids and timestamps are normalized.

Prefer _refresh: it applies params to the run without rewriting the Dataset's stored parameters.

---

POST /api/datasets/{id}/_benchmark

Time the Dataset's query without touching its real index.

Authentication: Required

Permission: dataset:refresh (Data Wizard or above on the owning team)

Request Body:

Field	Type	Description
params	object	Query parameter values for the run
config	object	Benchmark options, see below
progress	string	Progress channel id

Benchmark config:

Field	Type	Description
limit	integer	Cap the number of rows read from the Datasource
flows	boolean	Include the Dataset's flow steps in the run
index	boolean	Also stream results into a scratch index (deleted afterwards), measuring indexing cost too

Response: records read, elapsed time in seconds, and whether any rows errored.

Benchmark the Dataset queryPOST /api/datasets/admin:northwind-orders/_benchmark

config: limit caps the rows read, flows: true includes flow steps, index: true also writes into a scratch index (deleted afterwards). Reports records, elapsed seconds, and whether rows errored.

Request body

{
  "config": {
    "limit": 500
  }
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/_benchmark"
    }
  },
  "records": 500,
  "time": 0.5,
  "containsErrors": false,
  "errorMessage": {}
}

Captured from the API examples test suite; ids and timestamps are normalized.

There is also an internal variant, POST /api/datasets/{id}/_benchmark-internal, which answers 404 over HTTP.

---

Query Parameters

Dataset queries reference parameters whose values can be supplied per run (params on _refresh/_benchmark) or saved on the Dataset (see Settings). Native SQL queries reference them as $paramName; the stored parameter definitions conventionally carry name, dataType, and defaultValue.