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:

{
  "_links": {
    "self": { "href": "/api/reports/{id}/dataset-refs" }
  },
  "_embedded": {
    "inf:dataset-reference": [
      {
        "id": "orders",
        "alias": "orders",
        "datasetId": "orders-2024",
        "label": "Orders Dataset",
        "filter": {
          "criteria": []
        },
        "chips": [],
        "count": 12500,
        "countWithoutSnapshots": 12500,
        "overallCount": 15000,
        "snapshots": {
          "includeLatest": true,
          "type": "n",
          "n": 5,
          "snapshotDatasets": [
            { "datasetId": "orders-2024-jan" },
            { "datasetId": "orders-2024-feb" }
          ]
        },
        "dataset": {
          "id": "orders-2024",
          "name": "Orders 2024",
          "fields": [
            {
              "name": "orderId",
              "label": "Order ID",
              "type": "integer"
            }
          ]
        }
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

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:

{
  "id": "uuid",
  "reportId": "team:sales-dashboard",
  "datasetId": "customers-2024",
  "alias": "customers",
  "label": "Customer Data"
}

Status Code: 201 Created

Location Header: URL of the created dataset reference

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:

{
  "id": "uuid",
  "alias": "orders",
  "datasetId": "orders-2024",
  "label": "Orders Dataset",
  "filter": {},
  "chips": [],
  "snapshots": {
    "includeLatest": true,
    "type": "n",
    "n": 5
  }
}

---

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.

Notes:

• Changing the alias will 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.