Dashboards

Dashboards render dbt results as charts, leaderboards, and KPIs. Store configuration files under dashboards/*.yaml inside your configuration roots (e.g. .kiket/analytics/dashboards, with legacy support for .kiket/dashboards).

Schema overview

Dashboard files use the following structure:

model_version: "1.0"
dashboard:
  id: delivery-health
  name: Delivery Health
  description: Cycle time and throughput metrics.
  widgets:
    - id: cycle-time-trend
      type: timeseries
      title: Cycle Time (Days)
      query: fct_cycle_time
      query_config:
        model: fct_cycle_time
        filters:
          project_id: ":project_id"
        parameters:
          - name: project_id
            type: integer
            required: true
        order_by:
          - completed_on
      visualization:
        x: completed_on
        y: avg_cycle_days
    - id: throughput-kpi
      type: kpi
      title: Issues Completed (Last 7 Days)
      query: fct_throughput
      query_config:
        model: fct_throughput
        filters:
          project_id: ":project_id"
        parameters:
          - name: project_id
            type: integer
            required: true
      options:
        window: 7d
  alerts:
    - query: fct_cycle_time
      condition: avg_cycle_days > 5
      notify_roles:
        - manager
      query_config:
        model: fct_cycle_time
        filters:
          project_id: ":project_id"
        parameters:
          - name: project_id
            type: integer
            required: true

Required keys

Key	Description
model_version	Schema version (currently 1.0).
dashboard.id	Stable identifier used in URLs and APIs.
dashboard.name	Display name.
dashboard.widgets	Array of widget definitions.

Widgets

Each widget definition supports the following properties:

Key	Required	Notes
id	➖	Helpful for testing and telemetry.
type	✅	e.g. timeseries, kpi, leaderboard, table.
title	✅	Widget heading.
query	✅	Friendly identifier for the dbt model (shown in UI).
query_config	➖	Execution details (model name, filters, parameters, order).
visualization	➖	Options for x/y axes, grouping, formatting.
options	➖	Miscellaneous settings (rolling windows, limits, etc.).

query_config defaults to selecting all columns from the model and filtering by project_id. Override it when you need custom filters, ordering, or column lists.

Alerts

Alerts provide lightweight monitoring. Each alert can define:

Key	Required	Notes
query	✅	dbt model to evaluate.
condition	✅	Expression evaluated against the aggregated result (e.g. avg_cycle_days > 5).
notify_roles	➖	Roles to notify via the built-in notification system (manager, executive, etc.).
query_config	➖	Overrides for model/filters (same schema as widget query_config).

Publishing workflow

1. Commit the dashboard YAML to your definition repository.
2. After the next configuration sync, the dashboard appears in Analytics → Dashboards.
3. Update or remove dashboards by editing the YAML file and syncing again.

Viewing dashboards in Kiket

• Project dashboards are available at /projects/:project_id/dashboards.
• Use the sidebar to switch between dashboards; widgets refresh with the latest dbt data after every analytics run.
• The command palette (Cmd/Ctrl + K) now lists analytics shortcuts so you can jump to dashboards or queue a manual refresh without leaving the current view.
• Alerts defined in the YAML file display beneath the widget grid to highlight conditions that require attention.

Best practices

• Keep widget IDs unique per dashboard for reliable telemetry.
• Pair dashboards with dbt tests to catch breaking changes in upstream models.
• Use descriptive titles and meaningful descriptions so teams understand intent.
• Prefer query_config filters over ad-hoc SQL to maintain tenancy guarantees.
• For shared dashboards, place them in template repositories so new projects inherit them automatically.

Extension dashboards

When a dashboard ships inside an extension bundle (extensions/<name>/.kiket/analytics/dashboards), Kiket automatically:

• Binds every widget/alert to the extension’s managed schema (analytics_ext_<org>_<extension>_<installation_id>), so queries cannot read from shared marts.
• Rejects schema-qualified models (e.g., public.fct_usage) to prevent cross-tenant access.
• Stores the extension installation metadata alongside each widget, enabling auditing and CLI diagnostics.

Extension authors simply reference their dbt models by name (e.g., query: completed_requests); the runtime injects the correct schema at execution time.

Dashboards provide a consistent, configuration-driven way to surface the dbt analytics fabric across your organisation.