Search
Getting Started
Feature guides
Observability
External Data Sources
Dreambase Plugin & MCP
Community support
Named values computed from datasets, with a history point recorded on every scheduled refresh.
A metric is a named value computed from one (multiple datasets support coming soon) saved dataset. Examples include: weekly signups, monthly revenue, or active teams. Dreambase records the value on each scheduled refresh of the dataset, so every metric accumulates its own history.
Metrics are standalone objects. A metric may be added to a domain, and can be attached to a trigger.
How metrics work
Definition
A metric is a single read-only SQL SELECT over its dataset that returns exactly one row with one column named value. Aggregations, ratios, and filters all belong in that query. The dataset is referenced as a table by its id:
SELECT count(*) AS value FROM "<dataset-id>" WHERE created_at >= now() - INTERVAL 7
A metric also has a title, a one-line description, and a number format. Dreambase validates and executes the query before saving, and rejects any query that can return more than one row or does not return a single value column.
Current value
A metric’s current value is computed from the dataset’s stored rows at read time. Freshness follows the dataset: when the dataset is stale or its refresh is paused, the metric reports the same state.
History
Each scheduled refresh of the dataset records one point. Manual refreshes record no points. History resolves to one value per day, the day’s last point, in the schedule’s time zone.
Changes over 7 days and 14 days compare the newest point with the matching earlier day. When that day is missing, the change is blank, not zero.
A metric is stale when its newest point is older than two schedule intervals, and never less than a day.
Changing a metric’s query or dataset redefines the metric and resets its history. Changing its title, format, or description does not.
Metrics in the app
Metrics lists every metric with its current value, 7-day and 14-day change, and a two-week sparkline. Metrics can be pinned to the top of the list and filtered by domain, schedule, or source.
Each metric page has three tabs:
Overview: current value, recent change, and where the metric is used.
History: every recorded point.
Definition: the SQL, the source dataset, and the format.
Metrics are created and changed through the workspace chat, MCP, or REST. Metrics can be deleted from their page.
Watch a metric with a trigger
A trigger can watch any metric and send an alert when it crosses a threshold, such as signups falling 30% week over week. The trigger is judged after each scheduled refresh of the metric’s dataset. See Triggers.
Tool reference
list_metrics
MCP and REST · metrics:read
{ workspaceId, search?, datasetId?, dashboardId?, dataDomainId?, limit?, cursor? }
Lists the workspace’s metrics, most recently updated first, each with its id, title, description, dataset and domains. Call it before creating a metric to update an existing one instead of adding a duplicate.
get_metric
MCP and REST · metrics:read
{ workspaceId, metricId }
Returns a metric’s definition: title, description, dataset, format and datasetQuery.
create_metric
MCP and REST · metrics:read + metrics:write + datasets:read
{ workspaceId, datasetId, title, description?, datasetQuery, format, settings? }
Saves a new metric over one saved dataset and returns it with its current value. Scratch datasets are rejected, because their metrics would be deleted with them; promote the dataset with promote_dataset first. Test the query with query_dataset before calling. Not idempotent.
update_metric
MCP and REST · metrics:read + metrics:write + datasets:read
{ workspaceId, metricId, title?, description?, datasetId?, datasetQuery?, format?, settings? }
Updates the supplied fields. A new datasetQuery or datasetId redefines the metric and resets its history.
delete_metric
MCP and REST · metrics:read + metrics:write
{ workspaceId, metricId }
Deletes a metric. Irreversible.
get_metric_values
MCP and REST · metrics:read + datasets:read
{ workspaceId, metricIds }
Reads the current values of up to 20 metrics from their stored datasets without triggering a refresh. Each value includes the time its data was read, or the reason it is missing.
query_metric_history
MCP only · metrics:read
{ workspaceId, sql }
Runs one read-only DuckDB SELECT over metric history. Each metric is the table "<metric-id>" with the columns day, bucket_at and value; join metrics USING (day). Up to 20 metrics per query over the last 366 days.
get_metric_history
REST only · metrics:read
{ workspaceId, metricIds, from?, to? }
Returns up to 20 metrics’ daily points, oldest first, for charting: the last 90 days by default and at most 366.
Read current values through the API
curl "https://api.dreambase.com/v1/workspaces/<workspace-id>/metrics/values?metricIds=<metric-id>,<metric-id>" \ -H "Authorization: Bearer <access-token>"
REST paths: GET and POST /workspaces/{workspace_id}/metrics, GET, PATCH and DELETE /workspaces/{workspace_id}/metrics/{metric_id}, GET /workspaces/{workspace_id}/metrics/values, GET /workspaces/{workspace_id}/metrics/history.
Datasets — The saved results metrics read.
Domains — Group metrics by business area.
Triggers — Alert when a metric crosses a threshold.
Important boundaries
Metrics require analytics on for the workspace.
A metric reads exactly one dataset. Queries across multiple datasets cannot be saved as metrics.
Metrics cannot be saved on scratch datasets. Promote the dataset first.
History is recorded only by scheduled refreshes. A dataset without a schedule produces no history.
Deleting a dataset deletes its metrics.
Metric deletion is irreversible.
A metric is a named value computed from one (multiple datasets support coming soon) saved dataset. Examples include: weekly signups, monthly revenue, or active teams. Dreambase records the value on each scheduled refresh of the dataset, so every metric accumulates its own history.
Metrics are standalone objects. A metric may be added to a domain, and can be attached to a trigger.
How metrics work
Definition
A metric is a single read-only SQL SELECT over its dataset that returns exactly one row with one column named value. Aggregations, ratios, and filters all belong in that query. The dataset is referenced as a table by its id:
SELECT count(*) AS value FROM "<dataset-id>" WHERE created_at >= now() - INTERVAL 7
A metric also has a title, a one-line description, and a number format. Dreambase validates and executes the query before saving, and rejects any query that can return more than one row or does not return a single value column.
Current value
A metric’s current value is computed from the dataset’s stored rows at read time. Freshness follows the dataset: when the dataset is stale or its refresh is paused, the metric reports the same state.
History
Each scheduled refresh of the dataset records one point. Manual refreshes record no points. History resolves to one value per day, the day’s last point, in the schedule’s time zone.
Changes over 7 days and 14 days compare the newest point with the matching earlier day. When that day is missing, the change is blank, not zero.
A metric is stale when its newest point is older than two schedule intervals, and never less than a day.
Changing a metric’s query or dataset redefines the metric and resets its history. Changing its title, format, or description does not.
Metrics in the app
Metrics lists every metric with its current value, 7-day and 14-day change, and a two-week sparkline. Metrics can be pinned to the top of the list and filtered by domain, schedule, or source.
Each metric page has three tabs:
Overview: current value, recent change, and where the metric is used.
History: every recorded point.
Definition: the SQL, the source dataset, and the format.
Metrics are created and changed through the workspace chat, MCP, or REST. Metrics can be deleted from their page.
Watch a metric with a trigger
A trigger can watch any metric and send an alert when it crosses a threshold, such as signups falling 30% week over week. The trigger is judged after each scheduled refresh of the metric’s dataset. See Triggers.
Tool reference
list_metrics
MCP and REST · metrics:read
{ workspaceId, search?, datasetId?, dashboardId?, dataDomainId?, limit?, cursor? }
Lists the workspace’s metrics, most recently updated first, each with its id, title, description, dataset and domains. Call it before creating a metric to update an existing one instead of adding a duplicate.
get_metric
MCP and REST · metrics:read
{ workspaceId, metricId }
Returns a metric’s definition: title, description, dataset, format and datasetQuery.
create_metric
MCP and REST · metrics:read + metrics:write + datasets:read
{ workspaceId, datasetId, title, description?, datasetQuery, format, settings? }
Saves a new metric over one saved dataset and returns it with its current value. Scratch datasets are rejected, because their metrics would be deleted with them; promote the dataset with promote_dataset first. Test the query with query_dataset before calling. Not idempotent.
update_metric
MCP and REST · metrics:read + metrics:write + datasets:read
{ workspaceId, metricId, title?, description?, datasetId?, datasetQuery?, format?, settings? }
Updates the supplied fields. A new datasetQuery or datasetId redefines the metric and resets its history.
delete_metric
MCP and REST · metrics:read + metrics:write
{ workspaceId, metricId }
Deletes a metric. Irreversible.
get_metric_values
MCP and REST · metrics:read + datasets:read
{ workspaceId, metricIds }
Reads the current values of up to 20 metrics from their stored datasets without triggering a refresh. Each value includes the time its data was read, or the reason it is missing.
query_metric_history
MCP only · metrics:read
{ workspaceId, sql }
Runs one read-only DuckDB SELECT over metric history. Each metric is the table "<metric-id>" with the columns day, bucket_at and value; join metrics USING (day). Up to 20 metrics per query over the last 366 days.
get_metric_history
REST only · metrics:read
{ workspaceId, metricIds, from?, to? }
Returns up to 20 metrics’ daily points, oldest first, for charting: the last 90 days by default and at most 366.
Read current values through the API
curl "https://api.dreambase.com/v1/workspaces/<workspace-id>/metrics/values?metricIds=<metric-id>,<metric-id>" \ -H "Authorization: Bearer <access-token>"
REST paths: GET and POST /workspaces/{workspace_id}/metrics, GET, PATCH and DELETE /workspaces/{workspace_id}/metrics/{metric_id}, GET /workspaces/{workspace_id}/metrics/values, GET /workspaces/{workspace_id}/metrics/history.
Datasets — The saved results metrics read.
Domains — Group metrics by business area.
Triggers — Alert when a metric crosses a threshold.
Important boundaries
Metrics require analytics on for the workspace.
A metric reads exactly one dataset. Queries across multiple datasets cannot be saved as metrics.
Metrics cannot be saved on scratch datasets. Promote the dataset first.
History is recorded only by scheduled refreshes. A dataset without a schedule produces no history.
Deleting a dataset deletes its metrics.
Metric deletion is irreversible.
A metric is a named value computed from one (multiple datasets support coming soon) saved dataset. Examples include: weekly signups, monthly revenue, or active teams. Dreambase records the value on each scheduled refresh of the dataset, so every metric accumulates its own history.
Metrics are standalone objects. A metric may be added to a domain, and can be attached to a trigger.
How metrics work
Definition
A metric is a single read-only SQL SELECT over its dataset that returns exactly one row with one column named value. Aggregations, ratios, and filters all belong in that query. The dataset is referenced as a table by its id:
SELECT count(*) AS value FROM "<dataset-id>" WHERE created_at >= now() - INTERVAL 7
A metric also has a title, a one-line description, and a number format. Dreambase validates and executes the query before saving, and rejects any query that can return more than one row or does not return a single value column.
Current value
A metric’s current value is computed from the dataset’s stored rows at read time. Freshness follows the dataset: when the dataset is stale or its refresh is paused, the metric reports the same state.
History
Each scheduled refresh of the dataset records one point. Manual refreshes record no points. History resolves to one value per day, the day’s last point, in the schedule’s time zone.
Changes over 7 days and 14 days compare the newest point with the matching earlier day. When that day is missing, the change is blank, not zero.
A metric is stale when its newest point is older than two schedule intervals, and never less than a day.
Changing a metric’s query or dataset redefines the metric and resets its history. Changing its title, format, or description does not.
Metrics in the app
Metrics lists every metric with its current value, 7-day and 14-day change, and a two-week sparkline. Metrics can be pinned to the top of the list and filtered by domain, schedule, or source.
Each metric page has three tabs:
Overview: current value, recent change, and where the metric is used.
History: every recorded point.
Definition: the SQL, the source dataset, and the format.
Metrics are created and changed through the workspace chat, MCP, or REST. Metrics can be deleted from their page.
Watch a metric with a trigger
A trigger can watch any metric and send an alert when it crosses a threshold, such as signups falling 30% week over week. The trigger is judged after each scheduled refresh of the metric’s dataset. See Triggers.
Tool reference
list_metrics
MCP and REST · metrics:read
{ workspaceId, search?, datasetId?, dashboardId?, dataDomainId?, limit?, cursor? }
Lists the workspace’s metrics, most recently updated first, each with its id, title, description, dataset and domains. Call it before creating a metric to update an existing one instead of adding a duplicate.
get_metric
MCP and REST · metrics:read
{ workspaceId, metricId }
Returns a metric’s definition: title, description, dataset, format and datasetQuery.
create_metric
MCP and REST · metrics:read + metrics:write + datasets:read
{ workspaceId, datasetId, title, description?, datasetQuery, format, settings? }
Saves a new metric over one saved dataset and returns it with its current value. Scratch datasets are rejected, because their metrics would be deleted with them; promote the dataset with promote_dataset first. Test the query with query_dataset before calling. Not idempotent.
update_metric
MCP and REST · metrics:read + metrics:write + datasets:read
{ workspaceId, metricId, title?, description?, datasetId?, datasetQuery?, format?, settings? }
Updates the supplied fields. A new datasetQuery or datasetId redefines the metric and resets its history.
delete_metric
MCP and REST · metrics:read + metrics:write
{ workspaceId, metricId }
Deletes a metric. Irreversible.
get_metric_values
MCP and REST · metrics:read + datasets:read
{ workspaceId, metricIds }
Reads the current values of up to 20 metrics from their stored datasets without triggering a refresh. Each value includes the time its data was read, or the reason it is missing.
query_metric_history
MCP only · metrics:read
{ workspaceId, sql }
Runs one read-only DuckDB SELECT over metric history. Each metric is the table "<metric-id>" with the columns day, bucket_at and value; join metrics USING (day). Up to 20 metrics per query over the last 366 days.
get_metric_history
REST only · metrics:read
{ workspaceId, metricIds, from?, to? }
Returns up to 20 metrics’ daily points, oldest first, for charting: the last 90 days by default and at most 366.
Read current values through the API
curl "https://api.dreambase.com/v1/workspaces/<workspace-id>/metrics/values?metricIds=<metric-id>,<metric-id>" \ -H "Authorization: Bearer <access-token>"
REST paths: GET and POST /workspaces/{workspace_id}/metrics, GET, PATCH and DELETE /workspaces/{workspace_id}/metrics/{metric_id}, GET /workspaces/{workspace_id}/metrics/values, GET /workspaces/{workspace_id}/metrics/history.
Datasets — The saved results metrics read.
Domains — Group metrics by business area.
Triggers — Alert when a metric crosses a threshold.
Important boundaries
Metrics require analytics on for the workspace.
A metric reads exactly one dataset. Queries across multiple datasets cannot be saved as metrics.
Metrics cannot be saved on scratch datasets. Promote the dataset first.
History is recorded only by scheduled refreshes. A dataset without a schedule produces no history.
Deleting a dataset deletes its metrics.
Metric deletion is irreversible.