narrative-io/narrative-skills-marketplace / plugins/narrative-common/skills/write-nql
write-nql
VerifiedWrite, validate, and (optionally) execute an NQL query against a Narrative dataset. Drafts the query from the user's question, runs `narrative_nql_validate` until it compiles, explains the query in plain English, and only runs it on explicit approval (or when invoked with `--run`). Use when: "write an NQL query for X", "query this dataset", "validate this NQL", "run NQL against dataset <id>", "how many rows match Y", "show me the top N records from <dataset>". (narrative-common)
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 37.2 KB |
| SKILL.md.tmpl | other | 21.2 KB |
| references/EDGE_CASES.md | markdown | 1.2 KB |
| references/HARNESS_FALLBACK.md | markdown | 2.5 KB |
| references/HARNESS_FALLBACK.md.tmpl | other | 858 B |
| references/NQL_ASYNC_DEEP.md | markdown | 4.7 KB |
| references/NQL_GOTCHAS.md | markdown | 6.6 KB |
| references/NQL_QUOTING_AND_TABLE_REFS.md | markdown | 3.9 KB |
| references/NQL_VALIDATION_ERRORS.md | markdown | 2.5 KB |
| references/PERCENTILE_DISTRIBUTION.md | markdown | 3.9 KB |
references/NQL_VALIDATION_ERRORS.md
View on GitHub# Validation error → fix cheat sheet
When `narrative_nql_validate` returns an error, look up the message
text here for the canonical fix. Each row maps a verbatim or
near-verbatim error symptom to the most likely cause and the
shortest fix that resolves it. For deeper context on the underlying
rule, follow the link to [`NQL_GOTCHAS.md`](NQL_GOTCHAS.md) or the KB.
| Error symptom | Likely cause | Fix |
| --- | --- | --- |
| "syntax error at or near 'type'" | Unquoted reserved word | Quote as `"type"` |
| "syntax error at or near '!='" / "'!'" | Used `!=` for not-equals | Replace with `<>` — NQL only accepts the standard SQL inequality operator |
| "column not found" | Wrong identifier name / casing | Re-check schema via `narrative_datasets_describe` |
| "function does not exist" | Wrong function name (e.g., `LCASE`) | Use the supported function list in the syntax-essentials snippet |
| "No match found for function signature `date_parse`/`parse_datetime`" | Function not exposed | Use `to_timestamp(text, format)` or `CAST(... AS timestamp)` |
| "No match found for function signature `APPROX_PERCENTILE`" or run-time 500 on `PERCENTILE_CONT` | Percentile functions not available on the Snowflake data plane | Bucketed counts or row-position derivation — see [`PERCENTILE_DISTRIBUTION.md`](PERCENTILE_DISTRIBUTION.md) |
| Validate-only "Unknown Table" on `company_data."<numeric_id>"` that run accepts | Validate call omitted `data_plane_id` and fell back to the company default plane | Pass `data_plane_id` to `narrative_nql_validate` matching the dataset's plane — same value as you'll pass to `narrative_nql_execute` |
| "cannot cast string to long" | Implicit coercion | Wrap with `CAST(... AS long)` or `NULLIF` |
| "unexpected ELSE without CASE" | Mismatched CASE/END | Count `CASE … END` pairs |
| "wildcard not supported" / "SELECT \* not supported" | Used `SELECT *` or `COUNT(*)` | Enumerate columns; use `COUNT(1)` or `COUNT(<col>)` |
| "Unsupported GEOMETRY type" | `GEOMETRY` returned in `SELECT` | Move geometry to `JOIN` / `WHERE` only; project `latitude` / `longitude` / ids |
| "String Concatenation" type error | `\|\|` mixing non-string types | `CAST(<x> AS VARCHAR)`, or extract `.value` from structured fields |
| "Cross-Data Plane Query" error | Datasets in different planes | Query each plane separately, or materialize into one plane |
If the error message doesn't appear in this table, fall back to
[`NQL_GOTCHAS.md`](NQL_GOTCHAS.md) (the full failure-mode catalog) and
the `narrative-knowledge-base` MCP server.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |