> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickStack: Create Dashboard

> **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

<span data-endpoint-badge="Beta"><Badge color="blue">Beta</Badge></span>

**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


## OpenAPI

````yaml _specs/cloud-openapi.json POST /v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards
openapi: 3.1.2
info:
  title: OpenAPI spec for ClickHouse Cloud
  version: '1.0'
  contact:
    name: ClickHouse Support
    url: >-
      https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-910487
    email: support@clickhouse.com
servers:
  - url: https://api.clickhouse.cloud
security:
  - basicAuth: []
tags:
  - name: Organization
  - name: User management
  - name: Billing
  - name: Role Management
  - name: Service
  - name: Backup
  - name: OpenAPI
  - name: Prometheus
  - name: ClickPipes
  - name: ClickStack
  - name: Postgres
paths:
  /v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards:
    post:
      tags:
        - ClickStack
      summary: 'ClickStack: Create Dashboard'
      description: >-
        **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
      operationId: clickStackCreateDashboard
      parameters:
        - in: path
          name: organizationId
          description: ID of the organization that owns the service.
          required: true
          schema:
            type: string
            format: uuid
        - in: path
          name: serviceId
          description: ID of the ClickStack service.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClickStackCreateDashboardRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 200
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
                  result:
                    $ref: '#/components/schemas/ClickStackDashboardResponse'
        '400':
          description: >-
            The request cannot be processed due to a client error. Please verify
            your request parameters and try again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: number
                    description: HTTP status code.
                    example: 400
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
        '500':
          description: >-
            An internal server error has occurred. If this issue persists,
            please contact ClickHouse Cloud support for assistance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code.
                    example: 500
                  error:
                    type: string
                    description: Detailed error description.
                  requestId:
                    type: string
                    description: Unique id assigned to every request. UUIDv4
                    format: uuid
