Create a Data Set
dataset_createMaterialize a SQL query against one of your Data Sources into a cached Data Set table, refreshed on a schedule. Use this when a query is too slow to run live (the interactive budget is 60s, and a live query that runs anywhere near it spends the whole turn waiting), or when a dashboard needs filters — dashboard query parameters are supported on Data Sets only, because cached tables accept bind parameters and raw Data Sources do not. The Data Set is created immediately and its first build runs in the background; poll dataset_get for status until it reports 'ready'. The source connection must be one you own, not one shared with you. A SaaS source (postgres_list_connections marks it dataSetOnly) has no SQL: for it, sql is a JSON source-selection object — Google Sheets (public link) (type "google-sheets"): { "spreadsheetId": "<the id in the sheet's URL>", "sheet": "<tab name; optional, the first tab when omitted>" }; Airtable (type "airtable"): { "baseId": "app…", "tableId": "", "view": "" }; Salesforce (type "salesforce"): { "soql": "SELECT Id, Name, Amount FROM Opportunity" }; HubSpot (type "hubspot"): { "object": "contacts", "properties": "<optional comma-separated property names, e.g. email,firstname>" }; Google Sheets account (type "google-drive", find files with spreadsheet_list): { "spreadsheetId": "<the id spreadsheet_list returns, or the sheet's URL>", "sheet": "<tab name; optional, the first tab when omitted>", "range": "<optional A1 range whose first row is the header, e.g. A3:H>" }; Excel (Microsoft 365) account (type "microsoft-excel", find files with spreadsheet_list): { "driveId": "<the file's driveId from spreadsheet_list>", "itemId": "<the file's fileId from spreadsheet_list>", "sheet": "<worksheet name; optional, the first when omitted>", "range": "<optional A1 range whose first row is the header, e.g. A3:H>" }; Smartsheet account (type "smartsheet", find files with spreadsheet_list): { "sheetId": "<the sheet's fileId from spreadsheet_list, as text>" }. Those sources always refresh in full. Change a Data Set later with dataset_update; rebuild it now with dataset_refresh.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"name": "<name>",
"connection": "<connection>",
"sql": "<sql>"
},
"name": "dataset_create"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | The SQL to materialize. Runs against the Data Source on every refresh with a 120s budget, so it may be far heavier than an interactive query — aggregate here so the cached table is small and fast to read. For a SaaS source, the JSON source-selection object described above, as text. | |
| name | Yes | Name for the new Data Set. Must be unique to you. | |
| syncKey | No | With Sync: the unique key column rows are matched by. Omit to let it pick (the primary key, else a unique non-null column). | |
| connection | Yes | Name of the Data Source to read from, as returned by postgres_list_connections. Must be one you own. | |
| description | No | Optional human-readable description. | |
| refreshCron | No | 5-field UTC cron schedule. Mutually exclusive with refreshIntervalSeconds. | |
| refreshMode | No | How a refresh brings the cached table up to date. "auto" (the default): Sync when the query allows it, otherwise reload every row — decided from the source at the first refresh, and again whenever the SQL changes. "sync": copy only rows that changed — needs a PostgreSQL source and a query over ONE table whose result includes its unique key and a changed-at timestamp (updated_at or similar); a query that cannot sync reloads every row and says why. Sync checks itself against full reloads and stops on any difference. "full": reload every row. "incremental": append rows past incrementalKey, never picking up edits or deletes — only for append-only tables; not for SaaS sources. | |
| indexColumns | No | Columns to index on the cached table. Index the columns dashboard filters bind to — that is what makes a filtered read fast. | |
| incrementalKey | No | With refreshMode "incremental": the monotonically increasing column (an id or a created-at timestamp) a refresh reads past. | |
| syncChangedColumn | No | With Sync: the timestamp column that changes whenever a row does. Omit to let it pick (updated_at, modified_at…). | |
| freshnessWindowSeconds | No | How long a build stays fresh before a read triggers a lazy refresh. Defaults to 3600. | |
| refreshIntervalSeconds | No | Refresh every N seconds (minimum 300). Mutually exclusive with refreshCron. Omit both for manual refresh only. |