Settings

Manage user-specific view preferences and snapshot configuration for datasets.

GET /api/datasets/{id}/settings

Get user settings for a dataset.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Dataset ID or slug

Response:

{
  "datasetId": "sales-2024",
  "userId": "user:admin",
  "settings": {
    "defaultView": "table",
    "pageSize": 50,
    "columnWidths": {
      "order_id": 120,
      "customer_name": 200,
      "amount": 100
    },
    "columnOrder": ["order_id", "customer_name", "amount", "order_date"],
    "hiddenColumns": ["internal_notes", "audit_timestamp"],
    "defaultSort": {
      "field": "order_date",
      "order": "desc"
    },
    "defaultFilter": "filter-high-value",
    "visualPreferences": {
      "chartType": "bar",
      "colorScheme": "blue"
    }
  },
  "snapshots": {
    "includeLatest": true,
    "type": "relative",
    "n": 5,
    "snapshotDatasets": []
  },
  "updatedAt": "2024-02-08T15:30:00Z"
}

Settings Properties:

Property	Type	Description
`defaultView`	string	Default view type: `table`, `grid`, `chart`
`pageSize`	integer	Default number of records per page
`columnWidths`	object	Column width preferences (pixels)
`columnOrder`	array	Column display order
`hiddenColumns`	array	Columns hidden from view
`defaultSort`	object	Default sort configuration
`defaultFilter`	string	Default filter ID
`visualPreferences`	object	Visual/chart preferences

Snapshot Settings:

Property	Type	Description
`includeLatest`	boolean	Include current data in snapshot views
`type`	string	Snapshot selection: `relative`, `absolute`
`n`	integer	Number of snapshots (for relative type)
`snapshotDatasets`	array	Specific snapshot IDs (for absolute type)

PUT /api/datasets/{id}/settings

Update user settings and snapshot configuration.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Dataset ID or slug

Request Body:

Field	Type	Description
`settings`	object	User preference settings
`snapshots`	object	Snapshot configuration

Example Request:

{
  "settings": {
    "defaultView": "grid",
    "pageSize": 100,
    "columnOrder": ["customer_name", "amount", "order_date", "order_id"],
    "hiddenColumns": ["internal_notes"],
    "defaultSort": {
      "field": "amount",
      "order": "desc"
    },
    "defaultFilter": "filter-west-region"
  },
  "snapshots": {
    "includeLatest": true,
    "type": "relative",
    "n": 10
  }
}

Response:

Returns the updated settings object.

Merge Behavior:

Settings are merged with existing user settings. Only specified properties are updated; unspecified properties are preserved.

POST /api/datasets/{id}/settings/_restore

Delete user settings and restore to defaults.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Dataset ID or slug

Response:

204 No Content

Behavior:

Deletes all user-specific settings for this dataset
User will see default dataset view
Column order, widths, and preferences reset
Default filter and sort cleared

Use Case:

Reset personalized view when settings become corrupted or user wants to start fresh.

GET /api/datasets/{id}/params

Get dataset query parameters.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Dataset ID or slug

Response:

{
  "params": [
    {
      "name": "year",
      "label": "Fiscal Year",
      "dataType": "number",
      "defaultValue": 2024,
      "required": true,
      "description": "Fiscal year for reporting",
      "options": [2022, 2023, 2024]
    },
    {
      "name": "region",
      "label": "Sales Region",
      "dataType": "string",
      "defaultValue": "All",
      "required": false,
      "description": "Filter by region",
      "options": ["All", "West", "East", "North", "South"]
    },
    {
      "name": "minAmount",
      "label": "Minimum Order Amount",
      "dataType": "number",
      "defaultValue": 0,
      "required": false,
      "description": "Minimum order value to include"
    }
  ]
}

Parameter Properties:

Property	Type	Description
`name`	string	Parameter identifier (used as `{{name}}` in query)
`label`	string	Display name
`dataType`	string	Data type: `string`, `number`, `date`, `boolean`
`defaultValue`	any	Default value if not provided
`required`	boolean	Must be provided for execution
`description`	string	Help text
`options`	array	Predefined value options (optional)

PUT /api/datasets/{id}/params

Update dataset query parameters.

Authentication: Required

Permission: dataset:write

Path Parameters:

Parameter	Type	Description
`id`	string	Dataset ID or slug

Request Body:

Array of parameter objects.

Example Request:

{
  "params": [
    {
      "name": "startDate",
      "label": "Start Date",
      "dataType": "date",
      "defaultValue": "2024-01-01",
      "required": true,
      "description": "Beginning of date range"
    },
    {
      "name": "endDate",
      "label": "End Date",
      "dataType": "date",
      "defaultValue": "2024-12-31",
      "required": true,
      "description": "End of date range"
    },
    {
      "name": "status",
      "label": "Order Status",
      "dataType": "string",
      "defaultValue": "all",
      "required": false,
      "options": ["all", "pending", "completed", "cancelled"]
    }
  ]
}

Response:

Returns the updated dataset with new parameters.

Parameter Usage

Parameters defined here are available in the dataset query using {{paramName}} syntax. They can be overridden at refresh/run time.

User Settings Examples

Table View Preferences

