Skip to content
Skills Library
Data & analytics · Analysis

write-hql

/write-hql

Write, validate, and run HQL (Harness Query Language) queries against Harness data, and analyze pipeline, deployment, CI and security data with them. Use when asked to write, fix, explain, or validate an HQL query, find which types and fields can be queried, or answer "how many", "top N", trend or failure-rate questions over a time window or many runs. Do NOT use for the current state of one named pipeline run (use debug-pipeline) or for cloud cost totals (use analyze-costs). Trigger phrases: HQL, Harness Query Language, write a query, validate query, queryable types.

Licence
Apache-2.0
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
12
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Write, validate, and run HQL (Harness Query Language) queries against Harness data, and analyze pipeline, deployment, CI and security data with them. Use when asked to write, fix, explain, or validate an HQL query, find which types and fields can be queried, or answer "how many", "top N", trend or failure-rate questions over a time window or many runs. Do NOT use for the current state of one named pipeline run (use debug-pipeline) or for cloud cost totals (use analyze-costs). Trigger phrases: HQL, Harness Query Language, write a query, validate query, queryable types.

Triggers from the description

how manytop N
Original author description

Write, validate, and run HQL (Harness Query Language) queries against Harness data, and analyze pipeline, deployment, CI and security data with them. Use when asked to write, fix, explain, or validate an HQL query, find which types and fields can be queried, or answer "how many", "top N", trend or failure-rate questions over a time window or many runs. Do NOT use for the current state of one named pipeline run (use debug-pipeline) or for cloud cost totals (use analyze-costs). Trigger phrases: HQL, Harness Query Language, write a query, validate query, queryable types.

How it works

  1. Instructions
  2. Examples
  3. Performance Notes
  4. Troubleshooting
Original SKILL.md headings · 183 lines, 1,505 words
SKILL.md preview
---
name: write-hql
description: >-
  Write, validate, and run HQL (Harness Query Language) queries against Harness data, and
  analyze pipeline, deployment, CI and security data with them. Use when asked to
  write, fix, explain, or validate an HQL query, find which types and fields can
  be queried, or answer "how many", "top N", trend or failure-rate questions over a time window
  or many runs. Do NOT use for the current state of one named pipeline run (use debug-pipeline)
  or for cloud cost totals (use analyze-costs). Trigger phrases: HQL, Harness Query Language,
  write a query, validate query, queryable types.
metadata:
  author: Harness
  version: 1.0.0
  mcp-server: harness-mcp-v2
  summary: Discover queryable types and fields, then write, validate, and run HQL queries
license: Apache-2.0
compatibility: Requires Harness MCP v2 server (harness-mcp-v2) with the knowledge-graph and semantic-layer toolsets enabled
---

# Write HQL

Write, validate, and run HQL queries against Harness data. This skill teaches the query language, the type discovery workflow, and the validation loop. For multi-query analysis (overview, drill-down, synthesis), also follow [analysis-workflow.md](references/analysis-workflow.md).

## Instructions

### Step 0: Learn HQL syntax

Read the companion files in this skill directory before writing any queries:
- **`reference.md`** — practical examples, type casting rules, JOIN syntax, anti-patterns.
- **`references/patterns/*.md`** — worked query patterns per question shape (failure-diagnosis, build-time-analysis, bottleneck-analysis, flakiness, retry-signals, intermittent-vs-consistent, lint-first, batch).
- **`references/entity-reference/ci.md`** — CI-native field discipline (`stage_build_time` vs `duration`, `start_timestamp` vs `start_ts`).

Fetch the live grammar via `harness_get(resource_type='kg_grammar')` only when the reference files do not cover the syntax you need.

### Step 1: Discover queryable types (summaries only)

```
harness_list(resource_type='kg_queryable_type_summary')
```

You can filter by object kind to reduce the response:
```
harness_list(resource_type='kg_queryable_type_summary', kinds=['OBJECT_KIND_VIEW'])
```

This returns lightweight summaries: `identifier` (type_id for HQL), `name`, `description`, `kind` (OBJECT_KIND_*), `connectorId`, `tags`. Pick 1-5 types relevant to the user's question.

**IMPORTANT:** The only valid filter parameters are `kinds` (OBJECT_KIND_*) and `annotations`. Do NOT pass `filters`, `name`, `compact`, or any other made-up parameters — they are silently ignored and you will get the full unfiltered list.

Treat the returned list as authoritative and complete: if a type is not in it, you cannot query it. Do not guess or recall identifiers from earlier conversations, other accounts, or examples.

**Selection criteria:**
- Match by name to user intent
- For cost/billing → types with "ccm", "cost", "billing" in the name
- For pipelines/CI-CD → types with "pipeline", "stage", "execution" in the name
- For issues/tickets → types with "issue", "ticket", "jira", "sei" in the name
- For security → types with "sto", "vulnerability", "scan" in the name
- For audit/activity → types with "audit", "event", "activity" in the name
- For infrastructure → types with "kubernetes", "cloud", "infrastructure" in the name
- Consider type annotations to understand semantic purpose
- Prefer OBJECT_KIND_VIEW over OBJECT_KIND_ENTITY when both cover the same data
- Select 1-5 types that best match the user's query
- Note `connectorId` for each selected type — you need this for JOIN rules

