Info & Metadata

Get dataset metadata, exceptions, and minimal information.

GET /api/datasets/{id}/info

Get minimal dataset information (slug, name, owner, datasource type).

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Dataset ID or slug

Response:

{
  "id": "sales-2024",
  "slug": "sales-2024",
  "name": "Sales Data 2024",
  "ownerId": "team:analytics",
  "owner": {
    "id": "team:analytics",
    "name": "Analytics Team",
    "type": "team"
  },
  "datasourceId": "mysql-prod",
  "datasourceType": "mysql"
}

Use Case:

Lightweight endpoint for getting basic dataset information without loading full details. Useful for breadcrumbs, references, and quick lookups.

---

GET /api/datasets/_exceptions

Get dataset exceptions and errors.

Authentication: Required

Query Parameters:

Parameter	Type	Default	Description
start	integer	0	Pagination offset
limit	integer	30	Number of results per page

Response:

{
  "_links": {
    "self": { "href": "/api/datasets/_exceptions" }
  },
  "_embedded": {
    "inf:exception": [
      {
        "id": "exception-123",
        "datasetId": "sales-2024",
        "dataset": {
          "id": "sales-2024",
          "name": "Sales Data 2024"
        },
        "type": "refresh_error",
        "message": "Connection timeout to datasource mysql-prod",
        "details": {
          "datasourceId": "mysql-prod",
          "query": "SELECT * FROM orders",
          "errorCode": "ETIMEDOUT"
        },
        "occurredAt": "2024-02-08T03:00:00Z",
        "resolved": false
      },
      {
        "id": "exception-456",
        "datasetId": "customer-data",
        "dataset": {
          "id": "customer-data",
          "name": "Customer Database"
        },
        "type": "mapping_conflict",
        "message": "Field type mismatch: 'amount' expected number, got string",
        "details": {
          "field": "amount",
          "expectedType": "number",
          "actualType": "string",
          "sampleValue": "$1,234.56"
        },
        "occurredAt": "2024-02-07T15:30:00Z",
        "resolved": true,
        "resolvedAt": "2024-02-07T16:00:00Z",
        "resolvedBy": "user:admin"
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 15
}

Exception Types:

Type	Description
refresh_error	Dataset refresh failed
query_error	SQL query execution error
mapping_conflict	Elasticsearch mapping conflict
permission_error	Permission denied error
validation_error	Data validation failure
timeout_error	Operation timeout

Use Case:

Monitor dataset health and troubleshoot errors. Display in admin dashboards or alerting systems.

---

Exception Handling Examples

Get Recent Errors

const exceptions = await GET('/api/datasets/_exceptions?limit=10');

// Filter unresolved
const unresolved = exceptions.items.filter(e => !e.resolved);

console.log(`${unresolved.length} unresolved errors`);

Monitor Specific Dataset

const allExceptions = await GET('/api/datasets/_exceptions?limit=100');

const datasetErrors = allExceptions.items.filter(
  e => e.datasetId === 'sales-2024'
);

if (datasetErrors.length > 0) {
  console.warn(`Dataset has ${datasetErrors.length} errors`);
}

Error Alert System

const exceptions = await GET('/api/datasets/_exceptions');

for (const exception of exceptions.items) {
  if (!exception.resolved && exception.type === 'refresh_error') {
    // Send alert
    await sendAlert({
      title: `Dataset Refresh Failed: ${exception.dataset.name}`,
      message: exception.message,
      severity: 'high',
      datasetId: exception.datasetId
    });
  }
}

---

Best Practices

Info Endpoint

• Use for references - When you only need basic info
• Breadcrumb navigation - Lightweight dataset context
• Performance - Much faster than full GET
• Caching - Cache info responses client-side

Exception Monitoring

• Regular polling - Check for new exceptions periodically
• Alert on critical errors - Notify admins of refresh failures
• Track resolution - Mark exceptions as resolved when fixed
• Log analysis - Identify patterns in recurring errors
• User notifications - Inform dataset owners of errors