dashboards

Creates, updates, deletes, gets or lists a dashboards resource.

Overview

Name	dashboards
Type	Resource
Id	clickhouse.clickstack.dashboards

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	Dashboard ID (example: 65f5e4a3b9e77c001a567890)
name	string	Dashboard name (example: Service Overview)
containers	array	Optional grouping containers. Each tile may join a container via tile.containerId, and a tab inside it via tile.tabId.
filters	array	Dashboard filter keys added to the dashboard and applied to all tiles
saved_filter_values	array	Optional default dashboard filter values restored when loading the dashboard. (wire: savedFilterValues)
saved_query	string	Optional default dashboard query restored when loading the dashboard. (example: service.name = 'api') (wire: savedQuery)
saved_query_language	string	Query language used by savedQuery. (sql, lucene) (example: sql) (wire: savedQueryLanguage)
tags	array	Tags for organizing and filtering dashboards
tiles	array	List of tiles/charts in the dashboard

list

Name	Datatype	Description
id	string	Dashboard ID (example: 65f5e4a3b9e77c001a567890)
name	string	Dashboard name (example: Service Overview)
containers	array	Optional grouping containers. Each tile may join a container via tile.containerId, and a tab inside it via tile.tabId.
filters	array	Dashboard filter keys added to the dashboard and applied to all tiles
saved_filter_values	array	Optional default dashboard filter values restored when loading the dashboard. (wire: savedFilterValues)
saved_query	string	Optional default dashboard query restored when loading the dashboard. (example: service.name = 'api') (wire: savedQuery)
saved_query_language	string	Query language used by savedQuery. (sql, lucene) (example: sql) (wire: savedQueryLanguage)
tags	array	Tags for organizing and filtering dashboards
tiles	array	List of tiles/charts in the dashboard

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	service_id, click_stack_dashboard_id, organization_id		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Retrieves a specific dashboard by ID
list	select	service_id, organization_id		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Retrieves a list of all dashboards for the authenticated team
create	insert	service_id, organization_id, name, tiles		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Creates a new dashboard
update	update	service_id, click_stack_dashboard_id, organization_id, name, tiles		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Updates an existing dashboard. Concurrency: This endpoint does not support optimistic concurrency control. Concurrent PUT requests for the same dashboard may silently overwrite each other, which can leave orphan tile-to-container references on layout-shape edits. Clients should serialize edits to a given dashboard.
delete	delete	service_id, click_stack_dashboard_id, organization_id		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Deletes a dashboard
validate	exec	serviceId, organization_id, name, tiles		This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Validates a dashboard body against the same schema and tile rules used by POST /api/v2/dashboards. The dashboard is never persisted. Use this endpoint at plan time (e.g. from a Terraform provider) to check that a dashboard configuration is valid before applying it.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
click_stack_dashboard_id	string	ClickStack Dashboard ID (wire: clickStackDashboardId)
organization_id	string	ClickHouse Cloud organization ID. Resolved from the CLICKHOUSE_ORG_ID environment variable when it is set (x-stackQL-envVar); otherwise it must be supplied on every query as WHERE organization_id = <uuid>. A WHERE value always takes precedence over the environment. (x-stackQL-envVar: CLICKHOUSE_ORG_ID)
serviceId	string (uuid)	ID of the ClickStack service.
service_id	string (uuid)	ID of the ClickStack service. (wire: serviceId)

SELECT examples

get

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Retrieves a specific dashboard by ID

SELECT
id,
name,
containers,
filters,
saved_filter_values,
saved_query,
saved_query_language,
tags,
tiles
FROM clickhouse.clickstack.dashboards
WHERE service_id = '{{ service_id }}' -- required
AND click_stack_dashboard_id = '{{ click_stack_dashboard_id }}' -- required
AND organization_id = '{{ organization_id }}' -- required unless CLICKHOUSE_ORG_ID is set
;

list

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Retrieves a list of all dashboards for the authenticated team

SELECT
id,
name,
containers,
filters,
saved_filter_values,
saved_query,
saved_query_language,
tags,
tiles
FROM clickhouse.clickstack.dashboards
WHERE service_id = '{{ service_id }}' -- required
AND organization_id = '{{ organization_id }}' -- required unless CLICKHOUSE_ORG_ID is set
;

INSERT examples

create

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Creates a new dashboard

INSERT INTO clickhouse.clickstack.dashboards (
name,
tiles,
tags,
filters,
saved_query,
saved_query_language,
saved_filter_values,
containers,
service_id,
organization_id
)
SELECT 
'{{ name }}' /* required */,
'{{ tiles }}' /* required */,
'{{ tags }}',
'{{ filters }}',
'{{ saved_query }}',
'{{ saved_query_language }}',
'{{ saved_filter_values }}',
'{{ containers }}',
'{{ service_id }}',
'{{ organization_id }}'
RETURNING
request_id,
result,
status
;

Manifest

# Description fields are for documentation purposes
- name: dashboards
props:
  - name: service_id
    value: "{{ service_id }}"
    description: Required parameter for the dashboards resource.
  - name: organization_id
    value: "{{ organization_id }}"
    description: Required parameter for the dashboards resource.
  - name: name
    value: "{{ name }}"
    description: |
      Dashboard name.
  - name: tiles
    description: |
      List of tiles/charts to include in the dashboard.
    value:
      - name: "{{ name }}"
        x: {{ x }}
        y: {{ y }}
        w: {{ w }}
        h: {{ h }}
        config:
          displayType: "{{ displayType }}"
          sourceId: "{{ sourceId }}"
          select:
            - aggFn: "{{ aggFn }}"
              valueExpression: "{{ valueExpression }}"
              alias: "{{ alias }}"
              level: {{ level }}
              where: "{{ where }}"
              whereLanguage: "{{ whereLanguage }}"
              metricName: "{{ metricName }}"
              metricType: "{{ metricType }}"
              periodAggFn: "{{ periodAggFn }}"
              numberFormat:
                output: "{{ output }}"
                mantissa: {{ mantissa }}
                thousandSeparated: {{ thousandSeparated }}
                average: {{ average }}
                decimalBytes: {{ decimalBytes }}
                factor: {{ factor }}
                currencySymbol: "{{ currencySymbol }}"
                numericUnit: "{{ numericUnit }}"
                unit: "{{ unit }}"
          groupBy: "{{ groupBy }}"
          asRatio: {{ asRatio }}
          alignDateRangeToGranularity: {{ alignDateRangeToGranularity }}
          fillNulls: {{ fillNulls }}
          fitYAxisToData: {{ fitYAxisToData }}
          numberFormat:
            output: "{{ output }}"
            mantissa: {{ mantissa }}
            thousandSeparated: {{ thousandSeparated }}
            average: {{ average }}
            decimalBytes: {{ decimalBytes }}
            factor: {{ factor }}
            currencySymbol: "{{ currencySymbol }}"
            numericUnit: "{{ numericUnit }}"
            unit: "{{ unit }}"
          compareToPreviousPeriod: {{ compareToPreviousPeriod }}
          configType: "{{ configType }}"
          connectionId: "{{ connectionId }}"
          sqlTemplate: "{{ sqlTemplate }}"
          having: "{{ having }}"
          orderBy: "{{ orderBy }}"
          groupByColumnsOnLeft: {{ groupByColumnsOnLeft }}
          onClick:
            type: "{{ type }}"
            target:
              mode: "{{ mode }}"
              id: "{{ id }}"
              template: "{{ template }}"
            whereTemplate: "{{ whereTemplate }}"
            whereLanguage: "{{ whereLanguage }}"
            filters:
              - kind: "{{ kind }}"
                expression: "{{ expression }}"
                template: "{{ template }}"
            urlTemplate: "{{ urlTemplate }}"
          color: "{{ color }}"
          colorRules:
            - operator: "{{ operator }}"
              value: {{ value }}
              color: "{{ color }}"
              label: "{{ label }}"
          backgroundChart:
            type: "{{ type }}"
            color: "{{ color }}"
          limit: {{ limit }}
          where: "{{ where }}"
          whereLanguage: "{{ whereLanguage }}"
          markdown: "{{ markdown }}"
        containerId: "{{ containerId }}"
        tabId: "{{ tabId }}"
        id: "{{ id }}"
        asRatio: {{ asRatio }}
        series: "{{ series }}"
  - name: tags
    value:
      - "{{ tags }}"
    description: |
      Tags for organizing and filtering dashboards.
  - name: filters
    description: |
      Dashboard filter keys to add to the dashboard and apply across all tiles
    value:
      - type: "{{ type }}"
        name: "{{ name }}"
        expression: "{{ expression }}"
        sourceId: "{{ sourceId }}"
        sourceMetricType: "{{ sourceMetricType }}"
        where: "{{ where }}"
        whereLanguage: "{{ whereLanguage }}"
        appliesToSourceIds: "{{ appliesToSourceIds }}"
  - name: saved_query
    value: "{{ saved_query }}"
    description: |
      Optional default dashboard query to persist on the dashboard.
  - name: saved_query_language
    value: "{{ saved_query_language }}"
    description: |
      Query language used by savedQuery.
    valid_values: ['sql', 'lucene']
  - name: saved_filter_values
    description: |
      Optional default dashboard filter values to persist on the dashboard.
    value:
      - type: "{{ type }}"
        condition: "{{ condition }}"
  - name: containers
    description: |
      Optional grouping containers. Each tile may join a container via tile.containerId, and a tab inside it via tile.tabId.
    value:
      - id: "{{ id }}"
        title: "{{ title }}"
        collapsed: {{ collapsed }}
        collapsible: {{ collapsible }}
        bordered: {{ bordered }}
        tabs: "{{ tabs }}"

