From 7834e132279e4643b13545fa7f81fbcebda7e06d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 13:47:22 +0000
Subject: [PATCH] =?UTF-8?q?docs(kernel):=20services.data=20=E7=9A=84=20Par?=
 =?UTF-8?q?ameters=20=E8=A1=A5=E4=B8=8A=20canonical=20QueryOptionsV2=20?=
 =?UTF-8?q?=E8=AF=8D=E6=B1=87=20(#6002)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Methods 一节写明 find 接受 QueryOptions | QueryOptionsV2,但 Parameters 只列
legacy 那套(top/skip/filter/sort/select)。canonical source
packages/client/src/index.ts 的自述正好相反:QueryOptions 带 @deprecated、
"require translation to QueryAST";QueryOptionsV2 是 "the recommended interface
for data.find() queries"。本页因此把 SDK 自称推荐的词汇整个略过。

Parameters 改为并列两套并点明推荐关系(canonical where/fields/orderBy/limit/
offset,legacy filter/select/sort/top/skip 仍受支持、运行时翻译),Example 同批
换用 canonical 词汇。推荐关系由 JSDoc 写死,不是本 PR 的取舍。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3
---
 .../kernel/runtime-services/data-service.mdx  | 43 ++++++++++++++++---
 1 file changed, 38 insertions(+), 5 deletions(-)

diff --git a/content/docs/kernel/runtime-services/data-service.mdx b/content/docs/kernel/runtime-services/data-service.mdx
index 89789791bf..12950fcb0b 100644
--- a/content/docs/kernel/runtime-services/data-service.mdx
+++ b/content/docs/kernel/runtime-services/data-service.mdx
@@ -60,7 +60,39 @@ key for key. A managed runtime binds `services.data` to this same shape.
 - `object`: short object name (for example `task`, `account`)
 - `id`: record ID for single-record operations
 - `data`: partial payload for create/update
-- `options` (`find`): filters, sorting, pagination (`top`, `skip`, `filter`, `sort`, `select`)
+- `options` (`find`): filtering, sorting and pagination — two vocabularies, one
+  behaviour; see the table below
+
+### `find` options: canonical and legacy
+
+The signature above accepts `QueryOptions | QueryOptionsV2`, and the Canonical source
+declares which of the two to write. `QueryOptionsV2` is *"canonical query options using
+Spec protocol field names … the recommended interface for `data.find()` queries"*, while
+`QueryOptions` carries an `@deprecated` tag in the same file describing *"legacy parameter
+names … that require translation to QueryAST"*, with the instruction to *"prefer QueryAST
+fields directly"*. Both interfaces are declared in `packages/client/src/index.ts`, so the
+recommendation is the SDK's own, not this page's.
+
+| Canonical (`QueryOptionsV2`) | Legacy (`QueryOptions`) | Clause |
+|:---|:---|:---|
+| `where` | `filter` | filter conditions (`WHERE`) |
+| `fields` | `select` | field selection (`SELECT`) |
+| `orderBy` | `sort` | sort definition (`ORDER BY`) |
+| `limit` | `top` | maximum records (`LIMIT`) |
+| `offset` | `skip` | records skipped (`OFFSET`) |
+
+**Write the left column.** Those are the QueryAST and protocol field names, so the same
+words carry from here down through `data.query()` into the query layer — one translation
+step fewer to hold in your head.
+
+**The right column still works.** Nothing refuses it: `find` recognises a canonical
+options object and normalizes it into exactly the transport parameters the legacy names
+produce, so the two columns are equivalent, not merely similar. Deprecated here means
+"prefer the other spelling", not "scheduled for removal in this version".
+
+**Use one column per call.** `find` reads either the canonical names or the legacy ones
+for a given options object, never a blend — a key from the other column is dropped
+silently rather than refused, so migrate an options object as a whole.
 
 ## Returns
 
@@ -93,11 +125,12 @@ export async function recentOrdersForContact(data: DataService, contactId: strin
   // `get` resolves the response envelope `{ object, id, record }` — the row is `record`.
   const { record: contact } = await data.get<{ id: string; name: string }>('contact', contactId);
 
-  // `find` resolves `{ records, total?, hasMore? }`.
+  // `find` resolves `{ records, total?, hasMore? }`. The options are the canonical
+  // `QueryOptionsV2` vocabulary — `where` / `orderBy` / `limit`, not `filter` / `sort` / `top`.
   const { records: orders } = await data.find<{ id: string; amount: number }>('sales_order', {
-    filter: { contact_id: contact.id },
-    sort: [{ field: 'created_at', order: 'desc' }],
-    top: 20,
+    where: { contact_id: contact.id },
+    orderBy: [{ field: 'created_at', order: 'desc' }],
+    limit: 20,
   });
 
   return { contact, orders };