You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[decision] data.find is @deprecated while QueryOptionsV2 still calls itself "the recommended interface for data.find() queries" — the canonical source contradicts itself; pick a direction #6795
Spun out of #6323 / PR #6784 at acceptance, by the devx PM seat. The docs half is done — the services.data page now reports both faces accurately with attribution, so it survives either ruling. What remains is the source-side convergence in packages/client, which is a maintainer call. Filed unassigned; ⛔ not dispatchable until ruled.
The contradiction, measured (all on origin/main @ 64d764e76)
packages/client/src/index.ts:4202 — data.find carries @deprecated Use data.query() with standard QueryAST parameters instead, and the built dist/index.d.ts:2687 ships the tag, so every consumer's editor strikes find through at the call site.
packages/client/src/index.ts:162-164 — QueryOptionsV2 simultaneously names itself "the recommended interface for data.find() queries": a recommended vocabulary for a deprecated method.
data.query() exists on both ObjectStackClient.data (:4190) and ScopedProjectClient.data (:4913), ships untagged, and has a dedicated POST /data/:object/query route (rest-server.ts:5694).
The tag is recorded direction, not an accident: [讨论&决策] 前后端查询协议/OData vs QueryAST 规范化与长期归一方案 #986 ruled "deprecate the legacy-parameter entries, promote data.query(AST)"; the tag landed in 17dca13 (QueryAST unification) and was deliberately kept when c463c23 added QueryOptionsV2.
query is strictly more capable on this surface: search, nested expand detail, having — and find's own nested-expand refusal error routes callers to query.
Real consumers already moved: the CLI's data query command and objectui's data adapter both call data.query(); objectui's adapter comments record concrete find pain (forced raw-HTTP workarounds).
The heavy in-repo find usage is IDataEngine.find — a different, lower surface, not this one.
Options
A — Uphold [讨论&决策] 前后端查询协议/OData vs QueryAST 规范化与长期归一方案 #986: keep the tag; find eventually exits; make the one-line convergence edit now — reword QueryOptionsV2's self-description to something like "the vocabulary find still accepts", so it stops reading as an endorsement of a deprecated method.
B — Withdraw the deprecation: remove @deprecated from data.find (and the QueryOptions entry), accepting find as a permanent stable simplified entry beside query. Overrules [讨论&决策] 前后端查询协议/OData vs QueryAST 规范化与长期归一方案 #986's recorded direction.
Recommendation (dev and PM seat concur): A
The deprecation is implemented product direction with consumers already migrated; the only defect is the stale self-description, which is a one-line edit. B would overrule a recorded ruling to preserve a sentence.
If A is ruled, the implementing change is small (JSDoc wording in packages/client, plus a changeset since published source changes) and can ride any normal dispatch round.
Related: #6323 / PR #6784 (docs half, has the full measurement), #986 (the direction ruling), 17dca13 / c463c23 (tag history).
Maintainer ruling (2026-08-09): Option A — uphold #986.pm:queue.
The @deprecated tag on data.find stays; the one-line convergence edit lands: reword QueryOptionsV2's self-description so it stops calling itself "the recommended interface" for a deprecated method (the card's suggested phrasing — "the vocabulary find still accepts" — is fine). JSDoc wording in packages/client plus a changeset, ridable on any normal dispatch round.
Rationale: the deprecation is implemented product direction with consumers already migrated (CLI and objectui both call data.query()); B would overrule a recorded ruling to preserve a sentence. Dev and PM seat already concurred; this ruling confirms.
Maintainer directive (verbatim, covering all 25 decision-inbox cards this round): 「全部接受」. Recorded by PM session session_01LGRN2cSRfggfX9B2L83bQc. Veto window open — comment to overturn.
Spun out of #6323 / PR #6784 at acceptance, by the devx PM seat. The docs half is done — the
services.datapage now reports both faces accurately with attribution, so it survives either ruling. What remains is the source-side convergence inpackages/client, which is a maintainer call. Filed unassigned; ⛔ not dispatchable until ruled.The contradiction, measured (all on
origin/main@64d764e76)packages/client/src/index.ts:4202—data.findcarries@deprecated Use data.query() with standard QueryAST parameters instead, and the builtdist/index.d.ts:2687ships the tag, so every consumer's editor strikesfindthrough at the call site.packages/client/src/index.ts:162-164—QueryOptionsV2simultaneously names itself "the recommended interface for data.find() queries": a recommended vocabulary for a deprecated method.Supporting facts from the #6323 investigation:
data.query()exists on bothObjectStackClient.data(:4190) andScopedProjectClient.data(:4913), ships untagged, and has a dedicatedPOST /data/:object/queryroute (rest-server.ts:5694).QueryOptionsV2.queryis strictly more capable on this surface:search, nestedexpanddetail,having— andfind's own nested-expand refusal error routes callers toquery.data querycommand and objectui's data adapter both calldata.query(); objectui's adapter comments record concretefindpain (forced raw-HTTP workarounds).findusage isIDataEngine.find— a different, lower surface, not this one.Options
findeventually exits; make the one-line convergence edit now — rewordQueryOptionsV2's self-description to something like "the vocabularyfindstill accepts", so it stops reading as an endorsement of a deprecated method.@deprecatedfromdata.find(and theQueryOptionsentry), acceptingfindas a permanent stable simplified entry besidequery. Overrules [讨论&决策] 前后端查询协议/OData vs QueryAST 规范化与长期归一方案 #986's recorded direction.Recommendation (dev and PM seat concur): A
The deprecation is implemented product direction with consumers already migrated; the only defect is the stale self-description, which is a one-line edit. B would overrule a recorded ruling to preserve a sentence.
If A is ruled, the implementing change is small (JSDoc wording in
packages/client, plus a changeset since published source changes) and can ride any normal dispatch round.Related: #6323 / PR #6784 (docs half, has the full measurement), #986 (the direction ruling), 17dca13 / c463c23 (tag history).