UPDATE examples

update

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Updates an existing dashboard. Concurrency: This endpoint does not support optimistic concurrency control. Concurrent PUT requests for the same dashboard may silently overwrite each other, which can leave orphan tile-to-container references on layout-shape edits. Clients should serialize edits to a given dashboard.

UPDATE clickhouse.clickstack.dashboards
SET 
name = '{{ name }}',
tiles = '{{ tiles }}',
tags = '{{ tags }}',
filters = '{{ filters }}',
saved_query = '{{ saved_query }}',
saved_query_language = '{{ saved_query_language }}',
saved_filter_values = '{{ saved_filter_values }}',
containers = '{{ containers }}'
WHERE 
service_id = '{{ service_id }}' --required
AND click_stack_dashboard_id = '{{ click_stack_dashboard_id }}' --required
AND organization_id = '{{ organization_id }}' --required unless CLICKHOUSE_ORG_ID is set
AND name = '{{ name }}' --required
AND tiles = '{{ tiles }}' --required
RETURNING
request_id,
result,
status;

DELETE examples

delete

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Deletes a dashboard

DELETE FROM clickhouse.clickstack.dashboards
WHERE service_id = '{{ service_id }}' --required
AND click_stack_dashboard_id = '{{ click_stack_dashboard_id }}' --required
AND organization_id = '{{ organization_id }}' --required unless CLICKHOUSE_ORG_ID is set
;

Lifecycle Methods

EXEC variables use wire (API) names.

validate

This endpoint is in beta. API contract is stable, and no breaking changes are expected in the future. <br /><br /> ClickStack: Validates a dashboard body against the same schema and tile rules used by POST /api/v2/dashboards. The dashboard is never persisted. Use this endpoint at plan time (e.g. from a Terraform provider) to check that a dashboard configuration is valid before applying it.

EXEC clickhouse.clickstack.dashboards.validate 
@serviceId='{{ serviceId }}' --required, 
@organization_id='{{ organization_id }}' --required unless CLICKHOUSE_ORG_ID is set 
@@json=
'{
"name": "{{ name }}", 
"tiles": "{{ tiles }}", 
"tags": "{{ tags }}", 
"filters": "{{ filters }}", 
"savedQuery": "{{ savedQuery }}", 
"savedQueryLanguage": "{{ savedQueryLanguage }}", 
"savedFilterValues": "{{ savedFilterValues }}", 
"containers": "{{ containers }}"
}'
;