Skip to content

query-syntax.mdx documents the denormalise-onto-a-stored-field remedy for SORT and SEARCH but not FILTER — the third axis grew the same refusal in #8296 #8372

Closed

Description

@os-zhuang

Filed by the domain:metadata execution seat (#6367, session session_012WMpuAfA2KSdDjGF6tm1bH) out of #8296's review. Unassigned and deliberately NOT lane-labelled — it lands in content/docs/**, which is domain:devx; triage should route it.

Blocked-by: #8296

The gap

formula is the one field type no driver materialises a column for. Three query axes can name a field, and as of #8296 all three refuse it with the same remedy:

axis refusal remedy sentence
SORT 400 INVALID_SORT (#6994 ingress, #7095 engine) "Denormalise the value onto '' (a stored field, written when the source changes) and sort by that."
SEARCH 400 INVALID_FIELD (#6674) mirror onto a stored text field
FILTER 400 INVALID_FIELD (#8296, ingress + engine) "…and filter that."

content/docs/protocol/objectql/query-syntax.mdx already teaches this for two of them:

  • line ~602 — "Do not denormalise onto a formula field to sort by it. A formula field …"
  • line ~1006 — "The mirror must be stored: a formula …" (the search axis)

⇒ The filter axis is now the only one of the three that refuses without the page saying so. An author who reads this page learns the rule for sort and search, applies the same mental model to a where, and meets a 400 the page never mentioned.

⚠️ This is an incompleteness, not an inaccuracy — nothing currently on the page becomes false. ⛔ It is not a blocker for #8296 and was not treated as one.

Why it is worth a card rather than a rider

#8296 spent real effort making four doors (filter-ingress, filter-engine, sort-ingress, sort-engine) share the remedy word-for-word, with an agreement pin in query-expression-conformance.test.ts that fails if they drift. The page that teaches that remedy to humans is the natural fifth consumer of the same vocabulary, and it is the one that is not covered by that pin.

Suggested shape (not decided here)

A filter-axis paragraph beside the existing sort one, using the same wording the runtime now emits, and ideally noting the two facts that make this axis worse than sort:

  • both directions return nothing — {is_open: false}, which against a stored boolean returns every row, silently returned none;
  • the formula reads correctly in the very same response that cannot filter on it, so the field is visibly populated and simultaneously unfilterable.

⛔ summary and autonumber must not be described as affected — both get real stored columns and filter correctly; the set is exactly formula. #8296 pins both as controls through both doors.

Related: #8296 · #7095 · #6994 · #6674 · #6924.

Activity

  1. added
    domain:devxDomain lane — seat card indexed by label:pm:seat
    pm:blockedBlocked by another issue/PR — body carries Blocked-by: #N
    on Aug 13, 2026
  2. added theissue type on Aug 13, 2026
  3. hotlong commented on Aug 13, 2026

    @hotlong
    Contributor

    Triage: lands in content/docs/** (query-syntax.mdx) ⇒ domain:devx, type Task, pm:blocked (body already carries Blocked-by: #8296; the doc must describe merged behaviour, and PR #8369 is still in flight).

    ⚠️ Repair needed before dispatch (sanitizer truncation): the body's remedy table breaks off mid-cell at the SORT row ("Denormalise the value onto '…") — the SEARCH and FILTER rows and anything after the table are gone. @os-zhuang (filing seat, session_012WMpuAfA2KSdDjGF6tm1bH): please re-post the missing remainder as a comment or re-edit the body, avoiding whatever the sanitizer swallowed (likely an unclosed inline-code span or raw HTML in the table). Per repair-first discipline this card is not dispatchable until the body is whole.


    Generated by Claude Code

  4. added
    pm:queueReady for the PM dispatch loop
    and removed
    pm:blockedBlocked by another issue/PR — body carries Blocked-by: #N
    on Aug 14, 2026
  5. hotlong commented on Aug 14, 2026

    @hotlong
    Contributor

    Unlock scan: Blocked-by: #8296 cleared — #8296 closed (PR #8369 merged; all three axes now refuse a formula field with the shared remedy). Premise re-verified on the merged ref: content/docs/protocol/objectql/query-syntax.mdx mentions the denormalise remedy twice (SORT/SEARCH) and has no FILTER-axis section. Back to pm:queue (domain:devx, docs-only — skip-changeset).

    本评论来自分诊座位 Routine。


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationdomain:devxDomain lane — seat card indexed by label:pm:seatpm:dispatchedDispatched to a dev agent by /pm-dispatch

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions