@axiom-lattice/examples-deep_research 1.0.26 → 1.0.28

package/src/agents/data_agent/skills/metrics-query/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: metrics-query
+description: Query business metrics using the three-step workflow. Discover available metrics, understand metric definitions, and execute queries with proper filters and groupings.
+metadata:
+  category: data_analysis
+  tools:
+    - query_metrics_list
+    - query_metric_definition
+    - query_semantic_metric_data
+---
+
+## Overview: The Three-Step Loop
+
+1. **query_metrics_list** → Discover what metrics exist
+2. **query_metric_definition** → Understand one metric before querying it
+3. **query_semantic_metric_data** → Execute the query with the right parameters
+
+Repeat steps 2-3 for each metric the user asks about. Drill-down means running step 3 multiple times with progressively narrower filters.
+
+## Step 1 — Discover Available Metrics
+
+**Tool**: `query_metrics_list`
+
+**Parameters**:
+- `serverKey` (required): Target semantic metrics server
+- `datasourceIds` (optional): Array of datasource IDs to query. If not provided, uses all selected datasources.
+
+**Response Fields**:
+| Field | Description | Usage |
+|-------|-------------|-------|
+| metricName | Metric identifier | Pass to query_metric_definition and query_semantic_metric_data |
+| domain | Metric category | Groups related metrics (e.g., sales_performance, pricing_and_margin) |
+| shortDesc | One-line description | Present to user |
+| displayName | Human-readable name | Display in results |
+
+**When to Use**:
+- User asks about metrics without specifying exact names
+- Starting any metrics-related conversation
+- Finding metrics by domain or keywords
+
+**Next Step**: After finding relevant metrics, call `query_metric_definition` with the `metricName`.
+
+## Step 2 — Read the Metric Definition
+
+**Tool**: `query_metric_definition`
+
+**Parameters**:
+- `serverKey` (required): Target semantic metrics server
+- `metricName` (required): The name of the metric to get definition for
+- `datasourceId` (optional): Specific datasource ID to search in. If not provided, searches all selected datasources.
+
+This response is self-contained. Everything you need to write a correct query is here.
+
+### 2.1 Identify the Time Axis (defaultTimeContext)
+
+The `defaultTimeContext` tells you the primary date field and exactly how to use it:
+
+```json
+{
+  "timeDimension": "DocDate",
+  "label": "单据日期",
+  "granularity": "month",
+  "window": "current_month",
+  "supportedGrains": ["day", "week", "month", "year"]
+}
+```
+
+**Rules**:
+- To filter by date: Copy the pattern and replace values
+  ```json
+  {"dimension": "DocDate", "operator": "BETWEEN", "values": ["2025-01-01", "2025-12-31"]}
+  ```
+- To group by time: Use `"{timeDimension}__{grain}"` format (e.g., `"DocDate__month"`)
+
+### 2.2 Identify Available Dimensions (supportedDimensions)
+
+`supportedDimensions` lists every axis available for GROUP BY and filtering. Each entry has:
+- `dim_id`: Use this (NOT `field_name`) in filters and groupBy
+- `field_name`: Human-readable field name
+- `type`: `"categorical"` (strings) or `"datetime"` (dates)
+
+**Categorical Dimensions**:
+- Values are strings
+- Use `IN` for multiple values, `EQ` / `NEQ` for single
+- Example: `{"dimension": "org_region", "operator": "IN", "values": ["华东", "华南"]}`
+
+**Datetime Dimensions**:
+- Values are YYYY-MM-DD format
+- Use `BETWEEN` for ranges, `GT` / `LT` for open-ended
+- Group format: `"{dim_id}__{grain}"` where grain is lowercase: `day`, `week`, `month`, `year`
+- Example groupBy: `["DocDate__month"]`
+
+### 2.3 Understand Result Polarity (aiAgentContext.polarity)
+
+- `"positive"` — Higher value is better (e.g., order amount, delivery qty)
+- `"negative"` — Lower value is better (e.g., discount rate, return amount)
+
+Use this when summarizing results to the user (e.g., "the discount rate increased, which is a negative sign").
+
+**Next Step**: Call `query_semantic_metric_data` with parameters derived from this definition.
+
+## Step 3 — Execute a Query
+
+**Tool**: `query_semantic_metric_data`
+
+**Parameters**:
+- `serverKey` (required): Target semantic metrics server
+- `datasourceId` (required): The data source ID to query metrics from
+- `metrics` (required): Array of metric names to query (e.g., `["net_sales_amt", "gross_profit"]`)
+- `groupBy` (optional): Array of dimensions to group by (e.g., `["DocDate__month", "org_region"]`)
+- `filters` (optional): Array of filters to apply
+- `orderBy` (optional): Array of sort specifications
+- `limit` (optional): Maximum number of results (default: 1000)
+- `debug` (optional): Set to `true` to receive executed SQL for verification
+
+**Full Request Schema**:
+```json
+{
+  "serverKey": "your_server",
+  "datasourceId": "1",
+  "metrics": ["metric_name"],
+  "groupBy": ["dim_id or DocDate__grain"],
+  "filters": [{"dimension": "dim_id", "operator": "OP", "values": ["..."]}],
+  "orderBy": [{"field": "field_name", "direction": "ASC|DESC"}],
+  "limit": 100,
+  "debug": false
+}
+```
+
+### Filter Operator Reference
+
+| Operator | Applies To | Values Array |
+|----------|------------|--------------|
+| BETWEEN | datetime, number | [min, max] (inclusive) |
+| IN | categorical | ["v1", "v2", ...] |
+| EQ | any | ["v"] |
+| NEQ | any | ["v"] |
+| GT / GTE | datetime, number | ["v"] |
+| LT / LTE | datetime, number | ["v"] |
+| LIKE | string | ["%pattern%"] |
+| NOT_NULL | any | [] |
+
+## Workflow Patterns
+
+### Pattern A — Time Trend (most common first query)
+
+**Goal**: Show how a metric changes over time within a period.
+
+```json
+{
+  "serverKey": "your_server",
+  "datasourceId": "1",
+  "metrics": ["order_amt_tax_inc"],
+  "groupBy": ["DocDate__month"],
+  "filters": [{"dimension": "DocDate", "operator": "BETWEEN", "values": ["2025-01-01", "2025-12-31"]}],
+  "orderBy": [{"field": "DocDate__month", "direction": "ASC"}]
+}
+```
+
+Use `DocDate__week` or `DocDate__day` for shorter time windows.
+
+### Pattern B — Dimension Breakdown (who/what is top or bottom)
+
+**Goal**: Rank performance across a categorical dimension in a fixed period.
+
+```json
+{
+  "serverKey": "your_server",
+  "datasourceId": "1",
+  "metrics": ["order_amt_tax_inc"],
+  "groupBy": ["org_region"],
+  "filters": [{"dimension": "DocDate", "operator": "BETWEEN", "values": ["2025-01-01", "2025-03-31"]}],
+  "orderBy": [{"field": "value", "direction": "DESC"}],
+  "limit": 10
+}
+```
+
+Pick `dim_id` values from `supportedDimensions` in the detail response.
+
+### Pattern C — Drill Down (zoom into an anomaly)
+
+**Goal**: After Pattern A reveals a bad month, find which segment caused it.
+
+**Step 1**: Find the anomaly month using Pattern A
+
+**Step 2**: Drill into that month by adding a categorical dimension:
+
+```json
+{
+  "serverKey": "your_server",
+  "datasourceId": "1",
+  "metrics": ["order_amt_tax_inc"],
+  "groupBy": ["sales_person"],
+  "filters": [
+    {"dimension": "DocDate", "operator": "BETWEEN", "values": ["2025-06-01", "2025-06-30"]},
+    {"dimension": "org_region", "operator": "EQ", "values": ["华东"]}
+  ],
+  "orderBy": [{"field": "value", "direction": "ASC"}]
+}
+```
+
+**Step 3** (optional): Add a second groupBy dimension to cross-analyze:
+```json
+{
+  "groupBy": ["sales_person", "product_category"],
+  ...
+}
+```
+
+### Pattern D — Multi-Metric Comparison
+
+**Goal**: Query two or more metrics in one call to compare them side-by-side.
+
+```json
+{
+  "serverKey": "your_server",
+  "datasourceId": "1",
+  "metrics": ["order_amt_tax_inc", "net_sales_amt"],
+  "groupBy": ["DocDate__month"],
+  "filters": [{"dimension": "DocDate", "operator": "BETWEEN", "values": ["2025-01-01", "2025-12-31"]}],
+  "orderBy": [{"field": "DocDate__month", "direction": "ASC"}]
+}
+```
+
+The response contains one `results[]` entry per metric. Each entry has its own `rows[]` and `metricName` label.
+
+### Pattern E — Time × Dimension Cross-Analysis
+
+**Goal**: See how a dimension behaves across time (e.g., monthly sales by region).
+
+```json
+{
+  "serverKey": "your_server",
+  "datasourceId": "1",
+  "metrics": ["order_amt_tax_inc"],
+  "groupBy": ["DocDate__month", "org_region"],
+  "filters": [{"dimension": "DocDate", "operator": "BETWEEN", "values": ["2025-01-01", "2025-06-30"]}],
+  "orderBy": [
+    {"field": "DocDate__month", "direction": "ASC"},
+    {"field": "org_region", "direction": "ASC"}
+  ]
+}
+```
+
+## Recommended Analysis Flow
+
+```
+User question
+      │
+      ▼
+Step 1: query_metrics_list — find matching metric(s)
+      │
+      ▼
+Step 2: query_metric_definition — read defaultTimeContext + supportedDimensions
+      │
+      ▼
+Step 3a: Pattern A (time trend) — get the big picture
+      │
+      ├─ anomaly found? ──► Step 3c: Pattern C (drill down)
+      │
+      ├─ user asks "who"? ──► Step 3b: Pattern B (dimension breakdown)
+      │
+      └─ user asks "compare X and Y"? ──► Step 3d: Pattern D (multi-metric)
+```
+
+Always start broad (monthly trend over a year), then narrow (weekly in the problem month), then pinpoint (drill by dimension in the problem week).
+
+## Debug Mode
+
+Set `"debug": true` to receive `executedSqls` in the response. Use this to verify that the generated SQL matches your intent before presenting results to the user.
+
+```json
+{
+  ...,
+  "debug": true
+}
+```
+
+**Response**:
+```json
+{
+  "results": [...],
+  "executedSqls": ["SELECT TO_NVARCHAR(\"DocDate\", 'YYYY-MM') AS \"DocDate__month\", SUM(\"GTotal\") AS \"value\" FROM MTC_VW_AI_ORDR WHERE ..."]
+}
+```
+
+## Common Mistakes to Avoid
+
+| Mistake | Correct Approach |
+|---------|------------------|
+| Using `field_name` (e.g., `"SlpName"`) in groupBy | Use `dim_id` (e.g., `"sales_person"`) |
+| Writing `"DocDate__Month"` (capital M) | Always lowercase grain: `"DocDate__month"` |
+| Omitting a date filter entirely | ALWAYS include at least one DocDate filter to avoid full-table scans |
+| Querying a metric by an unsupported dimension | Only use `dim_id` values listed in the detail response |
+| Putting a groupBy field in orderBy using its display name | `orderBy.field` must match exactly what's in `groupBy` |
+| Using wrong operator for dimension type | categorical → IN/EQ, datetime → BETWEEN/GT/LT |