{
  "settings": {
    "defaultView": "table",
    "pageSize": 50,
    "columnWidths": {
      "order_id": 100,
      "customer_name": 250,
      "amount": 120,
      "order_date": 150
    },
    "columnOrder": [
      "order_id",
      "customer_name",
      "amount",
      "order_date",
      "region"
    ],
    "hiddenColumns": [
      "internal_notes",
      "created_by",
      "modified_at"
    ],
    "defaultSort": {
      "field": "order_date",
      "order": "desc"
    }
  }
}

Chart View Preferences

{
  "settings": {
    "defaultView": "chart",
    "visualPreferences": {
      "chartType": "line",
      "colorScheme": "categorical",
      "xAxis": "order_date",
      "yAxis": "amount",
      "groupBy": "region",
      "showLegend": true,
      "showDataLabels": false
    }
  }
}

Grid View Preferences

{
  "settings": {
    "defaultView": "grid",
    "pageSize": 25,
    "gridPreferences": {
      "cardLayout": "compact",
      "imageField": "product_image",
      "titleField": "product_name",
      "subtitleField": "category",
      "priceField": "amount"
    }
  }
}

Snapshot Configuration Examples

Include Latest + Last 5 Snapshots

{
  "snapshots": {
    "includeLatest": true,
    "type": "relative",
    "n": 5,
    "snapshotDatasets": []
  }
}

This shows:

Current data (includeLatest: true)
5 most recent snapshots (type: relative, n: 5)

Specific Snapshots Only

{
  "snapshots": {
    "includeLatest": false,
    "type": "absolute",
    "n": 0,
    "snapshotDatasets": [
      "sales-2024-q1-snapshot",
      "sales-2024-q2-snapshot",
      "sales-2024-q3-snapshot",
      "sales-2024-q4-snapshot"
    ]
  }
}

This shows:

No current data (includeLatest: false)
Only the 4 specified snapshots (type: absolute)

Current Data Only

{
  "snapshots": {
    "includeLatest": true,
    "type": "relative",
    "n": 0,
    "snapshotDatasets": []
  }
}

This shows:

Only current data, no snapshots

Settings Use Cases

Personal Dashboard

Users can customize their view of shared datasets:

// User A prefers table view with high page size
await PUT('/api/datasets/sales-2024/settings', {
  settings: {
    defaultView: 'table',
    pageSize: 100,
    defaultSort: { field: 'amount', order: 'desc' }
  }
});

// User B prefers chart view
await PUT('/api/datasets/sales-2024/settings', {
  settings: {
    defaultView: 'chart',
    visualPreferences: { chartType: 'bar' }
  }
});

Historical Analysis

Configure snapshot views for trend analysis:

await PUT('/api/datasets/sales-2024/settings', {
  snapshots: {
    includeLatest: true,
    type: 'relative',
    n: 12  // Last 12 snapshots (monthly)
  }
});

Compliance Reporting

Lock view to specific historical snapshots:

await PUT('/api/datasets/financial-2024/settings', {
  snapshots: {
    includeLatest: false,
    type: 'absolute',
    snapshotDatasets: [
      'financial-2024-q1-final',
      'financial-2024-q2-final',
      'financial-2024-q3-final'
    ]
  }
});

Best Practices

User Settings

Preserve user preferences during dataset updates
Don't override user settings programmatically
Provide reset option to restore defaults
Validate settings before saving
Document conventions for team-shared datasets

Snapshot Configuration

Match business needs: Quarterly snapshots for financial data, daily for operational data
Limit snapshot count: Too many snapshots slow queries and UI
Use relative mode: For rolling time windows
Use absolute mode: For fixed reporting periods
Document snapshot purpose: Include descriptions explaining each snapshot

Parameter Management

Use descriptive labels: Help users understand what parameters do
Provide default values: Ensure dataset works out-of-box
Offer options lists: When parameter has limited valid values
Mark required params: Prevent execution errors
Document parameter usage: Explain how parameters affect query results

Performance

Limit hidden columns: Don't hide too many columns by default
Optimize default sorts: Index frequently sorted fields
Reasonable page sizes: 25-100 records for most use cases
Cache settings: Client-side caching reduces API calls

Settings vs. Configuration

Settings are user-specific preferences (view, layout, sort). Configuration is dataset-level (query, fields, parameters). Don't confuse the two when building UIs.

GET /api/datasets/{id}/settings​

PUT /api/datasets/{id}/settings​

POST /api/datasets/{id}/settings/_restore​

GET /api/datasets/{id}/params​

PUT /api/datasets/{id}/params​

User Settings Examples​

Table View Preferences​

Chart View Preferences​

Grid View Preferences​

Snapshot Configuration Examples​

Include Latest + Last 5 Snapshots​

Specific Snapshots Only​

Current Data Only​

Settings Use Cases​

Personal Dashboard​

Historical Analysis​

Compliance Reporting​

Best Practices​

User Settings​

Snapshot Configuration​

Parameter Management​

Performance​

GET /api/datasets/{id}/settings

PUT /api/datasets/{id}/settings

POST /api/datasets/{id}/settings/_restore

GET /api/datasets/{id}/params

PUT /api/datasets/{id}/params

User Settings Examples

Table View Preferences

Chart View Preferences

Grid View Preferences

Snapshot Configuration Examples

Include Latest + Last 5 Snapshots

Specific Snapshots Only

Current Data Only

Settings Use Cases

Personal Dashboard

Historical Analysis

Compliance Reporting

Best Practices

User Settings

Snapshot Configuration

Parameter Management

Performance