A Dreambase dataset is a stored, named query plus its materialized result. It gives people and agents a bounded analytical object they can discover, inspect, query, refresh, and—after verification—keep for repeated use.

Datasets separate exploratory work from repeatable operations. Use MCP when an agent needs to inspect sources, plan a new dataset, save a scratch result, and validate it. Use the REST API for deterministic day-to-day reads and refreshes once the dataset already exists.

Dataset types

Dashboard-owned datasets

Dreambase creates these behind dashboard workflows. They use the same saved-result model as other datasets, but save_dataset cannot redefine them because their bound dashboard components must not silently change. Use refresh_dataset to replay the saved definition unchanged.

Scratch datasets

The save_dataset tool creates a queryable snapshot with an expiry of about seven days. Scratch is the default for exploration: inspect the preview, query the result, and let unhelpful work expire.

Promoted datasets

The promote_dataset tool clears a verified scratch dataset’s expiry. Promotion changes retention only; it does not rerun the source or alter the saved rows. Promotion currently cannot be undone through MCP, REST, or the app, so it requires a separate affirmative confirmation.

Stable dataset reads

list_datasets

MCP and REST · datasets:read

{ workspaceId, limit?, cursor? }

Lists bounded dataset handles without rows: dataset id, name, columns, row count, expiry, and queryability. Page until nextCursor is absent.

get_dataset

MCP and REST · datasets:read

{ workspaceId, datasetId }

Returns one full dataset handle, including cached per-column profile statistics.

query_dataset

MCP only · datasets:read

{ workspaceId, datasetId, sql }

Runs exactly one read-only DuckDB SELECT over one dataset, exposed to the query as the table dataset. Results are capped at 500 rows and 16 KiB; aggregate, filter, or page rather than assuming a truncated response is complete.

Sample a dataset

query_dataset({ workspaceId: "<workspace-id>", datasetId: "<dataset-id>", sql: "SELECT * FROM dataset LIMIT 20" })

Create a dataset through MCP

Dataset creation is an exploratory agent workflow. The agent should discover the connected source, fetch its planning schema, plan the required datasets, save one plan at a time, and validate the exact persisted rows.

1. Call list_connections to find the source.

2. Call get_connection for the compact catalog and to recover an unscanned MCP manifest.

3. Call search_connection for the exact relations, endpoints, tools, columns, and full planning schemas required by the question.

4. Assemble discoveryMarkdown and call plan_datasets with the analytical intent.

5. If the planner returns clarification, relay it to the user. Do not invent the missing decision.

6. Pass an authorized validated plan to save_dataset, one plan per call.

7. Inspect the returned preview and profile, then use query_dataset for targeted checks.

8. Promote only after explaining what was verified, naming the dataset and storage implication, and receiving a separate affirmative reply.

plan_datasets

MCP only · datasets:read

{ workspaceId, intent, discoveryMarkdown, topicContexts?, connectionIds? }

Returns validated dataset plans, a clarification, or a terminal error. Planning is non-persistent; only save_dataset writes a dataset. Connected API and MCP probes are conservatively open-world.

save_dataset

MCP only · datasets:read + datasets:write

{ workspaceId, datasetId?, name, description?, source, transform? }

Executes an exact SQL, API, or MCP source and stores the result. Omit datasetId to create a scratch dataset; pass a standalone dataset id to re-execute and replace it. Creating is non-idempotent—after an ambiguous failure, call list_datasets before retrying.

promote_dataset

MCP only · datasets:read + datasets:write

{ workspaceId, datasetId }

Clears a verified scratch dataset’s TTL. It does not rerun the source. The action currently cannot be undone and must follow explicit confirmation.

Refresh an existing dataset

refresh_dataset

MCP and REST · datasets:read + datasets:write

{ workspaceId, datasetId }

Replays the saved definition and replaces the rows. Scratch TTL is renewed; durable datasets remain durable. API POST and MCP sources may have external effects. Do not blind-retry an ambiguous failure.

Refresh through the API

curl -X POST \ https://api.dreambase.com/v1/workspaces/<workspace-id>/datasets/<dataset-id>/refresh \ -H "Authorization: Bearer <access-token>"

Day-to-day automation

Once a dataset definition is established, prefer the REST API for scheduled or application-driven operations. List datasets, retrieve metadata, and request an explicit refresh without asking an agent to rediscover the task every time. REST dataset reads remain metadata-only; row querying is MCP-only.

• API Reference — Use the deterministic REST endpoints for recurring integrations.

• Official Dreambase MCP — Install MCP and review the complete external-agent tool catalog.

• MCP Use Cases — See worked exploratory and artifact-building examples.

Important boundaries

• There is no standalone dataset viewer in the current product.

• REST exposes dataset metadata and refresh, not dataset rows or raw SQL.

• query_dataset reads one dataset per call.

• A queryable=false legacy dataset needs a dashboard refresh before row querying.

• Scratch saves expire after about seven days unless refreshed or promoted.

• Dataset write and planning tools require the scopes shown above and a deployment that exposes them.

• A successful tool call does not prove the analytical result is correct.