metric-creation

Files (3)

• SKILL.md
• examples.md
• reference.md

SKILL.md (first lines)

## Prerequisites

Before creating metrics, ensure you are on the correct workspace and branch. Use `get_session_workspace_and_branch` to check the current session context. For development work, create a branch with `create_workspace_branch` (the session switches automatically). See the `workspace-branch` skill for the full workspace/branch tool reference.

---

## Overview

A Honeydew **metric** is a named, reusable aggregation anchored to an entity.
Unlike a calculated attribute (which is per-row), a metric collapses multiple rows into a
single value.
Metrics are **context-sensitive**: they automatically respond to whatever filters and
groupings the consuming BI tool or analyst applies.

**Your job is to build an aggregation function that users can later group by.**

If a user asks for a group by ("sum sales by category"), ignore the group. You're building the aggregation to sum sales by ANYTHING. The user will later use it in a query with their chosen dimensions.

Use a metric when:

- The same aggregation logic is reused across dashboards, teams, or tools
- You need a governed, single source of truth for a KPI (e.g. "revenue", "active users")
- The calculation involves combining other metrics (ratios, deltas)

**Do not** use a metric when the value is per-row (use a calculated attribute instead).

---

## Building the SQL Expression

### Core Rules

- **MUST use an aggregation function** — metrics collapse rows
- **DO NOT use window functions** — only aggregations allowed
- **DO NOT use joins or subqueries** — simple expressions only
- **NEVER use COUNT(\*)** — use the entity's built-in count metric (e.g., `entity.count`) if available,
  or `COUNT(entity.key_field)` on the primary key. No `DISTINCT` needed — primary keys are
  unique by definition.
- **Compose from existing metrics whenever possible.** Honeydew accepts named metric references
  (`entity.metric_name`) anywhere you'd write a raw aggregation — inside `FILTER (WHERE ...)`, inside
  `GROUP BY (...)` (both fixed `GROUP BY (dim)` and nested `GROUP BY (*, dim)`), and as operands
  in derived arithmetic. Always check whether an existing metric can be the building block before
  reaching for `SUM(...)`, `COUNT(...)`, etc. The named-metric form expresses business intent,
  inherits future changes to the base metric, and keeps the model DRY.
- **For cross-entity counts, clarify intent first** — filtered count or simple count. Use
  `related_entity.count FILTER (WHERE source_entity.key IS NOT NULL)` for a filtered count.
  See reference.md "Cross-entity counts" for mechanics.
- **Reuse existing attributes** — if a calculated attribute already exists (or you just created
  one), reference it by name (e.g., `entity.attribute_name`) rather than repeating its SQL logic.
- **Use fully qualified column names** — `entity.attribute`, not just `attribute`

See [reference.md](reference.md) — particularly the "Composing from Existing Metrics" section — for the canonical patterns: filtered, fixed grouping, nested grouping, cross-entity counts, and derived metrics, each with named-metric and raw-fallback forms shown side by side.

---

## Creation Methods

### create_object (Required)

Always use `create_object` with full YAML to ensure proper datatype and all properties are set.

Call `create_object` with `yaml_text`:

```yaml
type: metric
entity: <entity_name>
name: <snake_case_name>
display_name: <Human Readable Name>
description: |-
  <business description>
owner: <owner_email_or_team>
datatype: float|number|string|date|timestamp
sql: |-
  <aggregation SQL expression>
```

**Required fields:**

- `type: metric`
- `entity` — the entity this metric belongs to
- `name` — snake_case identifier
- `owner` — **CRITICAL: always set to current username** (from workspace context)
- `datatype` — **CRITICAL: always set explicitly** (default to `float` for most metrics, `number` for counts)
- `sql` — the aggregation expression

**Optional fields:**

- `display_name` — human readable name
- `description` — business context **for a non-technical user**: WHY this metric matters, which business team owns the definition, known caveats, or governance notes. **Do NOT** describe the SQL or how it's calculated — that's visible in the `sql` field. **Do NOT** restate the metric name or display name. If there's nothing meaningful to add beyond the name, omit it entirely.
- `format_string` — display format (e.g., `$#,##0.00`)
- `labels` — categorization tags
- `folder` — organizational path

### update_object (for updates)

To modify an existing metric:

1. Use `get_entity` with the entity name to find the metric and its details.
2. Use `search_model` (with `search_mode: EXACT`) to find the metric's `object_key`.
3. Call `update_object` with the full updated YAML (`yaml_text`) and the `object_key`.

> **Minimal diff rule:** When updating, preserve the existing field order and formatting from the current YAML. Only change the fields you need to modify. Objects are versioned in git, so unnecessary reordering or reformatting creates noisy diffs.

### After Creation/Update: Display the UI Link

After a successful `create_object` or `update_object` call, the response includes a `ui_url` field. **Always display this URL to the user** so they can quickly open the object in the Honeydew application.

### delete_object (for deletion)

1. Use `search_model` (with `search_mode: EXACT`) to find the metric's `object_key`.
2. Call `delete_object` with that `object_key`.

---

## Examples

See [examples.md](examples.md) for full worked examples covering: basic, derived, filtered, ratio, count, distinct count, fixed grouping, nested aggregation, text summary, update, and delete.

---

From honeydew-ai/honeydew-ai-coding-agents-plugins, Apache-2.0.

More from honeydew-ai/honeydew-ai-coding-agents-plugins