Visuals

Create and manage visual representations (charts, graphs, dashboards) for datasets.

GET /api/datasets/{id}/visuals

Get all visuals for a dataset.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Dataset ID or slug

Query Parameters:

Parameter	Type	Default	Description
pinned	boolean	-	Filter to pinned visuals only

Response:

{
  "_links": {
    "self": { "href": "/api/datasets/{id}/visuals" }
  },
  "_embedded": {
    "inf:visual": [
      {
        "id": "visual-sales-by-region",
        "name": "Sales by Region",
        "description": "Bar chart showing sales breakdown by region",
        "component": "bar-chart",
        "datasetId": "sales-2024",
        "ownerId": "user:admin",
        "config": {
          "xAxis": "region",
          "yAxis": "amount",
          "aggregation": "sum",
          "colorScheme": "categorical",
          "showLegend": true
        },
        "embedded": false,
        "pinned": true,
        "position": 0,
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-02-08T15:00:00Z",
        "permissions": {
          "edit": true,
          "delete": true
        }
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

Visual Properties:

Property	Type	Description
id	string	Visual identifier
name	string	Visual display name
description	string	Visual description
component	string	Visual type/component
config	object	Component-specific configuration
embedded	boolean	Whether visual is embedded in dashboard
pinned	boolean	Pinned to top of visual list
position	integer	Display order

---

POST /api/datasets/{id}/visuals

Create a new visual for the dataset.

Authentication: Required

Permission: dataset:addVisual

Path Parameters:

Parameter	Type	Description
id	string	Dataset ID or slug

Request Body:

Field	Type	Required	Description
component	string	Yes	Visual component type
name	string	No	Visual display name
description	string	No	Visual description
config	object	No	Component configuration
embedded	boolean	No	Embedded visual (default: false)

Example Request (bar chart):

{
  "component": "bar-chart",
  "name": "Monthly Sales Trend",
  "description": "Bar chart showing sales by month",
  "config": {
    "xAxis": "month",
    "yAxis": "amount",
    "aggregation": "sum",
    "colorScheme": "blue",
    "showLegend": false,
    "showDataLabels": true
  }
}

Example Request (line chart):

{
  "component": "line-chart",
  "name": "Revenue Over Time",
  "config": {
    "xAxis": "order_date",
    "yAxis": "revenue",
    "aggregation": "sum",
    "groupBy": "region",
    "smooth": true,
    "showPoints": true
  }
}

Example Request (pie chart):

{
  "component": "pie-chart",
  "name": "Sales by Category",
  "config": {
    "categoryField": "category",
    "valueField": "amount",
    "aggregation": "sum",
    "showPercentages": true,
    "innerRadius": 0
  }
}

Response:

Returns the created visual object with assigned ID and default properties.

---

GET /api/datasets/{datasetId}/visuals/{id}

Get a single visual by ID.

Authentication: Required

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset ID or slug
id	string	Visual ID

Response:

{
  "id": "visual-sales-by-region",
  "name": "Sales by Region",
  "description": "Bar chart showing sales breakdown by region",
  "component": "bar-chart",
  "datasetId": "sales-2024",
  "ownerId": "user:admin",
  "config": {
    "xAxis": "region",
    "yAxis": "amount",
    "aggregation": "sum",
    "colorScheme": "categorical",
    "showLegend": true,
    "chartTitle": "Sales by Region",
    "width": 800,
    "height": 400
  },
  "embedded": false,
  "pinned": true,
  "position": 0,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-02-08T15:00:00Z",
  "_links": {
    "self": { "href": "/api/datasets/sales-2024/visuals/visual-sales-by-region" },
    "inf:dataset": { "href": "/api/datasets/sales-2024" }
  }
}

---

PUT /api/datasets/{datasetId}/visuals/{id}

Update an existing visual.

Authentication: Required

Permission: dataset:addVisual

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset ID or slug
id	string	Visual ID

Request Body:

Field	Type	Description
name	string	Visual display name
description	string	Visual description
config	object	Component configuration
pinned	boolean	Pin to top
position	integer	Display order

Example Request:

{
  "name": "Updated Sales by Region",
  "config": {
    "xAxis": "region",
    "yAxis": "amount",
    "aggregation": "avg",
    "colorScheme": "green",
    "showLegend": true,
    "showDataLabels": true,
    "chartTitle": "Average Sales by Region"
  },
  "pinned": true
}

Response:

Returns the updated visual object.

---

DELETE /api/datasets/{datasetId}/visuals/{id}

Delete a visual.

Authentication: Required

Permission: dataset:deleteVisual

Path Parameters:

Parameter	Type	Description
datasetId	string	Dataset ID or slug
id	string	Visual ID

Response:

204 No Content

---

GET /api/datasets/{id}/visual-templates

Get visual builder templates for the dataset.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Dataset ID or slug

Response:

{
  "templates": [
    {
      "id": "bar-chart-basic",
      "name": "Bar Chart",
      "component": "bar-chart",
      "description": "Compare values across categories",
      "icon": "bar-chart",
      "category": "comparison",
      "config": {
        "xAxis": null,
        "yAxis": null,
        "aggregation": "sum"
      }
    },
    {
      "id": "line-chart-trend",
      "name": "Line Chart",
      "component": "line-chart",
      "description": "Show trends over time",
      "icon": "line-chart",
      "category": "trend",
      "config": {
        "xAxis": null,
        "yAxis": null,
        "aggregation": "sum",
        "smooth": true
      }
    },
    {
      "id": "pie-chart-proportion",
      "name": "Pie Chart",
      "component": "pie-chart",
      "description": "Show proportions of a whole",
      "icon": "pie-chart",
      "category": "proportion",
      "config": {
        "categoryField": null,
        "valueField": null,
        "aggregation": "sum"
      }
    }
  ]
}

Use Case:

Present visual template options to users when creating new visuals. Templates provide starting configurations for common chart types.

---

Visual Component Types

Bar Chart

{
  "component": "bar-chart",
  "config": {
    "xAxis": "category",
    "yAxis": "value",
    "aggregation": "sum",
    "orientation": "vertical",
    "colorScheme": "categorical",
    "showLegend": true,
    "showDataLabels": false,
    "stacked": false
  }
}

Line Chart

{
  "component": "line-chart",
  "config": {
    "xAxis": "date",
    "yAxis": "value",
    "groupBy": "category",
    "aggregation": "sum",
    "smooth": true,
    "showPoints": true,
    "showArea": false,
    "colorScheme": "categorical"
  }
}

Pie Chart

{
  "component": "pie-chart",
  "config": {
    "categoryField": "category",
    "valueField": "amount",
    "aggregation": "sum",
    "showPercentages": true,
    "showLegend": true,
    "innerRadius": 0,
    "sortBy": "value"
  }
}

Table

{
  "component": "table",
  "config": {
    "columns": ["name", "amount", "date"],
    "sortBy": "amount",
    "sortOrder": "desc",
    "pageSize": 25,
    "showFilters": true,
    "showPagination": true
  }
}

Scatter Plot

{
  "component": "scatter-plot",
  "config": {
    "xAxis": "field1",
    "yAxis": "field2",
    "groupBy": "category",
    "sizeField": "amount",
    "colorScheme": "categorical",
    "showTrendline": false
  }
}

Heatmap

{
  "component": "heatmap",
  "config": {
    "xAxis": "category1",
    "yAxis": "category2",
    "valueField": "amount",
    "aggregation": "sum",
    "colorScheme": "sequential",
    "showValues": true
  }
}

Gauge

{
  "component": "gauge",
  "config": {
    "valueField": "percentage",
    "min": 0,
    "max": 100,
    "thresholds": [
      { "value": 30, "color": "red" },
      { "value": 70, "color": "yellow" },
      { "value": 100, "color": "green" }
    ],
    "showValue": true
  }
}

---

Visual Configuration Examples

Sales Dashboard

{
  "visuals": [
    {
      "component": "card",
      "name": "Total Revenue",
      "config": {
        "valueField": "amount",
        "aggregation": "sum",
        "format": "currency",
        "icon": "dollar"
      }
    },
    {
      "component": "line-chart",
      "name": "Revenue Trend",
      "config": {
        "xAxis": "order_date",
        "yAxis": "amount",
        "aggregation": "sum",
        "smooth": true,
        "dateInterval": "day"
      }
    },
    {
      "component": "bar-chart",
      "name": "Sales by Region",
      "config": {
        "xAxis": "region",
        "yAxis": "amount",
        "aggregation": "sum",
        "colorScheme": "categorical"
      }
    },
    {
      "component": "table",
      "name": "Top Products",
      "config": {
        "columns": ["product_name", "quantity", "revenue"],
        "sortBy": "revenue",
        "sortOrder": "desc",
        "pageSize": 10
      }
    }
  ]
}

Multi-Series Line Chart

{
  "component": "line-chart",
  "name": "Revenue by Product Category",
  "config": {
    "xAxis": "month",
    "yAxis": "revenue",
    "groupBy": "category",
    "aggregation": "sum",
    "smooth": true,
    "showLegend": true,
    "colorScheme": "categorical",
    "dateFormat": "MMM YYYY"
  }
}

Stacked Bar Chart

{
  "component": "bar-chart",
  "name": "Orders by Status and Region",
  "config": {
    "xAxis": "region",
    "yAxis": "order_count",
    "groupBy": "status",
    "aggregation": "count",
    "stacked": true,
    "showLegend": true,
    "colorScheme": "categorical"
  }
}

---

Best Practices

Visual Design

• Choose appropriate chart types - Match visualization to data and question
• Limit data points - Too many categories make charts unreadable
• Use color wisely - Consistent color schemes, accessible colors
• Label clearly - Descriptive titles, axis labels, legends
• Sort meaningfully - By value for bar charts, by time for trends

Performance

• Aggregate before visualizing - Don't chart raw records
• Limit series - Keep to 5-10 series max for line charts
• Use sampling - For scatter plots with thousands of points
• Cache visual data - Pre-compute aggregations when possible
• Optimize queries - Use indexed fields for grouping/sorting

User Experience

• Provide templates - Make it easy to create common visuals
• Enable interactions - Tooltips, drill-down, filtering
• Support responsiveness - Visuals adapt to screen size
• Allow customization - Let users adjust colors, labels, formats
• Pin important visuals - Keep key metrics at top

Maintenance

• Name visuals clearly - Describe what they show
• Document configuration - Complex configs need explanations
• Version control - Track changes to visual configs
• Test with data changes - Ensure visuals work as dataset evolves
• Review regularly - Remove unused visuals

Visual Discovery

Use the discover endpoint (GET /api/datasets/{id}/discover?fields=...) to get automatically generated visual suggestions based on field types and data characteristics.