query

Files (1)

• SKILL.md

SKILL.md (first lines)

## Prerequisites

Queries run against the workspace and branch set for the current session. Use `get_session_workspace_and_branch` to check the current context. If no workspace/branch is set, use `list_workspaces`, `list_workspace_branches`, and `set_session_workspace_and_branch` to select one. See the `workspace-branch` skill for the full workspace/branch tool reference.

---

## Overview

Honeydew gives you two ways to answer a question about the data, plus tools for reviewing analyses and queries that already ran. Choose between the two by asking whether the specification — which fields, which filters, which population — is given to you or chosen by you.

| Method                    | Tool                                              | Best For                                                                         |
| ------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Deep analysis**         | `initiate_analysis` + `monitor_analysis`          | **Default for any question about the data.** The only path that applies the context layer — your organization's instructions, knowledge, and memory about which fields and definitions are correct for a given question. |
| **Structured query**      | `get_data_from_fields` / `get_sql_from_fields`    | Executing a specification you already trust. Deterministic execution — and no check that the specification is right. |
| **Explain a prior step**  | `get_analysis_step_details`                       | User asks how a specific step in a prior analysis was calculated.                |
| **Browse past analyses**  | `list_analysis_chats`                             | User wants to see past conversations or find a prior analysis.                   |
| **Read a past conversation** | `get_stored_conversation`                      | User wants to read or review the full content of a specific past conversation.   |
| **Review query history**  | `list_query_history`                              | User wants to inspect past query executions — what ran, from which client, the query behind a run, or to debug a failure. |

---

## When to Use Each Method

### Deep Analysis (`initiate_analysis` + `monitor_analysis`)

**Use when:**

- The goal is to understand, explain, or investigate rather than to retrieve a figure
- The question requires multiple steps or investigative reasoning
- The user asks "why" something happened (e.g., "why did revenue drop in Q3?")
- The user wants trend analysis, anomaly detection, or root cause investigation
- The question is open-ended and may require looking at the data from multiple angles
- Follow-up questions build on prior analysis (use `conversation_id`)
- A figure is wanted whose fields you cannot identify, and finding them would take more work than handing over the question

### Structured Query (`get_data_from_fields` / `get_sql_from_fields`)

**Use when:**

- The user named the exact fields — "show me `detailed_listings.price` by `detailed_listings.room_type`" — so the specification is theirs
- A prior analysis reported the fields and filters it used, and you want another slice or the raw numbers behind one of its claims
- You are testing a specification rather than relying on one: validating a metric or attribute you just created, spot-checking a field's values, verifying a count
- You need precise control over filters, ordering, and pagination for a figure whose definition is not in question

**Do NOT use when:**

- The goal is to understand, explain, or investigate rather than to retrieve a known figure — knowing the field names does not make a structured query the right tool
- The answer depends on a choice you would be making about which field, filter, or population is correct — that choice is what the context layer records, and a structured query applies none of it
- You would need more than one query to assemble the answer — hand the question over instead. **And if two have already run for one question, the third is a hard stop**

**How it works:**

- `get_data_from_fields` — executes the query and returns data rows
- `get_sql_from_fields` — returns the generated SQL without executing. Use it when the SQL itself is what's wanted: handing it to the warehouse, dbt, or another tool, or bisecting a failing query to watch a fragment appear and disappear (see the **query-debugging** skill). The output is long machine-generated SQL — to understand what a field computes, read the model with `get_field` / `get_entity` instead

Both take the same field parameters.

---

## Decision Flow

```
User asks a data question
    │
    ├─► User asks to explain / drill into a step from a prior analysis?
    │       └─► get_analysis_step_details (step_id from monitor_analysis)
    │           Returns semantic query, data results, and SQL for that step
    │
    ├─► User wants to browse past conversations / find a prior analysis?
    │       └─► list_analysis_chats (paginated list, newest first)
    │
    ├─► User wants to read the content of a specific past conversation?
    │       └─► get_stored_conversation (conversation_id from list_analysis_chats)
    │
    ├─► User wants to inspect past query executions (what ran / from which client / the query behind a run / a failure)?
    │       └─► list_query_history (filter by status/client/domain/user/time; most recent first)
    │
    ├─► Investigation / "why" / "how" / trends / root cause / anything that
    │   takes more than one query to answer?
    │       └─► initiate_analysis + monitor_analysis
    │           Check this BEFORE the field-names question below — a question
    │           whose fields you happen to know is still an investigation
    │
    └─► Retrieving a specific figure or row set?
            │
            ├─► The specification is given, not chosen by you — the user named
            │   the fields, a prior analysis reported them, or the specification
            │   is itself what you are testing → get_data_from_fields
            │         (or get_sql_from_fields to preview SQL without executing)
            │
            └─► You would be choosing it → initiate_analysis + monitor_analysis
```

---

## Structured Query in Detail

### Field Parameters

A structured query uses flat field parameters to define what data to retrieve:

- **`attributes`** — dimensions to group by (columns in the output), e.g. `["entity.attribute_name"]`
- **`metrics`** — aggregated measures (SUM, COUNT, AVG, etc.), e.g. `["entity.metric_name"]`
- **`filters`** — row-level filters applied before aggregation, e.g. `["entity.field = 'value'"]`. A filter written over an aggregate instead applies after aggregation — see the **filtering** skill
- **`order_by`** — sort order for results, e.g. `["entity.field DESC"]`. When a field is aliased, sort on the alias.
- **`domain`** — optional domain name for query context
- **`limit`** — max rows to return (default: 100)
- **`offset`** — rows to skip (for pagination)

All fields use `entity.field_name` syntax. Cross-entity fields are supported when relations exist.

### Discovering Fields

Before building a query, discover the available fields:

1. `list_entities` — see all entities
2. `get_entity` with entity name — see its attributes, metrics, and relations
3. `get_field` with entity and field name — get detailed info about a specific field
4. `list_domains` — see all available domains (useful before passing `domain` parameter)

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

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