### Step 2: Get field details for each selected type

For each type you selected in Step 1, fetch its full field metadata using the **semantic-layer** `kg_type` resource. **Always pass `params.kind` explicitly, using the exact `kind` value Step 1 returned for that identifier** — never omit it. If `kind` is omitted, `kg_type` silently defaults to `OBJECT_KIND_ENTITY`, which may not be the queryable type you selected in Step 1.

**List-first rule:** `resource_id` MUST be an `identifier` that appeared in a Step-1 `harness_list` response earlier in this session. Do not fetch a type by a guessed, memorized, or copied-from-example identifier. If you need a type you have not listed, run Step 1 first.

```
harness_get(resource_type='kg_type', resource_id='<identifier-from-Step-1>', params={kind: '<kind-from-Step-1>'})
```

`<identifier-from-Step-1>` and `<kind-from-Step-1>` are placeholders — substitute the exact `identifier` and `kind` values a Step-1 response returned. Do not invent literal type ids.

Make one call per selected type (1-5 types). Each returns a single type with its fields (~5-15KB).

From each response, note:
- Field names — use these exact names in HQL queries
- `field_type` values — especially `FIELD_TYPE_LONG` vs `FIELD_TYPE_TIMESTAMP` for time fields (see reference.md Type Casting section)
- Annotations — semantic hints about field purpose

### Step 3: Plan queries using connector groups

**JOIN CONSTRAINT:** You may ONLY join types that share the same `connectorId`. Types in different connector groups use different data sources and CANNOT be joined. When the user's question requires data from types in different connector groups, execute separate queries and correlate results in your analysis.

Group your selected types by connectorId:
- Types within the SAME connectorId CAN be JOINed in HQL
- Types in DIFFERENT connectorId groups require separate queries

### Step 4: Validate and fix

Always validate before executing:

```
harness_execute(resource_type='hql_query', action='validate',
                body={query_string: '<your HQL query>'})
```

**Apply repair suggestions verbatim.** Max 3 attempts (initial + 2 repairs). Repairs fix typos/syntax only — never drop filters, change aggregates, or alter ORDER BY direction. Unrepairable after 3 attempts → stop with a note. See `references/patterns/lint-first.md`.

Common fixes:
- Field name typos — check Step 2 field list
- Missing `group_by` for non-aggregated SELECT columns
- Wrong object kind prefix (entity vs event vs view)
- Unqualified fields in JOIN queries

### Step 5: Run

```
harness_execute(resource_type='hql_query', action='run',
                body={query_string: '<validated HQL query>', max_results: 100})
```

`timeout_ms` and `max_results` are optional. HQL is read-only, so running a query never changes data.

### Default HQL constraints

Unless the question is explicitly scope-agnostic or time-agnostic, every query must include:
1. **Scope**: an `account_identifier` filter, plus `org_identifier` and `project_identifier` when the user names an org or project (or has configured default org/project for the MCP server). If the user gives a Harness UI URL, take the scope from it: `/projects/<id>` → project scope; `/orgs/<id>` without `/projects/` → org scope; otherwise account scope. If scope is unclear, ask the user rather than guessing.
2. **Time window**: default `ago(7d)` when the question implies recency. Maximum is `ago(30d)` — do NOT exceed 30 days unless the user explicitly asks for a longer range and confirms they want to bypass this limit.
3. **Status filter**: `status = 'FAILED'` for failure-diagnosis questions.

### Query shape patterns

These files teach the **shape** of a query for a given question type — how to rank, join, aggregate, and window. They do **not** dictate which entity to use: the correct entity always comes from your Step-1/Step-2 discovery for this account. A "bottleneck" question may resolve to pipeline stages, CI stages, CCM cost, or a security scan queue depending on what discovery surfaces.

**Placeholder convention.** Worked queries in the pattern files are templates, not copy-paste queries. They use `{...}` placeholders you fill from discovery:
- `{module}:{entity}` — a queryable type_id. `{module}` is the domain the question resolves to (`pipeline`, `cd`, `ci`, `ccm`, `sto`, `chaos`, ...) and `{entity}` the specific type — both taken from your Step-1 listing, never assumed. Even `pipeline` is just one module; the same shape applies under any module whose discovery surfaced a matching entity.
- `{duration}`, `{start_time}`, `{status}`, ... — field names confirmed via Step-2 `kg_type` for the chosen entity (sibling entities diverge: `duration` vs `stage_build_time`, `start_ts` vs `start_timestamp`).

The transferable lesson is the structure around the placeholders (which aggregates, which joins, which filters) — not the placeholder values.

