Dataset References
Manage associations between reports and datasets, including filters, aliases, and snapshot settings.
Overview
Reports can reference multiple datasets, each with:
- Alias - Unique identifier within the report (e.g.,
orders,customers) - Label - Display name for the dataset
- Filter - Applied criteria to limit data
- Chips - Filter UI components
- Snapshot Settings - Configuration for including historical dataset snapshots
GET /api/reports/{id}/dataset-refs
Get all dataset references for a report with field metadata and record counts.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Report ID |
Response:
Each binding (keyed by alias) with its dataset, filtered record count, and overall count. Counts are -1 when the dataset is not indexed.
List dataset referencesGET /api/reports/admin:sales-overview/dataset-refs
Each binding (keyed by alias) with its dataset, filtered record count, and overall count. Counts are -1 when the dataset is not indexed.
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/reports/admin%3Asales-overview/dataset-refs"
}
},
"start": 0,
"count": 1,
"total": 1,
"_embedded": {
"inf:report-dataset": [
{
"_links": {
"self": {
"href": "https://informer.example.com/api/reports/admin%3Asales-overview/dataset-refs/orders"
}
},
"id": "orders",
"filter": {},
"chips": [],
"alias": "orders",
"label": "Orders",
"tenant": "acme",
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"reportId": "00000000-0000-4000-8000-000000000001",
"datasetId": "00000000-0000-4000-8000-000000000002",
"snapshots.tenant": null,
"snapshots.id": null,
"snapshots.type": null,
"snapshots.includeLatest": null,
"snapshots.n": null,
"snapshots.userSettingsId": null,
"snapshots.jobDatasetId": null,
"snapshots.assistantDatasetId": null,
"snapshots.reportDatasetId": null,
"snapshots.createdAt": null,
"snapshots.updatedAt": null,
"snapshots.snapshotDatasets.tenant": null,
"snapshots.snapshotDatasets.id": null,
"snapshots.snapshotDatasets.snapshotSettingsId": null,
"snapshots.snapshotDatasets.datasetId": null,
"snapshots.snapshotDatasets.createdAt": null,
"snapshots.snapshotDatasets.updatedAt": null,
"count": -1,
"countWithoutSnapshots": 1000,
"overallCount": 1000,
"_embedded": {
"inf:dataset": {
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002"
},
"inf:draft": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/draft"
},
"inf:run": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/_run"
},
"inf:benchmark": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/_benchmark"
},
"inf:refresh": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/_refresh"
},
"inf:data": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/data{?start,limit,q,sort,show,report}",
"templated": true
},
"inf:user-settings": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/settings"
},
"inf:query": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000003"
},
"inf:owner": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/owner"
},
"inf:search": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/_search{?query,_source,sort,from,size,searchType,aggs,report,aggregations,alias,snapshots}",
"templated": true
},
"inf:mapping": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/mapping"
},
"inf:job-templates": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/job-templates"
},
"inf:fields": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/fields"
},
"inf:count": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/count"
},
"inf:comments": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/comments"
},
"inf:visuals": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/visuals"
},
"inf:visual-templates": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/visual-templates"
},
"inf:dataset-tags": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/tags"
},
"inf:dataset-tag": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/tags/{tagId}",
"templated": true
},
"inf:discover": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/discover"
},
"inf:filters": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/filters"
},
"inf:dataset-shares": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/shares"
},
"inf:flow": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/flow"
},
"inf:group": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/group"
},
"inf:group-rows": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/group-rows"
},
"inf:dataset-share": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/shares/{principalId}",
"templated": true
},
"inf:import": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/_import"
},
"inf:exceptions": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/_exceptions"
},
"inf:search-aggregates": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/_search-aggregates"
},
"inf:exporters": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/exporters"
},
"inf:favorite": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/favorite"
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/_export"
},
"edit": {
"href": "https://informer.example.com/api/reports/admin%3Anorthwind-orders/_edit"
}
},
"naturalId": "admin:northwind-orders",
"permissions": {
"edit": true,
"share": true,
"delete": true,
"write": true,
"addVisual": true,
"deleteVisual": true,
"changeOwner": true,
"copy": true,
"rename": true,
"refresh": true,
"modifyFlows": true,
"replaceFile": true,
"modifySettings": true,
"createDataView": true,
"assignTags": true,
"createFilter": true,
"scriptFields": true,
"setIndex": false
},
"id": "00000000-0000-4000-8000-000000000002",
"tenant": "acme",
"ownerId": "admin",
"slug": "northwind-orders",
"name": "Northwind Orders",
"description": "A dataset consisting of all orders in the northwind system (public schema)",
"embedded": false,
"esIndex": null,
"esIndexName": "northwind-orders",
"esType": "data",
"records": -1,
"size": "524288",
"source": "northwind-datasets",
"sourceId": null,
"params": {},
"dataUpdatedAt": "2026-01-15T16:20:00.000Z",
"dataExpiresAt": null,
"ttl": null,
"append": false,
"shared": false,
"timestampField": null,
"lastDurationMillis": "1500",
"windowSize": 500,
"settings": {},
"flow": [],
"esId": null,
"lastQueriedAt": "2026-01-15T16:20:00.000Z",
"esWorkers": 1,
"datasetFieldReportAccess": false,
"parentId": null,
"templateProcessorId": null,
"deleteDate": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": null,
"reportId": "00000000-0000-4000-8000-000000000001",
"queryId": "00000000-0000-4000-8000-000000000003",
"editingId": null,
"folderId": null,
"query": {
"naturalId": "00000000-0000-4000-8000-000000000003",
"fields": null,
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": true,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000003",
"tenant": "acme",
"ownerId": "admin",
"slug": null,
"name": null,
"description": null,
"shared": false,
"embedded": true,
"source": null,
"sourceId": null,
"settings": {},
"inputs": null,
"language": "informer",
"flow": [
{
"calculatedField": {
"alias": "salesperson",
"label": "Salesperson",
"script": "FirstName + ' ' + LastName"
}
},
{
"calculatedField": {
"alias": "orderAmount",
"label": "Order Amount",
"script": "UnitPrice * Quantity"
}
},
{
"calculatedField": {
"alias": "shipState",
"label": "Ship State",
"script": "ShipCountry === \"USA\" ? ShipRegion : null"
}
}
],
"payload": {
"fields": [
{
"id": "OrderDate",
"path": "OrderDate",
"type": "field",
"label": "Order Date",
"fieldId": "OrderDate",
"grouped": false,
"linkRef": null,
"rawType": "date",
"dataType": "date_tz",
"distinct": false,
"position": 0,
"aggregate": null
},
{
"id": "RequiredDate",
"path": "RequiredDate",
"type": "field",
"label": "Required Date",
"fieldId": "RequiredDate",
"grouped": false,
"linkRef": null,
"rawType": "date",
"dataType": "date_tz",
"distinct": false,
"position": 1,
"aggregate": null
},
{
"id": "ShipAddress",
"path": "ShipAddress",
"type": "field",
"label": "Ship Address",
"fieldId": "ShipAddress",
"grouped": false,
"linkRef": null,
"rawType": "character varying",
"dataType": "keyword_text",
"distinct": false,
"position": 2,
"aggregate": null
},
"… 10 more items (13 total) — omitted from docs"
],
"source": {
"id": "00000000-0000-4000-8000-000000000004:public+orders",
"schemaId": "public",
"mappingId": "orders"
},
"groupBy": [],
"linkRefs": [
{
"id": "employees",
"linkId": "00000000-0000-4000-8000-000000000004:public+orders:employees",
"details": {
"id": "00000000-0000-4000-8000-000000000004:public+orders:employees",
"defn": [
{
"toField": "EmployeeID",
"operator": "=",
"toSchema": "public",
"fromField": "EmployeeID",
"toMapping": "employees",
"fromSchema": "public",
"fromMapping": "orders"
}
],
"toId": "00000000-0000-4000-8000-000000000004:public+employees",
"type": "sql",
"fromId": "00000000-0000-4000-8000-000000000004:public+orders",
"linkId": "employees"
}
},
{
"id": "order-details",
"linkId": "00000000-0000-4000-8000-000000000004:public+orders:order-details",
"details": {
"id": "00000000-0000-4000-8000-000000000004:public+orders:order-details",
"defn": [
{
"toField": "OrderID",
"operator": "=",
"toSchema": "public",
"fromField": "OrderID",
"toMapping": "order_details",
"fromSchema": "public",
"fromMapping": "orders"
}
],
"toId": "00000000-0000-4000-8000-000000000004:public+order_details",
"type": "sql",
"fromId": "00000000-0000-4000-8000-000000000004:public+orders",
"linkId": "order-details"
}
},
{
"id": "order-details/products",
"linkId": "00000000-0000-4000-8000-000000000004:public+order_details:products",
"details": {
"id": "00000000-0000-4000-8000-000000000004:public+order_details:products",
"defn": [
{
"toField": "ProductID",
"operator": "=",
"toSchema": "public",
"fromField": "ProductID",
"toMapping": "products",
"fromSchema": "public",
"fromMapping": "order_details"
}
],
"toId": "00000000-0000-4000-8000-000000000004:public+products",
"type": "sql",
"fromId": "00000000-0000-4000-8000-000000000004:public+order_details",
"linkId": "products"
}
}
]
},
"defnUpdatedAt": null,
"limit": -1,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": "00000000-0000-4000-8000-000000000004",
"editingId": null,
"folderId": null,
"datasource": {
"defaultLinkType": "sql",
"aiSystemMessage": "This is a PostgresSQL database. Identifiers are case-sensitive by default. \n Always surround all column names, table names, and schema names in double-quotes (\"). \n For example:\n SELECT \"OrderID\", \"ShipCountry\" FROM \"public\".\"orders\" WHERE \"ShipCity\" = 'Raleigh';\n ---",
"family": "sql",
"languages": [
"informer",
"sql",
"distinctValue",
"… 2 more items (5 total) — omitted from docs"
],
"naturalId": "admin:northwind",
"image": "/opt/informer/packages/informer-server/modules/sql/images/postgres.svg",
"compatibility": [],
"permissions": {
"assignTags": true,
"edit": true,
"delete": true,
"share": true,
"write": true,
"changeOwner": true,
"ping": true,
"scan": true,
"downloadSchema": true,
"importData": true,
"importSchema": true,
"rename": true,
"editConnection": true,
"createLink": true,
"setWrite": true,
"createSuite": true,
"createFieldExpression": true,
"createMapping": false,
"bundle": true,
"query": true
},
"id": "00000000-0000-4000-8000-000000000004",
"tenant": "acme",
"ownerId": "admin",
"slug": "northwind",
"name": "Northwind",
"description": null,
"embedded": false,
"type": "postgres",
"connection": {
"host": "localhost",
"pool": {
"max": 5,
"min": 0,
"idle": 10000,
"acquire": 10000
},
"port": 5432,
"user": "northwinduser",
"database": "northwind",
"password": "encrypted:iv:0000000000000000",
"idleTimeoutMillis": 7
},
"scannedAt": "2026-01-15T16:20:00.000Z",
"schemaUpdatedAt": "2026-01-15T16:20:00.000Z",
"rescanRequired": false,
"shared": false,
"schemas": [
"public"
],
"source": null,
"sourceId": null,
"settings": {
"multiSchema": false,
"useFakeData": false,
"remoteQueryBatchSize": {
"multiKey": 500,
"singleKey": 500
},
"usePreparedStatements": false
},
"data": null,
"appId": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"folderId": null,
"fileId": null,
"shares": []
}
},
"_embedded": {
"inf:field": [
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/fields/RequiredDate"
}
},
"label": "Required Date",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000005",
"tenant": "acme",
"name": "RequiredDate",
"datasetId": "00000000-0000-4000-8000-000000000002",
"position": 1,
"dataType": "date",
"script": null,
"typeMapping": {
"type": "date"
},
"formatOptions": null,
"lockFieldId": true,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/fields/Quantity"
}
},
"label": "Order Detail Quantity",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000006",
"tenant": "acme",
"name": "Quantity",
"datasetId": "00000000-0000-4000-8000-000000000002",
"position": 11,
"dataType": "integer",
"script": null,
"typeMapping": {
"type": "integer"
},
"formatOptions": null,
"lockFieldId": true,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000002/fields/ShippedDate"
}
},
"label": "Shipped Date",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000007",
"tenant": "acme",
"name": "ShippedDate",
"datasetId": "00000000-0000-4000-8000-000000000002",
"position": 7,
"dataType": "date",
"script": null,
"typeMapping": {
"type": "date"
},
"formatOptions": null,
"lockFieldId": true,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null
},
"… 13 more items (16 total) — omitted from docs"
],
"inf:filter": []
}
}
}
}
]
}
}
Response Fields:
| Field | Type | Description |
|---|---|---|
id | string | Alias (same as alias) |
alias | string | Unique identifier within report |
datasetId | string | Referenced dataset ID |
label | string | Display name |
filter | object | Applied filter criteria |
chips | array | Filter UI components |
count | integer | Filtered record count (with report-level filters) |
countWithoutSnapshots | integer | Count excluding snapshot data |
overallCount | integer | Count including all snapshots |
snapshots | object | Snapshot configuration (if enabled) |
dataset | object | Full dataset metadata including fields |
POST /api/reports/{id}/dataset-refs
Add a new dataset reference to a report.
Authentication: Required
Permissions: report:write
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Report ID |
Request Body:
{
"reportId": "team:sales-dashboard",
"datasetId": "customers-2024",
"alias": "customers",
"label": "Customer Data",
"filter": {
"criteria": [
{
"field": "region",
"op": "eq",
"value": "West"
}
]
},
"chips": [
{
"field": "region",
"label": "Region: West"
}
],
"snapshots": {
"includeLatest": true,
"type": "n",
"n": 3,
"snapshotDatasets": ["snapshot-1", "snapshot-2"]
}
}
Required Fields:
| Field | Type | Description |
|---|---|---|
reportId | string | Report ID |
datasetId | string | Dataset to reference |
alias | string | Unique alias (1-150 chars, alphanumeric + underscore/hyphen, must start with letter/number/underscore) |
label | string | Display name (1-150 chars) |
Optional Fields:
| Field | Type | Default | Description |
|---|---|---|---|
filter | object | {} | Filter criteria |
chips | array | [] | Filter UI components |
snapshots | object | null | Snapshot settings |
Snapshot Settings:
| Field | Type | Default | Description |
|---|---|---|---|
includeLatest | boolean | true | Include the latest dataset data |
type | string | - | Snapshot selection type: n (last N snapshots) or null |
n | integer | 1 | Number of recent snapshots to include (when type is n) |
snapshotDatasets | array | [] | Specific snapshot dataset IDs to include |
Response:
Responds 201 Created with the new binding and a Location header.
Add a dataset referencePOST /api/reports/admin:sales-overview/dataset-refs
Binds another dataset (or the same one under a new alias) to the report. reportId is the report UUID. Responds 201 with a Location header.
Request body
{
"reportId": "00000000-0000-4000-8000-000000000001",
"datasetId": "00000000-0000-4000-8000-000000000002",
"alias": "orders_archive",
"label": "Orders (Archive)"
}
Response · 201
{
"_links": {
"self": {
"href": "https://informer.example.com/api/reports/00000000-0000-4000-8000-000000000003/dataset-refs/"
}
},
"id": "00000000-0000-4000-8000-000000000003",
"tenant": "acme",
"reportId": "00000000-0000-4000-8000-000000000001",
"datasetId": "00000000-0000-4000-8000-000000000002",
"alias": "orders_archive",
"label": "Orders (Archive)",
"filter": {},
"chips": [],
"updatedAt": "2026-01-15T16:20:00.000Z",
"createdAt": "2026-01-15T16:20:00.000Z"
}
Validation:
- Alias must be unique within the report
- Alias must match regex:
^[a-zA-Z0-9_][a-zA-Z0-9_-]*$ - Referenced dataset must exist and be accessible
- Snapshot dataset IDs must belong to valid snapshots of the specified dataset
GET /api/reports/{id}/dataset-refs/{dataset}
Get a specific dataset reference by alias.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Report ID |
dataset | string | Dataset alias |
Response:
Get a single dataset referenceGET /api/reports/admin:sales-overview/dataset-refs/orders
Looked up by its alias within the report.
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/reports/admin%3Asales-overview/dataset-refs/orders"
}
},
"id": "00000000-0000-4000-8000-000000000001",
"filter": {},
"chips": [],
"alias": "orders",
"label": "Orders",
"tenant": "acme",
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"reportId": "00000000-0000-4000-8000-000000000002",
"datasetId": "00000000-0000-4000-8000-000000000003",
"snapshots": null,
"_embedded": {
"inf:dataset": {
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003"
},
"inf:draft": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/draft"
},
"inf:run": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/_run"
},
"inf:benchmark": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/_benchmark"
},
"inf:refresh": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/_refresh"
},
"inf:data": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/data{?start,limit,q,sort,show,report}",
"templated": true
},
"inf:user-settings": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/settings"
},
"inf:query": {
"href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000004"
},
"inf:owner": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/owner"
},
"inf:search": {
"href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/_search{?query,_source,sort,from,size,searchType,aggs,report,aggregations,alias,snapshots}",
"templated": true
},
"inf:mapping": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/mapping"
},
"inf:job-templates": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/job-templates"
},
"inf:fields": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/fields"
},
"inf:count": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/count"
},
"inf:comments": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/comments"
},
"inf:visuals": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/visuals"
},
"inf:visual-templates": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/visual-templates"
},
"inf:dataset-tags": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/tags"
},
"inf:dataset-tag": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/tags/{tagId}",
"templated": true
},
"inf:discover": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/discover"
},
"inf:filters": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/filters"
},
"inf:dataset-shares": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/shares"
},
"inf:flow": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/flow"
},
"inf:group": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/group"
},
"inf:group-rows": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/group-rows"
},
"inf:dataset-share": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/shares/{principalId}",
"templated": true
},
"inf:import": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/_import"
},
"inf:exceptions": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/_exceptions"
},
"inf:search-aggregates": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/_search-aggregates"
},
"inf:exporters": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/exporters"
},
"inf:favorite": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/favorite"
},
"inf:export-bundle": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/_export"
},
"edit": {
"href": "https://informer.example.com/api/reports/admin%3Anorthwind-orders/_edit"
}
},
"naturalId": "admin:northwind-orders",
"permissions": {
"edit": true,
"share": true,
"delete": true,
"write": true,
"addVisual": true,
"deleteVisual": true,
"changeOwner": true,
"copy": true,
"rename": true,
"refresh": true,
"modifyFlows": true,
"replaceFile": true,
"modifySettings": true,
"createDataView": true,
"assignTags": true,
"createFilter": true,
"scriptFields": true,
"setIndex": false
},
"id": "00000000-0000-4000-8000-000000000003",
"tenant": "acme",
"ownerId": "admin",
"slug": "northwind-orders",
"name": "Northwind Orders",
"description": "A dataset consisting of all orders in the northwind system (public schema)",
"embedded": false,
"esIndex": null,
"esIndexName": "northwind-orders",
"esType": "data",
"records": -1,
"size": "524288",
"source": "northwind-datasets",
"sourceId": null,
"params": {},
"dataUpdatedAt": "2026-01-15T16:20:00.000Z",
"dataExpiresAt": null,
"ttl": null,
"append": false,
"shared": false,
"timestampField": null,
"lastDurationMillis": "1500",
"windowSize": 500,
"settings": {},
"flow": [],
"esId": null,
"lastQueriedAt": "2026-01-15T16:20:00.000Z",
"esWorkers": 1,
"datasetFieldReportAccess": false,
"parentId": null,
"templateProcessorId": null,
"deleteDate": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": null,
"reportId": "00000000-0000-4000-8000-000000000002",
"queryId": "00000000-0000-4000-8000-000000000004",
"editingId": null,
"folderId": null,
"query": {
"naturalId": "00000000-0000-4000-8000-000000000004",
"fields": null,
"permissions": {
"assignTags": true,
"changeOwner": true,
"copy": true,
"delete": true,
"edit": true,
"rename": true,
"run": true,
"share": true,
"write": true
},
"id": "00000000-0000-4000-8000-000000000004",
"tenant": "acme",
"ownerId": "admin",
"slug": null,
"name": null,
"description": null,
"shared": false,
"embedded": true,
"source": null,
"sourceId": null,
"settings": {},
"inputs": null,
"language": "informer",
"flow": [
{
"calculatedField": {
"alias": "salesperson",
"label": "Salesperson",
"script": "FirstName + ' ' + LastName"
}
},
{
"calculatedField": {
"alias": "orderAmount",
"label": "Order Amount",
"script": "UnitPrice * Quantity"
}
},
{
"calculatedField": {
"alias": "shipState",
"label": "Ship State",
"script": "ShipCountry === \"USA\" ? ShipRegion : null"
}
}
],
"payload": {
"fields": [
{
"id": "OrderDate",
"path": "OrderDate",
"type": "field",
"label": "Order Date",
"fieldId": "OrderDate",
"grouped": false,
"linkRef": null,
"rawType": "date",
"dataType": "date_tz",
"distinct": false,
"position": 0,
"aggregate": null
},
{
"id": "RequiredDate",
"path": "RequiredDate",
"type": "field",
"label": "Required Date",
"fieldId": "RequiredDate",
"grouped": false,
"linkRef": null,
"rawType": "date",
"dataType": "date_tz",
"distinct": false,
"position": 1,
"aggregate": null
},
{
"id": "ShipAddress",
"path": "ShipAddress",
"type": "field",
"label": "Ship Address",
"fieldId": "ShipAddress",
"grouped": false,
"linkRef": null,
"rawType": "character varying",
"dataType": "keyword_text",
"distinct": false,
"position": 2,
"aggregate": null
},
"… 10 more items (13 total) — omitted from docs"
],
"source": {
"id": "00000000-0000-4000-8000-000000000005:public+orders",
"schemaId": "public",
"mappingId": "orders"
},
"groupBy": [],
"linkRefs": [
{
"id": "employees",
"linkId": "00000000-0000-4000-8000-000000000005:public+orders:employees",
"details": {
"id": "00000000-0000-4000-8000-000000000005:public+orders:employees",
"defn": [
{
"toField": "EmployeeID",
"operator": "=",
"toSchema": "public",
"fromField": "EmployeeID",
"toMapping": "employees",
"fromSchema": "public",
"fromMapping": "orders"
}
],
"toId": "00000000-0000-4000-8000-000000000005:public+employees",
"type": "sql",
"fromId": "00000000-0000-4000-8000-000000000005:public+orders",
"linkId": "employees"
}
},
{
"id": "order-details",
"linkId": "00000000-0000-4000-8000-000000000005:public+orders:order-details",
"details": {
"id": "00000000-0000-4000-8000-000000000005:public+orders:order-details",
"defn": [
{
"toField": "OrderID",
"operator": "=",
"toSchema": "public",
"fromField": "OrderID",
"toMapping": "order_details",
"fromSchema": "public",
"fromMapping": "orders"
}
],
"toId": "00000000-0000-4000-8000-000000000005:public+order_details",
"type": "sql",
"fromId": "00000000-0000-4000-8000-000000000005:public+orders",
"linkId": "order-details"
}
},
{
"id": "order-details/products",
"linkId": "00000000-0000-4000-8000-000000000005:public+order_details:products",
"details": {
"id": "00000000-0000-4000-8000-000000000005:public+order_details:products",
"defn": [
{
"toField": "ProductID",
"operator": "=",
"toSchema": "public",
"fromField": "ProductID",
"toMapping": "products",
"fromSchema": "public",
"fromMapping": "order_details"
}
],
"toId": "00000000-0000-4000-8000-000000000005:public+products",
"type": "sql",
"fromId": "00000000-0000-4000-8000-000000000005:public+order_details",
"linkId": "products"
}
}
]
},
"defnUpdatedAt": null,
"limit": -1,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"datasourceId": "00000000-0000-4000-8000-000000000005",
"editingId": null,
"folderId": null,
"datasource": {
"defaultLinkType": "sql",
"aiSystemMessage": "This is a PostgresSQL database. Identifiers are case-sensitive by default. \n Always surround all column names, table names, and schema names in double-quotes (\"). \n For example:\n SELECT \"OrderID\", \"ShipCountry\" FROM \"public\".\"orders\" WHERE \"ShipCity\" = 'Raleigh';\n ---",
"family": "sql",
"languages": [
"informer",
"sql",
"distinctValue",
"… 2 more items (5 total) — omitted from docs"
],
"naturalId": "admin:northwind",
"image": "/opt/informer/packages/informer-server/modules/sql/images/postgres.svg",
"compatibility": [],
"permissions": {
"assignTags": true,
"edit": true,
"delete": true,
"share": true,
"write": true,
"changeOwner": true,
"ping": true,
"scan": true,
"downloadSchema": true,
"importData": true,
"importSchema": true,
"rename": true,
"editConnection": true,
"createLink": true,
"setWrite": true,
"createSuite": true,
"createFieldExpression": true,
"createMapping": false,
"bundle": true,
"query": true
},
"id": "00000000-0000-4000-8000-000000000005",
"tenant": "acme",
"ownerId": "admin",
"slug": "northwind",
"name": "Northwind",
"description": null,
"embedded": false,
"type": "postgres",
"connection": {
"host": "localhost",
"pool": {
"max": 5,
"min": 0,
"idle": 10000,
"acquire": 10000
},
"port": 5432,
"user": "northwinduser",
"database": "northwind",
"password": "encrypted:iv:0000000000000000",
"idleTimeoutMillis": 7
},
"scannedAt": "2026-01-15T16:20:00.000Z",
"schemaUpdatedAt": "2026-01-15T16:20:00.000Z",
"rescanRequired": false,
"shared": false,
"schemas": [
"public"
],
"source": null,
"sourceId": null,
"settings": {
"multiSchema": false,
"useFakeData": false,
"remoteQueryBatchSize": {
"multiKey": 500,
"singleKey": 500
},
"usePreparedStatements": false
},
"data": null,
"appId": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"folderId": null,
"fileId": null,
"shares": []
}
},
"_embedded": {
"inf:field": [
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/fields/RequiredDate"
}
},
"label": "Required Date",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000006",
"tenant": "acme",
"name": "RequiredDate",
"datasetId": "00000000-0000-4000-8000-000000000003",
"position": 1,
"dataType": "date",
"script": null,
"typeMapping": {
"type": "date"
},
"formatOptions": null,
"lockFieldId": true,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/fields/Quantity"
}
},
"label": "Order Detail Quantity",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000007",
"tenant": "acme",
"name": "Quantity",
"datasetId": "00000000-0000-4000-8000-000000000003",
"position": 11,
"dataType": "integer",
"script": null,
"typeMapping": {
"type": "integer"
},
"formatOptions": null,
"lockFieldId": true,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000003/fields/ShippedDate"
}
},
"label": "Shipped Date",
"source": "Indexed",
"id": "00000000-0000-4000-8000-000000000008",
"tenant": "acme",
"name": "ShippedDate",
"datasetId": "00000000-0000-4000-8000-000000000003",
"position": 7,
"dataType": "date",
"script": null,
"typeMapping": {
"type": "date"
},
"formatOptions": null,
"lockFieldId": true,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"fieldId": null,
"field": null
},
"… 13 more items (16 total) — omitted from docs"
],
"inf:filter": []
}
}
}
}
PUT /api/reports/{id}/dataset-refs/{dataset}
Update a dataset reference configuration.
Authentication: Required
Permissions: report:write
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Report ID |
dataset | string | Dataset alias |
Request Body:
{
"alias": "orders",
"label": "Updated Orders Label",
"filter": {
"criteria": [
{
"field": "status",
"op": "eq",
"value": "completed"
}
]
},
"chips": [],
"snapshots": {
"includeLatest": false,
"type": "n",
"n": 10,
"snapshotDatasets": ["snapshot-3", "snapshot-4"]
}
}
Response:
Returns the updated dataset reference.
Update a dataset referencePUT /api/reports/admin:sales-overview/dataset-refs/orders
Edit the binding’s label, alias, filter, chips, or snapshot settings. Renaming the alias propagates into the report defn.
Request body
{
"label": "Orders (FY24)",
"filter": {},
"chips": []
}
Response · 200
{
"_links": {
"self": {
"href": "https://informer.example.com/api/reports/admin%3Asales-overview/dataset-refs/orders"
}
},
"id": "00000000-0000-4000-8000-000000000001",
"filter": {},
"chips": [],
"alias": "orders",
"label": "Orders (FY24)",
"tenant": "acme",
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"reportId": "00000000-0000-4000-8000-000000000002",
"datasetId": "00000000-0000-4000-8000-000000000003",
"snapshots": null
}
Notes:
- Changing the
aliaswill update all references in the report definition - Snapshot dataset associations are replaced (not merged)
- Invalid snapshot dataset IDs are ignored
DELETE /api/reports/{id}/dataset-refs/{dataset}
Remove a dataset reference from a report.
Authentication: Required
Permissions: report:write
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Report ID |
dataset | string | Dataset alias |
Response:
204 No Content on success.
Behavior:
- Removes the dataset reference
- Removes all references to the alias from the report definition
- Deletes associated snapshot settings
- Does not delete the actual dataset (only the report's reference to it)
Snapshot Settings
Snapshot settings allow reports to include historical versions of datasets alongside current data.
Configuration Options
Include Latest:
{
"includeLatest": true
}
Include the current dataset data along with snapshots.
Last N Snapshots:
{
"type": "n",
"n": 5,
"includeLatest": true
}
Include the 5 most recent snapshots plus current data.
Specific Snapshots:
{
"snapshotDatasets": [
"orders-2024-jan",
"orders-2024-feb",
"orders-2024-mar"
],
"includeLatest": false
}
Include only specific snapshot datasets.
Mixed Approach:
{
"type": "n",
"n": 3,
"includeLatest": true,
"snapshotDatasets": ["orders-2023-dec"]
}
Include last 3 snapshots, current data, and a specific older snapshot.
Record Counts
The GET endpoint returns multiple count fields:
- count: Records after applying report-level filters and snapshot inclusion
- countWithoutSnapshots: Records in the base dataset only (excluding snapshots)
- overallCount: Total records including all configured snapshots
These counts help understand the data volume and snapshot impact.