Discovery & Templates
Discover visual templates, job templates, and Painless scripts for datasets.
GET /api/datasets/{id}/discover
Get automatically generated visual discovery templates based on dataset fields.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Dataset ID or slug |
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
fields | array | Specific fields to discover for |
alias | string | Snapshot alias |
Example Request:
GET /api/datasets/sales-2024/discover?fields=["region","amount","order_date"]
Response:
{
"suggestions": [
{
"type": "bar-chart",
"title": "Sales by Region",
"description": "Compare total sales across regions",
"confidence": 0.95,
"config": {
"component": "bar-chart",
"xAxis": "region",
"yAxis": "amount",
"aggregation": "sum"
}
},
{
"type": "line-chart",
"title": "Sales Trend Over Time",
"description": "View sales trends by date",
"confidence": 0.90,
"config": {
"component": "line-chart",
"xAxis": "order_date",
"yAxis": "amount",
"aggregation": "sum",
"dateInterval": "day"
}
},
{
"type": "pie-chart",
"title": "Sales Distribution by Region",
"description": "Show proportional sales by region",
"confidence": 0.85,
"config": {
"component": "pie-chart",
"categoryField": "region",
"valueField": "amount",
"aggregation": "sum"
}
}
],
"fields": {
"region": {
"type": "categorical",
"cardinality": 4,
"suitableFor": ["grouping", "filtering"]
},
"amount": {
"type": "numeric",
"suitableFor": ["aggregation", "axis"]
},
"order_date": {
"type": "date",
"suitableFor": ["timeseries", "filtering"]
}
}
}
Use Case:
Present intelligent visual suggestions to users based on their dataset's field types and data characteristics.
GET /api/dataset-templates
Get dataset builder templates.
Authentication: Required
Response:
{
"templates": [
{
"id": "sales-template",
"name": "Sales Dataset",
"description": "Template for sales transaction data",
"category": "sales",
"fields": [
{ "name": "order_id", "dataType": "string", "label": "Order ID" },
{ "name": "customer_name", "dataType": "string", "label": "Customer" },
{ "name": "amount", "dataType": "number", "label": "Amount" },
{ "name": "order_date", "dataType": "date", "label": "Order Date" }
],
"defaultQuery": "SELECT * FROM orders WHERE year = {{year}}",
"params": [
{ "name": "year", "dataType": "number", "defaultValue": 2024 }
]
},
{
"id": "customer-template",
"name": "Customer Dataset",
"description": "Template for customer data",
"category": "crm",
"fields": [
{ "name": "customer_id", "dataType": "string" },
{ "name": "name", "dataType": "string" },
{ "name": "email", "dataType": "string" },
{ "name": "created_at", "dataType": "date" }
]
}
]
}
GET /api/datasets/{id}/job-templates
Get job builder templates for a dataset.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Dataset ID or slug |
Response:
{
"templates": [
{
"id": "daily-refresh",
"name": "Daily Refresh",
"description": "Refresh dataset daily at midnight",
"schedule": {
"type": "cron",
"expression": "0 0 * * *"
},
"action": {
"type": "refresh",
"params": {}
}
},
{
"id": "weekly-export",
"name": "Weekly Export",
"description": "Export dataset to Excel weekly",
"schedule": {
"type": "cron",
"expression": "0 0 * * 1"
},
"action": {
"type": "export",
"exporter": "excel"
}
}
]
}
GET /api/datasets/{id}/jobs
Get all jobs associated with a dataset.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Dataset ID or slug |
Response:
{
"_links": {
"self": { "href": "/api/datasets/{id}/jobs" }
},
"_embedded": {
"inf:job": [
{
"id": "job-daily-refresh",
"name": "Daily Sales Refresh",
"datasetId": "sales-2024",
"schedule": "0 0 * * *",
"action": "refresh",
"enabled": true,
"lastRun": "2024-02-08T00:00:00Z",
"nextRun": "2024-02-09T00:00:00Z",
"status": "success"
}
]
},
"start": 0,
"count": 1,
"total": 1
}
GET /api/datasets/{id}/painless-templates
Get Painless script templates for dataset fields.
Authentication: Required
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Dataset ID or slug |
Response:
{
"templates": [
{
"id": "calculate-margin",
"name": "Calculate Profit Margin",
"description": "Calculate profit margin percentage",
"category": "calculation",
"script": "(doc['revenue'].value - doc['cost'].value) / doc['revenue'].value * 100",
"requiredFields": ["revenue", "cost"],
"outputType": "number"
},
{
"id": "full-name",
"name": "Combine First and Last Name",
"description": "Concatenate first and last name",
"category": "text",
"script": "doc['first_name'].value + ' ' + doc['last_name'].value",
"requiredFields": ["first_name", "last_name"],
"outputType": "string"
},
{
"id": "days-old",
"name": "Days Since Date",
"description": "Calculate days since a specific date",
"category": "date",
"script": "(System.currentTimeMillis() - doc['created_at'].value.toInstant().toEpochMilli()) / (1000 * 60 * 60 * 24)",
"requiredFields": ["created_at"],
"outputType": "number"
}
],
"fields": {
"revenue": { "dataType": "number" },
"cost": { "dataType": "number" },
"first_name": { "dataType": "string" },
"last_name": { "dataType": "string" },
"created_at": { "dataType": "date" }
}
}
Use Case:
Present pre-built Painless script templates to users when creating calculated fields, reducing the learning curve for complex expressions.
Best Practices
Discovery
- Present top suggestions - Show 3-5 best matches
- Explain confidence - Help users understand why visuals are suggested
- Allow customization - Let users modify suggested configs
- Learn from usage - Track which suggestions are accepted
Templates
- Provide variety - Cover common use cases
- Keep updated - Maintain templates as features evolve
- Document usage - Include clear descriptions
- Test thoroughly - Ensure templates work across datasets