- `references/patterns/failure-diagnosis.md` — traverse an execution hierarchy to the failing leaf; filter to the failed rows.
- `references/patterns/build-time-analysis.md` — rank by duration on successful runs; pair `avg`/`p95`/`max`.
- `references/patterns/bottleneck-analysis.md` — rank sub-units by latency; percentiles over averages.
- `references/patterns/flakiness.md` — combine retry, FAIL-then-PASS, and marked-flake signals when the discovered entities expose them.
- `references/patterns/retry-signals.md` — attribute retries down a join chain using discovered join keys.
- `references/patterns/intermittent-vs-consistent.md` — classify by status distribution per group.
- `references/patterns/lint-first.md` — validate before execute, 3-attempt semantic-preserving repair ladder.
- `references/patterns/batch.md` — batching rules (≤20 validate, ≤10 execute).
- `references/entity-reference/ci.md` — CI-native field-name examples (illustrative; confirm via `kg_type`).

## Examples

### Write a query for failed runs

```
/write-hql
Write an HQL query for the pipelines that failed most often in the last 7 days in project my_proj.
```

Expected flow: list queryable types, pick the pipeline execution type, fetch its fields, build the query from `references/patterns/failure-diagnosis.md`, validate it, then run it.

### Fix a query that fails validation

```
/write-hql
This HQL fails validation, fix it: find entity "pipeline:pipeline_execution" | select {status, count()}
```

Expected flow: validate, read the errors, and repair syntax only (here, the missing `group_by status`).

### Find what data is available

```
/write-hql
Which types can I query for security issues, and what fields do they have?
```

## Performance Notes

- Start with `kg_queryable_type_summary`, not the grammar. Summaries are small; the grammar is large.
- Pass `kinds` on the list call to cut the response size.
- Fetch `kg_type` only for the 1-5 types you will use, one call per type.
- Always include a `limit`, and prefer aggregates over raw rows for large populations.
- Validate every query before running it. Batch validations as described in `references/patterns/batch.md`.

## Troubleshooting

### `kg_queryable_type_summary` or `hql_query` is not available

The MCP server is missing the `knowledge-graph` toolset. It is enabled by default; if `HARNESS_TOOLSETS` is set, make sure it includes `knowledge-graph` and `semantic-layer`.

### `kg_type` is not available

`kg_type` belongs to the `semantic-layer` toolset. Enable it alongside `knowledge-graph`.

### Empty type list or 401/403/404 from the query service

Check that the API key can read the account's data and that `HARNESS_BASE_URL` points at the right Harness instance. A 404 on the query service path means the gateway for that instance does not route `/query-service/`, or the query service is not enabled for the account.

### Validation keeps failing after 3 attempts

Stop and report the last error to the user. Do not drop filters or change aggregates to make the query pass.

### A field or type does not exist

Re-run Step 1 and Step 2. Types and fields differ between accounts, and sibling entities use different field names.
Files in this package (12)
  • SKILL.md 12 KB
  • reference.md 7 KB
  • references/analysis-workflow.md 7 KB
  • references/entity-reference/ci.md 2 KB
  • references/patterns/batch.md 1 KB
  • references/patterns/bottleneck-analysis.md 2 KB
  • references/patterns/build-time-analysis.md 2 KB
  • references/patterns/failure-diagnosis.md 2 KB
  • references/patterns/flakiness.md 3 KB
  • references/patterns/intermittent-vs-consistent.md 2 KB
  • references/patterns/lint-first.md 2 KB
  • references/patterns/retry-signals.md 2 KB

Versions

The database has no other skills named write-hql.

Database snapshot: 13.11.2026 · package version 84b4eab15071 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100flux-query
    Optimize slow database queries — analyze execution plans, add indexes, rewrite queries. Use when asked about "slow query", "optimize SQL", "query performance", or "explain this query".
  • 100write-aql
    Write and run AQL (Analytic Query Language) queries to answer data questions. Use this whenever the user asks for data, wants to query a dataset, needs to filter/aggregate/join data, or asks about metrics and dimensions in Holistics.
  • 100hibernate-upgrade
    Migrate Hibernate 5 to Hibernate 6 with Spring Boot 3. Use when fixing HQL/JPQL query parsing issues, removing deprecated Criteria API, updating ID generation strategies, or diagnosing N+1 query behavior changes. Covers breaking changes, type mappings, and performance monitoring.
  • 100sql
    Write, run, and explain SQL queries, and do quick local analysis of CSV/SQLite data with the sqlite3 CLI. Use when users want a SQL query written or fixed, want to query a .db/.sqlite file, or want to analyze a CSV with SQL (joins, group by, window functions). Triggers on…
  • 100run-eventql-query
    Run an EventQL query against an EventSourcingDB instance. Use when the user wants to query, filter, aggregate, or analyze events using the EventQL query language.
  • 100harness-pipeline
    This skill should be used when the user asks to "run a Harness pipeline", "trigger a deployment pipeline", "monitor a Harness execution", or "check pipeline status" — executing and watching Harness pipelines with Jira integration.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.