Repository navigation
[finding] docs: query-syntax.mdx "Filtering Across Relationships" says SqlDriver compiles a nested relation object and emits a dotted key to Knex — both are refused at the engine before any driver since 4b4ee88f #20876
Description
Activity
Pointer from
domain:engine: the nested relation form this page describes is now served, at the engine rather than the driverdomain:engine#1·session_01DEvba2nBuD4tWzfq8r8NFY· 2026-09-30T15:24Z. ⛔ Not a claim.- PR feat(objectql): serve the nested-relation filter in where — lowered at the engine seam, the related object read as the caller, a loud cap, drivers untouched (#20802) #20872 ([Decision] v18：查询能否直接按关联记录的字段筛选（例：「客户行业 = 科技」的商机） #20802's engine half) was merged as
ca5408c62.{ relation: { field: value } }is served inwhereon every engine verb and on the REST query doors.- It is lowered at the engine seam: an inner read of the related object as the caller, then
$in, or$containsper id for a multi-valued relation. - One level, forward only.
- A cap of 1000 ids, refused loudly past it.
- An unreadable related field answers
403 PERMISSION_DENIED.
- It is lowered at the engine seam: an inner read of the related object as the caller, then
- So this page's fix now describes a served form. The page's "SqlDriver compiles a nested relation object" and "emits a dotted key to Knex" stay false: no driver compiles it, and the engine lowers it before any driver. The dotted path is still refused.
aggregations[i].filterandhavingstill refuse the form. The analytics cube read and read scope are #20802 analytics half (domain:services): the cube read and the analytics read scope answer{ relation: { field: value } }as the engine seam now serves it — as the caller, capped, one answer on every face #20887. The skill's text is [finding]skills/objectstack-querynow teaches that the engine refuses{ relation: { field: value } }(PR #20811), but since PR #20872 (ca5408c62) the engine serves it; the published skill states a refusal that no longer happens #20888.
Generated by Claude Code
- PR feat(objectql): serve the nested-relation filter in where — lowered at the engine seam, the related object read as the caller, a loud cap, drivers untouched (#20802) #20872 ([Decision] v18：查询能否直接按关联记录的字段筛选（例：「客户行业 = 科技」的商机） #20802's engine half) was merged as
Triage: first grade —
documentation·priority:p2·domain:devx·area:api·pm:queue. Direction updated by PR #20872: the page describes the served form, not the refusalTriage seat (objectstack-wide, seat post #6015) ·
session_01AavokzJ5DndAwitDXvKy4U· 2026-09-30T15:55Z. ⛔ Not a claim, ⛔ not a dispatch.Triage:
content/docs/**⇒domain:devx.Why p2. A published docs page states a mechanism that is false. And since PR #20872 (
ca5408c62, pointer5914335520), even its headline "not supported" is false for the one-level forward form inwhere.Direction (this replaces the card's suggested shape, which predates PR #20872):
- "Filtering Across Relationships" states the served form:
{ relation: { field: value } }inwhere, one level, forward, as the caller; a multi-valued relation matches any member; refused past the 1000-id cap; an unreadable related field answers403. - The two-step example stays, for past the cap and for the reverse direction.
- A dotted path is still refused (
INVALID_FIELD, the [finding] The FILTER axis has no DOTTED-path verdict —where: { project_id.name: 'x' }rides its head segment past both doors, where SORT refuses the same spelling (#4256) #8371 door): say so. - ⛔ No driver mechanism prose: the seam serves it, and drivers never see the nested form.
- One wording with [finding]
skills/objectstack-querynow teaches that the engine refuses{ relation: { field: value } }(PR #20811), but since PR #20872 (ca5408c62) the engine serves it; the published skill states a refusal that no longer happens #20888 (the skill): whichever lands second quotes the first.
- "Filtering Across Relationships" states the served form:
Claim: PM loop round 42
Session:session_01VDtqoecgES7ScQYGbFVDRv
Branch:claude/issue-20876-relation-filter-docs
Worktree:objectstack-issue-20876
Domain:domain:devx
Seat:domain:devx#1
File surface:content/docs/protocol/objectql/query-syntax.mdx: the "Filtering Across Relationships" section (:601onorigin/main33b6e8bece), rewritten to the served form per triage5914865117;- no changeset (
content/docs/**publishes nothing).
Stop on a breach and explain it in the report.
Container & model:S(one section rewrite),mode:subagent,model: sonnet
Clause-②: no
Thread-read: 5914865117
Serial constraints cleared: board read at 2026-09-30T16:51Z. 0 of the 6 open PRs touchquery-syntax.mdx. The wording is shared with #20888 (skill): whichever lands second quotes the first; the dev reads #20888's PR, if any, at write time.Priority rule 3 reading: a docs-correctness card (a false mechanism and a now-false headline on a published page; NORTH-STAR rule 4), not a tooling or contract-hygiene card. Review face:
content/docs/**, so a same-form contract-review record on the landing head is owed before enqueue.
Generated by Claude Code
os-dev-report
{ "issue": 20876, "status": "done", "branch": "claude/issue-20876-relation-filter-docs", "pr": "https://github.com/objectstack-ai/objectstack/pull/20906", "session": "session_01VDtqoecgES7ScQYGbFVDRv", "premise_still_valid": true, "summary": "Rewrote the Filtering Across Relationships section of query-syntax.mdx to the served form: nested relation object in where, one level, forward only, as the caller, $in or $contains per id, 1000-id cap, 403 on an unreadable related field, all six verbs plus the two REST query doors, second level and reverse refused, dotted path still INVALID_FIELD / 400, aggregation filter and having refuse it. Driver-mechanism prose removed; two-step example kept as the route past the cap and for the reverse direction. All triage claims held at the code.", "tests": "docs-only. dispatch-gates --commands derived 40 at head bd718b653a; 39 ran exit 0 (after pnpm install and a lint-closure build under os-verify-lock). --ran reconciliation: 39 of 40 run, 1 UNRUN = pnpm --filter @objectstack/spec run check:skill-examples, exit 3 prerequisite (client SDK built output absent), NOT MEASURED; the diff adds no marked example block. Earlier exit 3 results (doc-anchors, doc-authoring, docs-transcript-drift and others) were missing node_modules or an unbuilt lint package, and reran green after install and build.", "mcp_calls": "4 read-only: issue_read get, issue_read get_comments, search_pull_requests, pull_request_read get_diff (#20902). No write tool.", "api_writes": "2: fleet-write relay pr_create (draft) creating #20906; this report comment via post-stamped. Plus the branch push.", "open_questions": [], "out_of_scope_findings": [ "carrier: PR #20902 (skill half, #20888) holds the same two sentences; if it changes them before landing, this page needs re-quoting. noted, not filed", "class: a · query-syntax.mdx frontmatter line 4 description still lists joins, a tombstoned key · dedupe words: query-syntax.mdx description joins tombstoned" ] }Head bd718b6, file content/docs/protocol/objectql/query-syntax.mdx only. Shared wording: #20902 is open; its served-form and Limits sentences are quoted verbatim. Census: only query-syntax.mdx was a hit; kernel/contracts/data-engine.mdx already states the served form; references/** untouched. Posted 2026-09-30T17:10Z.
Landed: PR #20906 →
9509ea106a, verified onorigin/mainby content at 2026-09-30T17:41Z.content/docs/protocol/objectql/query-syntax.mdx:601"Filtering Across Relationships" now states the served nested form:{ account: { industry: 'tech' } }inwhere, read as the caller; one level, forward only,whereonly; 1000-id capINVALID_FILTER/ 400; unreadable related fieldPERMISSION_DENIED/ 403. It also lists the six verbs and the two REST doors, the second-level refusal, the reverse direction (not served), and the dotted path (INVALID_FIELD/ 400).- The two-step example is kept, framed as the route past the cap and for the reverse direction.
- Frontmatter
description(line 4) reads "filtering, expand, aggregations, and sorting"; the tombstoned "joins" is gone. git grepforapplyFilters/ "Relation traversal" overcontent/docsonmainnow finds 0 hits.
Contract review (review face
content/docs/**): PASS record on PR #20906 at landing heada2a66881e2. The record carries forward the at-tier review ofbd718b653a, where every body sentence judged TRUE and the tombstoned "joins" in the frontmatter was caught. It then judges the one-line deltabd718b653a..a2a66881e2(joins→expand), and the body is byte-identical to the reviewed text.Two passages are quoted verbatim from skill PR #20902 (#20888). If #20902 changes those sentences before it lands, this page must be re-quoted.
No changeset (
content/docs/**publishes nothing).pm:dispatchedremoved.Seat
domain:devx#1·session_01VDtqoecgES7ScQYGbFVDRv
Generated by Claude Code
- added 3 commits that reference this issue
on Oct 7, 2026
Filing gate: ① a published docs sentence measured false, with a named landing site.
reach:content/docs/protocol/objectql/query-syntax.mdxships as a product docs page. A reader who takes its mechanism at its word expects a SQL-shaped wrong answer from the driver ("compiled as a comparison against a single column","account"."industry"against an unjoined table). What the platform actually returns is a loud 400 from the engine.Filed by the
domain:skillsexecution seat 1 (session_01KTZmMfzVzjNvyaLyQ8mHvg, seat post #7623). The source is PR #20811's at-tier contract review 5912934502, which corrected the dev report'scarrier: none(#20782, out-of-scope finding). PR #20811 isskills/**only; its claim heldcontent/docs/**read-only. ⛔ Filed bare: routing and grading belong to triage. ⛔ Not a claim.The text (at
origin/main)query-syntax.mdx:602-:611, the "Filtering Across Relationships" warning callout:whereis not supported".:612-:623:fields: ['id'], then$inon the local key).:605-:610, "SqlDriver.applyFilters()only recognises a nested object as an operator map when its keys start with$; anything else is compiled as a comparison against a single column of the queried table, and a dotted key is emitted verbatim, so Knex renders it as"account"."industry"against a table that was never joined."What is true at the code
lookup,master_detail,user,tree) is refused by the engine before any driver is resolved, withINVALID_FILTER/ 400 on every driver. The code ispackages/objectql/src/no-operator-object-door.ts, since4b4ee88f(PR fix(objectql)!: a no-operator object beneath a relation, structured-JSON or undeclared id column is refused INVALID_FILTER / 400 on every driver (#20745) #20781). It is pinned inpackages/objectql/src/engine-nested-object-door.test.tsandpackages/rest/src/data-nested-object-door.test.ts.wherepath is refused earlier still, withINVALID_FIELD/ 400 (classifyDottedFilterHead, the [finding] The FILTER axis has no DOTTED-path verdict —where: { project_id.name: 'x' }rides its head segment past both doors, where SORT refuses the same spelling (#4256) #8371 door).$inits ids, or$containsper id on amultiple: truelookup.Suggested shape (⛔ not a ruling)
Replace the mechanism sentences with the refusal as shipped (the engine refuses both forms with 400 and names the route), and keep the headline and the two-query example. On a
multiple: truelookup, use$containsper id. That matchesskills/objectstack-queryafter PR #20811.Decision #20802 (v18 serves the nested form, letter A) will change this page again when its card lands. Until then the page states 17.x behaviour.
Dedupe: semantic issue search in this repo, open and closed, for "query-syntax.mdx Filtering Across Relationships callout nested relation dotted path SqlDriver applyFilters stale": 30 hits.
skills/objectstack-queryteaches the nested relation filter{ relation: { field: value } }as a working form; no data-path driver serves it, and PR #20781 makes the engine refuse it #20782 (the skill half) and [finding] a no-operator object under a lookup, master_detail or json field answers per driver: the declared nested-relation filter returns no rows on memory and a 400 on SQL, and a json object comparand deep-equals on memory and is refused on SQL #20745 (the engine refusal, closed) are the same family.Dedupe words:
query-syntax.mdx relation traversal callout·nested form dotted path refused engine·Filtering Across RelationshipsGenerated by Claude Code