Dashboards

A dashboard is a saved grid of panels that visualize the results of Hamelin queries over a Space's datasets. Its resource ID is prefixed DSH_.

A dashboard holds an ordered list of panels laid out on a 24-column grid. Each visualization panel carries one or more Hamelin queries and a Vega-Lite or table spec that renders the results. Panels run their queries against the datasets in the dashboard's Space, and fromDatasets names those datasets. Template variables let a panel query reference ${variable} placeholders that a reader picks values for at view time. A dashboard is content.

Panels

A panel is one entry in the panels array. The type field discriminates four kinds. Every panel carries an id and a layout. Every kind except title carries an optional title.

Field	Type	Required	Description
id	string	Required	Unique panel identifier within the dashboard.
type	enum	Required	Panel kind: vega-lite, table, markdown, or title. Determines which other fields apply.
layout	object	Required	Grid placement. See Panel layout.
title	object	Optional	Panel heading. See Panel title. Omitted from title-type panels, which supply their own required title.

Fields by panel type:

Panel type	Field	Type	Required	Description
vega-lite	query	string	Required	Single Hamelin query. Kept for backward compatibility with single-query panels.
vega-lite	queries	array<PanelQuery>	Optional	Multiple named queries. Each has id (the Vega dataset key), name (the tab label), and query.
vega-lite	spec	object	Required	The Vega-Lite specification, as an object. Validated at render time.
vega-lite	timeRange	string	Optional	Panel time range. Empty inherits the dashboard's defaultTimeRange.
table	query	string	Required	Hamelin query whose result rows fill the table.
table	timeRange	string	Optional	Panel time range. Empty inherits the dashboard's defaultTimeRange.
markdown	content	string	Optional	Markdown or rich-text body.
title	title	object	Required	Section header. Same shape as Panel title but size defaults to md.
title	collapsed	boolean	Optional	Whether the panels grouped under this title are hidden in the rendered grid.

Panel layout

Placement on the 24-column grid. All values are integers.

Field	Type	Required	Description
x	integer	Required	Column of the panel's left edge.
y	integer	Required	Row of the panel's top edge.
w	integer	Required	Width in columns.
h	integer	Required	Height in rows.

Panel title

Field	Type	Required	Description
text	string	Required	The heading text.
align	enum	Optional	Horizontal alignment: left, center, or right. Default left.
size	enum	Optional	Text size: sm, md, or lg. Default sm for content panels, md for title panels.

Template variables

A template variable is one entry in templateVariables. A panel query references it as ${name}, and a reader selects a value from the variable's values list. The kind field discriminates two kinds. A primitive variable substitutes a typed literal. An identifier_fragment variable substitutes an identifier segment, so its values are restricted to letters, digits, and underscores.

Field	Type	Required	Description
id	string	Required	Unique variable identifier within the dashboard.
name	string	Required	The name referenced as ${name}. Starts with a letter or underscore, then letters, digits, and underscores. Cannot be a reserved name (__proto__, constructor, prototype, hasOwnProperty, toString, valueOf). Unique within the dashboard.
kind	enum	Required	primitive or identifier_fragment.
type	enum	Required for primitive	The literal type: int, double, boolean, string, or interval. Every value must parse as this type. An interval value is a positive integer and a unit, such as 1h, 15min, or 7d.
values	array<string>	Required	The selectable values. For identifier_fragment, each value contains only letters, digits, and underscores.
defaultValue	string	Required	The value selected by default. Must appear in values.
description	string	Optional	Free-text description of the variable.

Export file

A dashboard, or a single panel, can be exported to a JSON file and imported into another dashboard. The file is a versioned envelope. The kind field discriminates the two shapes.

Field	Type	Required	Description
version	integer	Required	Export schema version. Currently 1.
kind	enum	Required	dashboard for a whole dashboard, panel for a single panel.
dashboard	object	Required for dashboard	The dashboard body: name, panels, templateVariables, refreshInterval, and defaultTimeRange.
panel	object	Required for panel	A single Panel object.
metadata	object	Optional	Provenance recorded at export, such as dashboardId, organizationId, folderPath, and exportedAt. Ignored on import.

Inputs

Field	Type	Required	Description
name	string	Required	Dashboard name. Unique within its Space and folder.
panels	array<Panel>	Required	The panels rendered on the grid, in order. See Panels.
templateVariables	array<TemplateVariable>	Optional	Named variables that panel queries reference as ${name}. Names must be unique within the dashboard. See Template variables.
refreshInterval	enum	Optional	Auto-refresh cadence in milliseconds: 0 (no auto-refresh), 900000 (15 minutes), or 3600000 (1 hour). Default 0.
defaultTimeRange	string	Optional	Dashboard-wide time range applied to panels that do not set their own. A Hamelin range expression such as -1h or -24h..now(). Default -1h.
folderPath	string	Optional	Folder location within the Space, e.g. Dashboards/AWS.
spaceId	string	Required on create	The Space the dashboard belongs to, prefixed SPC_. Immutable after creation.

Outputs

Field	Type	Description
folderId	string	The containing folder, prefixed FLD_. Null when the dashboard sits at the Space root.
fromDatasets	array<object>	The datasets this dashboard's panels query. Each entry has name, resourceName, resourceId, and spaceId.

Plus the common resource fields.

Related

• Spaces, the container whose datasets a dashboard's panels query.
• Content, where a dashboard sits among Perpetual's resources.
• Changesets, how edits to a dashboard are staged and committed.
• Folders, how dashboards are organized within a Space.
• Visualize query results, how to build a panel from a query.