components:
  schemas:
    ClickStackCreateDashboardRequest:
      properties:
        name:
          description: Dashboard name.
          type: string
          example: New Dashboard
        tiles:
          type: array
          description: List of tiles/charts to include in the dashboard.
          items:
            $ref: '#/components/schemas/ClickStackTileInput'
        tags:
          type: array
          description: Tags for organizing and filtering dashboards.
          items:
            type: string
          example:
            - development
        filters:
          type: array
          description: >-
            Dashboard filter keys to add to the dashboard and apply across all
            tiles
          items:
            $ref: '#/components/schemas/ClickStackFilterInput'
        savedQuery:
          description: Optional default dashboard query to persist on the dashboard.
          type:
            - string
            - 'null'
          example: service.name = 'api'
        savedQueryLanguage:
          description: Query language used by savedQuery.
          type:
            - string
            - 'null'
          enum:
            - sql
            - lucene
          example: sql
        savedFilterValues:
          type: array
          description: >-
            Optional default dashboard filter values to persist on the
            dashboard.
          items:
            $ref: '#/components/schemas/ClickStackSavedFilterValue'
        containers:
          type: array
          description: >-
            Optional grouping containers. Each tile may join a container via
            tile.containerId, and a tab inside it via tile.tabId.
          items:
            $ref: '#/components/schemas/ClickStackDashboardContainer'
      required:
        - name
        - tiles
    ClickStackDashboardResponse:
      properties:
        id:
          description: Dashboard ID
          type: string
          example: 65f5e4a3b9e77c001a567890
        name:
          description: Dashboard name
          type: string
          example: Service Overview
        tiles:
          type: array
          description: List of tiles/charts in the dashboard
          items:
            $ref: '#/components/schemas/ClickStackTileOutput'
        tags:
          type: array
          description: Tags for organizing and filtering dashboards
          items:
            type: string
          example:
            - production
            - monitoring
        filters:
          type: array
          description: >-
            Dashboard filter keys added to the dashboard and applied to all
            tiles
          items:
            $ref: '#/components/schemas/ClickStackFilter'
        savedQuery:
          description: >-
            Optional default dashboard query restored when loading the
            dashboard.
          type:
            - string
            - 'null'
          example: service.name = 'api'
        savedQueryLanguage:
          description: Query language used by savedQuery.
          type:
            - string
            - 'null'
          enum:
            - sql
            - lucene
          example: sql
        savedFilterValues:
          type: array
          description: >-
            Optional default dashboard filter values restored when loading the
            dashboard.
          items:
            $ref: '#/components/schemas/ClickStackSavedFilterValue'
        containers:
          type: array
          description: >-
            Optional grouping containers. Each tile may join a container via
            tile.containerId, and a tab inside it via tile.tabId.
          items:
            $ref: '#/components/schemas/ClickStackDashboardContainer'
    ClickStackTileInput:
      properties:
        name:
          description: Display name for the tile
          type: string
          example: Error Rate
        x:
          description: Horizontal position in the grid (0-based)
          type: integer
          example: 0
        'y':
          description: Vertical position in the grid (0-based)
          type: integer
          example: 0
        w:
          description: Width in grid units
          type: integer
          example: 6
        h:
          description: Height in grid units
          type: integer
          example: 3
        config:
          $ref: '#/components/schemas/ClickStackTileConfig'
        containerId:
          description: >-
            References a DashboardContainer by id. Tiles without containerId
            render in the default ungrouped area.
          type: string
          example: service-health
        tabId:
          description: >-
            References a tab inside the tile's container by id. Requires
            containerId to be set, and the container to declare a matching tab.
          type: string
          example: errors
        id:
          description: Optional tile ID. Omit to generate a new ID.
          type: string
          example: 65f5e4a3b9e77c001a901234
        asRatio:
          description: >-
            Display two series as a ratio (series[0] / series[1]). Only
            applicable when providing "series". Deprecated in favor of
            "config.asRatio".
          type: boolean
          example: false
          deprecated: true
        series:
          type: array
          description: >-
            Data series to display in this tile (all must be the same type).
            Deprecated; use "config" instead.
          items:
            $ref: '#/components/schemas/ClickStackDashboardChartSeries'
          deprecated: true
      required:
        - name
        - x
        - 'y'
        - w
        - h
    ClickStackFilterInput:
      properties:
        type:
          description: Filter type. Must be "QUERY_EXPRESSION".
          type: string
          enum:
            - QUERY_EXPRESSION
          example: QUERY_EXPRESSION
        name:
          description: Display name for the dashboard filter key
          type: string
          example: Environment
        expression:
          description: Key expression used when applying this dashboard filter key
          type: string
          example: environment
        sourceId:
          description: Source ID this dashboard filter key applies to
          type: string
          example: 65f5e4a3b9e77c001a111111
        sourceMetricType:
          description: Metric type when source is metrics
          type: string
          enum:
            - sum
            - gauge
            - histogram
            - summary
            - exponential histogram
          example: gauge
        where:
          description: >-
            Optional WHERE condition to scope which rows this filter key reads
            values from
          type: string
          example: ServiceName:api
        whereLanguage:
          description: Language of the where condition
          type: string
          enum:
            - sql
            - lucene
          example: lucene
      required:
        - type
        - name
        - expression
        - sourceId
    ClickStackSavedFilterValue:
      properties:
        type:
          description: Filter type. Currently only "sql" is supported.
          type: string
          enum:
            - sql
          example: sql
        condition:
          description: >-
            SQL filter condition. For example use expressions in the form
            "column IN ('value')".
          type: string
          example: ServiceName IN ('hdx-oss-dev-api')
      required:
        - condition
    ClickStackDashboardContainer:
      properties:
        id:
          description: Unique identifier for the container within the dashboard.
          type: string
          example: service-health
        title:
          description: Display title for the container.
          type: string
          example: Service Health
        collapsed:
          description: Persisted default collapse state. Per-viewer state lives in the URL.
          type: boolean
          example: false
        collapsible:
          description: Whether the user can collapse the group.
          type: boolean
          example: true
        bordered:
          description: Whether to show a visual border around the group.
          type: boolean
          example: true
        tabs:
          type: array
          description: >-
            Optional tabs. 2+ entries renders a tab bar; 0-1 entries renders a
            plain group header. Tiles join a tab via tabId.
          items:
            $ref: '#/components/schemas/ClickStackDashboardContainerTab'
      required:
        - id
        - title
        - collapsed
    ClickStackTileOutput:
      properties:
        name:
          description: Display name for the tile
          type: string
          example: Error Rate
        x:
          description: Horizontal position in the grid (0-based)
          type: integer
          example: 0
        'y':
          description: Vertical position in the grid (0-based)
          type: integer
          example: 0
        w:
          description: Width in grid units
          type: integer
          example: 6
        h:
          description: Height in grid units
          type: integer
          example: 3
        config:
          $ref: '#/components/schemas/ClickStackTileConfig'
        containerId:
          description: >-
            References a DashboardContainer by id. Tiles without containerId
            render in the default ungrouped area.
          type: string
          example: service-health
        tabId:
          description: >-
            References a tab inside the tile's container by id. Requires
            containerId to be set, and the container to declare a matching tab.
          type: string
          example: errors
        id:
          description: Unique tile ID assigned by the server.
          type: string
          example: 65f5e4a3b9e77c001a901234
      required:
        - name
        - x
        - 'y'
        - w
        - h
        - id
    ClickStackFilter:
      properties:
        type:
          description: Filter type. Must be "QUERY_EXPRESSION".
          type: string
          enum:
            - QUERY_EXPRESSION
          example: QUERY_EXPRESSION
        name:
          description: Display name for the dashboard filter key
          type: string
          example: Environment
        expression:
          description: Key expression used when applying this dashboard filter key
          type: string
          example: environment
        sourceId:
          description: Source ID this dashboard filter key applies to
          type: string
          example: 65f5e4a3b9e77c001a111111
        sourceMetricType:
          description: Metric type when source is metrics
          type: string
          enum:
            - sum
            - gauge
            - histogram
            - summary
            - exponential histogram
          example: gauge
        where:
          description: >-
            Optional WHERE condition to scope which rows this filter key reads
            values from
          type: string
          example: ServiceName:api
        whereLanguage:
          description: Language of the where condition
          type: string
          enum:
            - sql
            - lucene
          example: lucene
        id:
          description: Unique dashboard filter key ID
          type: string
      required:
        - type
        - name
        - expression
        - sourceId
        - id
    ClickStackTileConfig:
      oneOf:
        - $ref: '#/components/schemas/ClickStackLineChartConfig'
        - $ref: '#/components/schemas/ClickStackBarChartConfig'
        - $ref: '#/components/schemas/ClickStackTableChartConfig'
        - $ref: '#/components/schemas/ClickStackNumberChartConfig'
        - $ref: '#/components/schemas/ClickStackPieChartConfig'
        - $ref: '#/components/schemas/ClickStackHeatmapChartConfig'
        - $ref: '#/components/schemas/ClickStackSearchChartConfig'
        - $ref: '#/components/schemas/ClickStackMarkdownChartConfig'
    ClickStackDashboardChartSeries:
      oneOf:
        - $ref: '#/components/schemas/ClickStackTimeChartSeries'
        - $ref: '#/components/schemas/ClickStackTableChartSeries'
        - $ref: '#/components/schemas/ClickStackNumberChartSeries'
        - $ref: '#/components/schemas/ClickStackSearchChartSeries'
        - $ref: '#/components/schemas/ClickStackMarkdownChartSeries'
    ClickStackDashboardContainerTab:
      properties:
        id:
          description: Unique identifier for the tab within its container.
          type: string
          example: errors
        title:
          description: Display title for the tab.
          type: string
          example: Errors
      required:
        - id
        - title
    ClickStackLineChartConfig:
      oneOf:
        - $ref: '#/components/schemas/ClickStackLineBuilderChartConfig'
        - $ref: '#/components/schemas/ClickStackLineRawSqlChartConfig'
    ClickStackBarChartConfig:
      oneOf:
        - $ref: '#/components/schemas/ClickStackBarBuilderChartConfig'
        - $ref: '#/components/schemas/ClickStackBarRawSqlChartConfig'
    ClickStackTableChartConfig:
      oneOf:
        - $ref: '#/components/schemas/ClickStackTableBuilderChartConfig'
        - $ref: '#/components/schemas/ClickStackTableRawSqlChartConfig'
    ClickStackNumberChartConfig:
      oneOf:
        - $ref: '#/components/schemas/ClickStackNumberBuilderChartConfig'
        - $ref: '#/components/schemas/ClickStackNumberRawSqlChartConfig'
    ClickStackPieChartConfig:
      oneOf:
        - $ref: '#/components/schemas/ClickStackPieBuilderChartConfig'
        - $ref: '#/components/schemas/ClickStackPieRawSqlChartConfig'
    ClickStackHeatmapChartConfig:
      properties:
        displayType:
          description: Display type discriminator. Must be "heatmap" for heatmap tiles.
          type: string
          enum:
            - heatmap
          example: heatmap
        sourceId:
          description: ID of the data source to query.
          type: string
          example: 65f5e4a3b9e77c001a111111
        select:
          type: array
          description: Exactly one heatmap select item.
          items:
            $ref: '#/components/schemas/ClickStackHeatmapSelectItem'
        where:
          description: Row-level filter (syntax depends on whereLanguage).
          type: string
          example: ServiceName = 'api'
        whereLanguage:
          description: Query language for the where clause.
          type: string
          enum:
            - sql
            - lucene
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
      required:
        - displayType
        - sourceId
        - select
    ClickStackSearchChartConfig:
      properties:
        displayType:
          description: >-
            Display type discriminator. Must be "search" for search/log viewer
            tiles.
          type: string
          enum:
            - search
          example: search
        sourceId:
          description: ID of the data source to query.
          type: string
          example: 65f5e4a3b9e77c001a111111
        select:
          description: Comma-separated list of expressions to display.
          type: string
          example: timestamp, level, message
        where:
          description: Filter condition for the search (syntax depends on whereLanguage).
          type: string
          example: level:error
        whereLanguage:
          description: Query language for the where clause.
          type: string
          enum:
            - sql
            - lucene
      required:
        - displayType
        - sourceId
        - select
        - whereLanguage
    ClickStackMarkdownChartConfig:
      properties:
        displayType:
          description: >-
            Display type discriminator. Must be "markdown" for markdown text
            tiles.
          type: string
          enum:
            - markdown
          example: markdown
        markdown:
          description: Markdown content to render inside the tile.
          type: string
          example: |-
            # Dashboard Title

            This is a markdown widget.
      required:
        - displayType
    ClickStackTimeChartSeries:
      properties:
        type:
          description: Series type discriminator. Must be "time" for time-series charts.
          type: string
          enum:
            - time
          example: time
        sourceId:
          description: ID of the data source to query
          type: string
          example: 65f5e4a3b9e77c001a567890
        aggFn:
          description: Aggregation function to apply to the field or metric value
          type: string
          enum:
            - avg
            - count
            - count_distinct
            - last_value
            - max
            - min
            - quantile
            - sum
            - any
            - none
          example: count
        level:
          description: Percentile level for quantile aggregations (e.g., 0.95 for p95)
          type: number
          example: 0.95
        field:
          description: >-
            Column or expression to aggregate (required for most aggregation
            functions except count)
          type: string
          example: duration
        alias:
          description: Display name for the series in the chart
          type: string
          example: Request Duration
        where:
          description: Filter query for the data (syntax depends on whereLanguage)
          type: string
          example: service:api
        whereLanguage:
          description: Query language for the where clause
          type: string
          enum:
            - sql
            - lucene
          example: lucene
        groupBy:
          type: array
          description: Fields to group results by (creates separate series for each group)
          items:
            type: string
          example:
            - host
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
        metricDataType:
          description: Metric data type, only for metrics data sources.
          type: string
          enum:
            - sum
            - gauge
            - histogram
            - summary
            - exponential histogram
          example: sum
        metricName:
          description: Metric name for metrics data sources
          type: string
          example: http.server.duration
        displayType:
          description: Visual representation type for the time series
          type: string
          enum:
            - stacked_bar
            - line
          example: line
      required:
        - type
        - sourceId
        - aggFn
        - where
        - whereLanguage
        - groupBy
    ClickStackTableChartSeries:
      properties:
        type:
          description: Series type discriminator. Must be "table" for table charts.
          type: string
          enum:
            - table
          example: table
        sourceId:
          description: ID of the data source to query
          type: string
          example: 65f5e4a3b9e77c001a567890
        aggFn:
          description: Aggregation function to apply to the field or metric value
          type: string
          enum:
            - avg
            - count
            - count_distinct
            - last_value
            - max
            - min
            - quantile
            - sum
            - any
            - none
          example: count
        level:
          description: Percentile level for quantile aggregations (e.g., 0.95 for p95)
          type: number
          example: 0.95
        field:
          description: >-
            Column or expression to aggregate (required for most aggregation
            functions except count)
          type: string
          example: duration
        alias:
          description: Display name for the series
          type: string
          example: Total Count
        where:
          description: Filter query for the data (syntax depends on whereLanguage)
          type: string
          example: level:error
        whereLanguage:
          description: Query language for the where clause
          type: string
          enum:
            - sql
            - lucene
          example: lucene
        groupBy:
          type: array
          description: Fields to group results by (creates separate rows for each group)
          items:
            type: string
          example:
            - errorType
        sortOrder:
          description: Sort order for table rows
          type: string
          enum:
            - desc
            - asc
          example: desc
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
        metricDataType:
          description: Metric data type, only for metrics data sources.
          type: string
          enum:
            - sum
            - gauge
            - histogram
            - summary
            - exponential histogram
          example: sum
        metricName:
          description: Metric name for metrics data sources
          type: string
          example: http.server.duration
      required:
        - type
        - sourceId
        - aggFn
        - where
        - whereLanguage
        - groupBy
    ClickStackNumberChartSeries:
      properties:
        type:
          description: >-
            Series type discriminator. Must be "number" for single-value number
            charts.
          type: string
          enum:
            - number
          example: number
        sourceId:
          description: ID of the data source to query
          type: string
          example: 65f5e4a3b9e77c001a567890
        aggFn:
          description: Aggregation function to apply to the field or metric value
          type: string
          enum:
            - avg
            - count
            - count_distinct
            - last_value
            - max
            - min
            - quantile
            - sum
            - any
            - none
          example: count
        level:
          description: Percentile level for quantile aggregations (e.g., 0.95 for p95)
          type: number
          example: 0.95
        field:
          description: >-
            Column or expression to aggregate (required for most aggregation
            functions except count)
          type: string
          example: duration
        alias:
          description: Display name for the series in the chart
          type: string
          example: Total Requests
        where:
          description: Filter query for the data (syntax depends on whereLanguage)
          type: string
          example: service:api
        whereLanguage:
          description: Query language for the where clause
          type: string
          enum:
            - sql
            - lucene
          example: lucene
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
        metricDataType:
          description: Metric data type, only for metrics data sources.
          type: string
          enum:
            - sum
            - gauge
            - histogram
            - summary
            - exponential histogram
          example: sum
        metricName:
          description: Metric name for metrics data sources.
          type: string
          example: http.server.duration
      required:
        - type
        - sourceId
        - aggFn
        - where
        - whereLanguage
    ClickStackSearchChartSeries:
      properties:
        type:
          description: >-
            Series type discriminator. Must be "search" for search/log viewer
            charts.
          type: string
          enum:
            - search
          example: search
        sourceId:
          description: ID of the data source to query
          type: string
          example: 65f5e4a3b9e77c001a567890
        fields:
          type: array
          description: List of field names to display in the search results table
          items:
            type: string
          example:
            - timestamp
            - level
            - message
        where:
          description: Filter query for the data (syntax depends on whereLanguage)
          type: string
          example: level:error
        whereLanguage:
          description: Query language for the where clause
          type: string
          enum:
            - sql
            - lucene
          example: lucene
      required:
        - type
        - sourceId
        - fields
        - where
        - whereLanguage
    ClickStackMarkdownChartSeries:
      properties:
        type:
          description: >-
            Series type discriminator. Must be "markdown" for markdown text
            widgets.
          type: string
          enum:
            - markdown
          example: markdown
        content:
          description: Markdown content to render inside the widget.
          type: string
          example: |-
            # Dashboard Title

            This is a markdown widget.
      required:
        - type
        - content
    ClickStackLineBuilderChartConfig:
      properties:
        displayType:
          description: Display type discriminator. Must be "line" for line charts.
          type: string
          enum:
            - line
          example: line
        sourceId:
          description: ID of the data source to query.
          type: string
          example: 65f5e4a3b9e77c001a111111
        select:
          type: array
          description: >-
            One or more aggregated values to plot. When asRatio is true, exactly
            two select items are required.
          items:
            $ref: '#/components/schemas/ClickStackSelectItem'
        groupBy:
          description: >-
            Field expression to group results by (creates separate lines per
            group value).
          type: string
          example: host
        asRatio:
          description: >-
            Plot select[0] / select[1] as a ratio. Requires exactly two select
            items.
          type: boolean
        alignDateRangeToGranularity:
          description: Expand date range boundaries to the query granularity interval.
          type: boolean
        fillNulls:
          description: Fill missing time buckets with zero instead of leaving gaps.
          type: boolean
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
        compareToPreviousPeriod:
          description: Overlay the equivalent previous time period for comparison.
          type: boolean
      required:
        - displayType
        - sourceId
        - select
    ClickStackLineRawSqlChartConfig:
      properties:
        configType:
          description: Must be "sql" to use the Raw SQL chart config variant.
          type: string
          enum:
            - sql
          example: sql
        connectionId:
          description: ID of the ClickHouse connection to execute the query against.
          type: string
          example: 65f5e4a3b9e77c001a567890
        sqlTemplate:
          description: SQL query template to execute. Supports HyperDX template variables.
          type: string
          example: >-
            SELECT count() FROM otel_logs WHERE timestamp > now() - INTERVAL 1
            HOUR
        sourceId:
          description: >-
            Optional ID of the data source associated with this Raw SQL chart.
            Used for applying dashboard filters.
          type: string
          example: 65f5e4a3b9e77c001a567890
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
        displayType:
          description: Display as a line time-series chart.
          type: string
          enum:
            - line
          example: line
        compareToPreviousPeriod:
          description: Overlay the equivalent previous time period for comparison.
          type: boolean
        fillNulls:
          description: Fill missing time buckets with zero instead of leaving gaps.
          type: boolean
        alignDateRangeToGranularity:
          description: Expand date range boundaries to the query granularity interval.
          type: boolean
      required:
        - configType
        - connectionId
        - sqlTemplate
        - displayType
    ClickStackBarBuilderChartConfig:
      properties:
        displayType:
          description: >-
            Display type discriminator. Must be "stacked_bar" for stacked-bar
            charts.
          type: string
          enum:
            - stacked_bar
          example: stacked_bar
        sourceId:
          description: ID of the data source to query.
          type: string
          example: 65f5e4a3b9e77c001a111111
        select:
          type: array
          description: >-
            One or more aggregated values to plot. When asRatio is true, exactly
            two select items are required.
          items:
            $ref: '#/components/schemas/ClickStackSelectItem'
        groupBy:
          description: >-
            Field expression to group results by (creates separate bars segments
            per group value).
          type: string
          example: service
        asRatio:
          description: >-
            Plot select[0] / select[1] as a ratio. Requires exactly two select
            items.
          type: boolean
        alignDateRangeToGranularity:
          description: Align the date range boundaries to the query granularity interval.
          type: boolean
        fillNulls:
          description: Fill missing time buckets with zero instead of leaving gaps.
          type: boolean
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
      required:
        - displayType
        - sourceId
        - select
    ClickStackBarRawSqlChartConfig:
      properties:
        configType:
          description: Must be "sql" to use the Raw SQL chart config variant.
          type: string
          enum:
            - sql
          example: sql
        connectionId:
          description: ID of the ClickHouse connection to execute the query against.
          type: string
          example: 65f5e4a3b9e77c001a567890
        sqlTemplate:
          description: SQL query template to execute. Supports HyperDX template variables.
          type: string
          example: >-
            SELECT count() FROM otel_logs WHERE timestamp > now() - INTERVAL 1
            HOUR
        sourceId:
          description: >-
            Optional ID of the data source associated with this Raw SQL chart.
            Used for applying dashboard filters.
          type: string
          example: 65f5e4a3b9e77c001a567890
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
        displayType:
          description: Display as a stacked-bar time-series chart.
          type: string
          enum:
            - stacked_bar
          example: stacked_bar
        fillNulls:
          description: Fill missing time buckets with zero instead of leaving gaps.
          type: boolean
        alignDateRangeToGranularity:
          description: Expand date range boundaries to the query granularity interval.
          type: boolean
      required:
        - configType
        - connectionId
        - sqlTemplate
        - displayType
    ClickStackTableBuilderChartConfig:
      properties:
        displayType:
          description: Display type discriminator. Must be "table" for table charts.
          type: string
          enum:
            - table
          example: table
        sourceId:
          description: ID of the data source to query.
          type: string
          example: 65f5e4a3b9e77c001a111111
        select:
          type: array
          description: >-
            One or more aggregated values to display as table columns. When
            asRatio is true, exactly two select items are required.
          items:
            $ref: '#/components/schemas/ClickStackSelectItem'
        groupBy:
          description: Field expression to group results by (one row per group value).
          type: string
          example: service
        having:
          description: Post-aggregation SQL HAVING condition.
          type: string
          example: count > 100
        orderBy:
          description: SQL ORDER BY expression for sorting table rows.
          type: string
          example: count DESC
        asRatio:
          description: >-
            Display select[0] / select[1] as a ratio. Requires exactly two
            select items.
          type: boolean
          example: false
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
        groupByColumnsOnLeft:
          description: >-
            When true, render Group By columns to the left of series columns in
            the table. Defaults to false (Group By columns on the right).
          type: boolean
          example: false
        onClick:
          $ref: '#/components/schemas/ClickStackOnClick'
      required:
        - displayType
        - sourceId
        - select
    ClickStackTableRawSqlChartConfig:
      properties:
        configType:
          description: Must be "sql" to use the Raw SQL chart config variant.
          type: string
          enum:
            - sql
          example: sql
        connectionId:
          description: ID of the ClickHouse connection to execute the query against.
          type: string
          example: 65f5e4a3b9e77c001a567890
        sqlTemplate:
          description: SQL query template to execute. Supports HyperDX template variables.
          type: string
          example: >-
            SELECT count() FROM otel_logs WHERE timestamp > now() - INTERVAL 1
            HOUR
        sourceId:
          description: >-
            Optional ID of the data source associated with this Raw SQL chart.
            Used for applying dashboard filters.
          type: string
          example: 65f5e4a3b9e77c001a567890
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
        displayType:
          description: Display as a table chart.
          type: string
          enum:
            - table
          example: table
        onClick:
          $ref: '#/components/schemas/ClickStackOnClick'
      required:
        - configType
        - connectionId
        - sqlTemplate
        - displayType
    ClickStackNumberBuilderChartConfig:
      properties:
        displayType:
          description: >-
            Display type discriminator. Must be "number" for single big-number
            charts.
          type: string
          enum:
            - number
          example: number
        sourceId:
          description: ID of the data source to query.
          type: string
          example: 65f5e4a3b9e77c001a111111
        select:
          type: array
          description: Exactly one aggregated value to display as a single number.
          items:
            $ref: '#/components/schemas/ClickStackSelectItem'
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
      required:
        - displayType
        - sourceId
        - select
    ClickStackNumberRawSqlChartConfig:
      properties:
        configType:
          description: Must be "sql" to use the Raw SQL chart config variant.
          type: string
          enum:
            - sql
          example: sql
        connectionId:
          description: ID of the ClickHouse connection to execute the query against.
          type: string
          example: 65f5e4a3b9e77c001a567890
        sqlTemplate:
          description: SQL query template to execute. Supports HyperDX template variables.
          type: string
          example: >-
            SELECT count() FROM otel_logs WHERE timestamp > now() - INTERVAL 1
            HOUR
        sourceId:
          description: >-
            Optional ID of the data source associated with this Raw SQL chart.
            Used for applying dashboard filters.
          type: string
          example: 65f5e4a3b9e77c001a567890
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
        displayType:
          description: Display as a single big-number chart.
          type: string
          enum:
            - number
          example: number
      required:
        - configType
        - connectionId
        - sqlTemplate
        - displayType
    ClickStackPieBuilderChartConfig:
      properties:
        displayType:
          description: Display type discriminator. Must be "pie" for pie charts.
          type: string
          enum:
            - pie
          example: pie
        sourceId:
          description: ID of the data source to query.
          type: string
          example: 65f5e4a3b9e77c001a111111
        select:
          type: array
          description: Exactly one aggregated value used to size each pie slice.
          items:
            $ref: '#/components/schemas/ClickStackSelectItem'
        groupBy:
          description: Field expression to group results by (one slice per group value).
          type: string
          example: service
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
      required:
        - displayType
        - sourceId
        - select
    ClickStackPieRawSqlChartConfig:
      properties:
        configType:
          description: Must be "sql" to use the Raw SQL chart config variant.
          type: string
          enum:
            - sql
          example: sql
        connectionId:
          description: ID of the ClickHouse connection to execute the query against.
          type: string
          example: 65f5e4a3b9e77c001a567890
        sqlTemplate:
          description: SQL query template to execute. Supports HyperDX template variables.
          type: string
          example: >-
            SELECT count() FROM otel_logs WHERE timestamp > now() - INTERVAL 1
            HOUR
        sourceId:
          description: >-
            Optional ID of the data source associated with this Raw SQL chart.
            Used for applying dashboard filters.
          type: string
          example: 65f5e4a3b9e77c001a567890
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
        displayType:
          description: Display as a pie chart.
          type: string
          enum:
            - pie
          example: pie
      required:
        - configType
        - connectionId
        - sqlTemplate
        - displayType
    ClickStackHeatmapSelectItem:
      properties:
        valueExpression:
          description: >-
            SQL expression for the value being bucketed on the y-axis. Must be
            non-empty.
          type: string
          example: Duration
        countExpression:
          description: >-
            SQL expression for the count contributing to each bucket. Defaults
            to "count()" in the editor when omitted.
          type: string
          example: count()
        heatmapScaleType:
          description: Scale type used to bucket values on the y-axis.
          type: string
          enum:
            - log
            - linear
          example: log
      required:
        - valueExpression
    ClickStackNumberFormat:
      properties:
        output:
          description: Output format applied to the number.
          type: string
          enum:
            - currency
            - percent
            - byte
            - time
            - number
            - data_rate
            - throughput
            - duration
          example: number
        mantissa:
          description: Number of decimal places.
          type: integer
          example: 2
        thousandSeparated:
          description: Whether to use thousand separators.
          type: boolean
          example: true
        average:
          description: Whether to show as average.
          type: boolean
          example: false
        decimalBytes:
          description: Use decimal bytes (1000) vs binary bytes (1024).
          type: boolean
          example: false
        factor:
          description: Multiplication factor.
          type: number
          example: 1
        currencySymbol:
          description: Currency symbol for currency format.
          type: string
          example: $
        numericUnit:
          description: Numeric unit for data, data rate, or throughput formats.
          type: string
          enum:
            - bytes_iec
            - bytes_si
            - bits_iec
            - bits_si
            - kibibytes
            - kilobytes
            - mebibytes
            - megabytes
            - gibibytes
            - gigabytes
            - tebibytes
            - terabytes
            - pebibytes
            - petabytes
            - packets_sec
            - bytes_sec_iec
            - bytes_sec_si
            - bits_sec_iec
            - bits_sec_si
            - kibibytes_sec
            - kibibits_sec
            - kilobytes_sec
            - kilobits_sec
            - mebibytes_sec
            - mebibits_sec
            - megabytes_sec
            - megabits_sec
            - gibibytes_sec
            - gibibits_sec
            - gigabytes_sec
            - gigabits_sec
            - tebibytes_sec
            - tebibits_sec
            - terabytes_sec
            - terabits_sec
            - pebibytes_sec
            - pebibits_sec
            - petabytes_sec
            - petabits_sec
            - cps
            - ops
            - rps
            - reads_sec
            - wps
            - iops
            - cpm
            - opm
            - rpm_reads
            - wpm
          example: bytes_iec
        unit:
          description: Custom unit label.
          type: string
          example: ms
    ClickStackSelectItem:
      properties:
        aggFn:
          description: >-
            Aggregation function to apply. "count" does not require a
            valueExpression; "quantile" requires a level field indicating the
            desired percentile (e.g., 0.95).
          type: string
          enum:
            - avg
            - count
            - count_distinct
            - last_value
            - max
            - min
            - quantile
            - sum
            - any
            - none
          example: count
        valueExpression:
          description: >-
            Expression for the column or value to aggregate. Must be omitted
            when aggFn is "count"; required for all other aggFn values.
          type: string
          example: Duration
        alias:
          description: Display alias for this select item in chart legends.
          type: string
          example: Request Duration
        level:
          description: Percentile level; only valid when aggFn is "quantile".
          type: number
          enum:
            - '0.5'
            - '0.9'
            - '0.95'
            - '0.99'
        where:
          description: SQL or Lucene filter condition applied before aggregation.
          type: string
          example: service:api
        whereLanguage:
          description: Query language for the where clause.
          type: string
          enum:
            - sql
            - lucene
        metricName:
          description: >-
            Name of the metric to aggregate; only applicable when the source is
            a metrics source.
          type: string
          example: http.server.duration
        metricType:
          description: Metric type; only applicable when the source is a metrics source.
          type: string
          enum:
            - sum
            - gauge
            - histogram
            - summary
            - exponential histogram
        periodAggFn:
          description: >-
            Optional period aggregation function for Gauge metrics (e.g.,
            compute the delta over the period).
          type: string
          enum:
            - delta
          example: delta
        numberFormat:
          $ref: '#/components/schemas/ClickStackNumberFormat'
      required:
        - aggFn
    ClickStackOnClick:
      oneOf:
        - $ref: '#/components/schemas/ClickStackOnClickSearch'
        - $ref: '#/components/schemas/ClickStackOnClickDashboard'
    ClickStackOnClickSearch:
      properties:
        type:
          description: >-
            OnClick variant discriminator. Must be "search" for search
            link-outs.
          type: string
          enum:
            - search
          example: search
        target:
          $ref: '#/components/schemas/ClickStackOnClickTarget'
        whereTemplate:
          description: Optional WHERE clause template applied to the destination search.
          type: string
          example: ServiceName = '{{ServiceName}}'
        whereLanguage:
          description: Language of the rendered whereTemplate.
          type: string
          enum:
            - sql
            - lucene
        filters:
          type: array
          description: >-
            Optional dashboard filter templates rendered against the clicked
            row.
          items:
            $ref: '#/components/schemas/ClickStackOnClickFilterTemplate'
      required:
        - type
        - target
    ClickStackOnClickDashboard:
      properties:
        type:
          description: >-
            OnClick variant discriminator. Must be "dashboard" for dashboard
            link-outs.
          type: string
          enum:
            - dashboard
          example: dashboard
        target:
          $ref: '#/components/schemas/ClickStackOnClickTarget'
        whereTemplate:
          description: Optional WHERE clause template applied to the destination dashboard.
          type: string
          example: ServiceName = '{{ServiceName}}'
        whereLanguage:
          description: Language of the rendered whereTemplate.
          type: string
          enum:
            - sql
            - lucene
        filters:
          type: array
          description: >-
            Optional dashboard filter templates rendered against the clicked
            row.
          items:
            $ref: '#/components/schemas/ClickStackOnClickFilterTemplate'
      required:
        - type
        - target
    ClickStackOnClickTarget:
      oneOf:
        - $ref: '#/components/schemas/ClickStackOnClickTargetIdVariant'
        - $ref: '#/components/schemas/ClickStackOnClickTargetTemplateVariant'
    ClickStackOnClickFilterTemplate:
      properties:
        kind:
          description: >-
            Filter template kind. Currently only "expressionTemplate" is
            supported.
          type: string
          enum:
            - expressionTemplate
          example: expressionTemplate
        expression:
          description: >-
            The column/expression to filter the destination by (e.g.
            "ServiceName").
          type: string
          example: ServiceName
        template:
          description: >-
            Value template rendered against the clicked row; supports row column
            variables in `{{column}}` form (e.g. `{{ServiceName}}`).
          type: string
          example: '{{ServiceName}}'
      required:
        - kind
        - expression
        - template
    ClickStackOnClickTargetIdVariant:
      properties:
        mode:
          description: Target is a single dashboard or log/trace source
          type: string
          enum:
            - id
          example: id
        id:
          description: ID of the target source (for search) or dashboard (for dashboard).
          type: string
          example: 65f5e4a3b9e77c001a567890
      required:
        - mode
        - id
    ClickStackOnClickTargetTemplateVariant:
      properties:
        mode:
          description: Target is matched by name against the template.
          type: string
          enum:
            - template
          example: template
        template:
          description: >-
            Name template rendered against the clicked row; supports
            `{{column}}` variables.
          type: string
          example: '{{ServiceName}}'
      required:
        - mode
        - template
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Use key ID and key secret obtained in ClickHouse Cloud console:
        https://clickhouse.com/docs/cloud/manage/openapi

````