Skip to content

docs(skills): LogsQL clause-order and _time iron rules on the monit-query card - #154

Closed
ysyneu wants to merge 1 commit into
mainfrom
docs/logsql-iron-rules
Closed

docs(skills): LogsQL clause-order and _time iron rules on the monit-query card#154
ysyneu wants to merge 1 commit into
mainfrom
docs/logsql-iron-rules

Conversation

@ysyneu

@ysyneu ysyneu commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Why

skills/flashduty/reference/monit-query.md teaches monit-query data --expr by example for PromQL and Loki, but LogsQL appears only as a routing keyword in "Route here when". A VictoriaLogs query therefore gets written with SQL/PromQL/Loki habits and is rejected by the datasource on syntax alone — and because the rejection is a parse error rather than a semantic one, retries that only reword the aggregate fail identically.

What

Two gotcha bullets plus a LogsQL worked example:

  • stats puts by (...) before the aggregate| stats by (level) count() n. The trailing-by forms (| stats count(*) by (level), | stats count() by level, | stats count(*) as n by level) all fail with cannot parse 'stats' pipe: unexpected token ... after [count(*)]. Multi-key and no-by global aggregate shapes are given too, along with the ordinary downstream pipes (sort, limit, filter).
  • _time: takes a duration or a bracketed range_time:1h, _time:[<rfc3339>, <rfc3339>]. Slash ranges and abbreviated dates fail with cannot parse duration at _time filter.

Every accepted and rejected form in the text was executed against a live VictoriaLogs instance before being written down.

Verification

  • go build ./... clean
  • go test ./... — all packages pass (incl. internal/skilldoc)
  • Docs-only change; no command surface or generated fence touched.

…uery card

The monit-query card teaches `data --expr` by example for PromQL and Loki
but names LogsQL only as a routing keyword, so a VictoriaLogs query gets
written with SQL/PromQL/Loki habits and comes back 422 on syntax alone.

Two dialect rules that differ from every other backend the card covers:

- `stats` takes `by (...)` BEFORE the aggregate: `| stats by (level) count() n`.
  Trailing `by` — the SQL/PromQL/Loki form — is a parse error, so the retry
  that only changes the aggregate spelling fails identically.
- `_time:` accepts a duration or a bracketed range (`_time:[<rfc3339>, <rfc3339>]`),
  never a slash range, and never an abbreviated date.

Both are stated with the exact rejected forms and the error text they produce,
plus a LogsQL worked example alongside the existing Loki one.
@ysyneu

ysyneu commented Aug 20, 2026

Copy link
Copy Markdown
Contributor Author

Closing — this card no longer reaches a reader.

skills/flashduty/ is hidden: true: withheld from public skill discovery and not packaged into any release artifact. Its one consumer is Safari, which embeds the tree directly, and Safari has since dropped its monit-query card in favour of a standalone monit-query skill that ships per-datasource query-language references. The LogsQL clause-order and _time rules this PR adds have landed there instead, in the VictoriaLogs reference where a reader constructing a query will actually be looking.

The fduty monit-query command group is unaffected: #157 corrects its --ds-type surface (diagnose never accepted mysql) and #158 splits the oversized monit card.

@ysyneu ysyneu closed this Aug 20, 2026
@ysyneu
ysyneu deleted the docs/logsql-iron-rules branch August 20, 2026 05:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant