platform-soql-query

platform-soql-query：Salesforce SOQL 查詢專家

當使用者需要 SOQL/SOSL 撰寫或最佳化時使用此技能：自然語言轉查詢、關係查詢、彙總、查詢計畫分析，以及 Salesforce 查詢的效能/安全性改善。

此技能負責的任務

當工作涉及以下內容時，使用 platform-soql-query：

• .soql 檔案
• 從自然語言產生查詢
• 關係查詢與彙總查詢
• 查詢最佳化與選擇性分析
• SOQL/SOSL 語法與 governor 感知設計

當使用者正在執行以下操作時，請委派給其他技能：

• 執行大量資料操作 → platform-data-manage
• 在更廣泛的 Apex 實作中嵌入查詢邏輯 → platform-apex-generate
• 透過日誌而非查詢形狀進行除錯 → platform-apex-logs-debug

---

首先收集的必要內容

詢問或推斷：

• 目標物件
• 所需欄位
• 篩選條件
• 排序 / 限制需求
• 查詢用途：顯示、自動化、報表式分析或 Apex 使用
• 是否已關注效能 / 選擇性

---

建議工作流程

1. 產生最簡單的正確查詢

偏好：

• 僅選取必要欄位
• 明確的 WHERE 條件
• 適當的 LIMIT（若適用）
• 關係深度僅達必要程度

2. 選擇正確的查詢形狀

需求	預設模式
從子物件取得父資料	子對父遍歷
從父物件取得子列	子查詢
計數 / 彙總	彙總查詢
有 / 無相關列的記錄	semi-join / anti-join
跨物件文字搜尋	SOSL

3. 最佳化選擇性與安全性

檢查：

• 索引 / 選擇性篩選
• 無多餘欄位
• 無可避免的萬用字元或掃描密集型模式
• 安全性強制執行期望

4. 如有需要，驗證執行路徑

若使用者需要執行期驗證，請將執行交給：

• platform-data-manage

---

高訊號規則

• 絕不使用 SELECT * 的思維；僅查詢必要欄位
• 在 Apex 環境中，不要在迴圈內查詢
• 偏好於 SOQL 中篩選，而非在 Apex 中事後篩選
• 使用彙總進行計數與分組摘要，而非載入不必要的記錄
• 謹慎評估萬用字元的使用；前置萬用字元通常會破壞索引
• 當查詢移入 Apex 時，需考量安全模式 / 欄位存取需求

---

輸出格式

完成時，依序報告：

1. 查詢目的
2. 最終 SOQL/SOSL
3. 為何選擇此形狀
4. 最佳化或安全性注意事項
5. 執行建議（如有需要）

建議格式 — 確切語法請參閱 references/soql-syntax-reference.md：

查詢目標：<摘要>
查詢：<soql 或 sosl>
設計：<關係 / 彙總 / 篩選選擇>
注意事項：<選擇性、限制、安全性、governor 感知>
下一步：<在 platform-data-manage 中執行或嵌入 Apex>

---

跨技能整合

需求	委派給	原因
對 org 執行查詢	platform-data-manage	執行與匯出
在服務/選擇器中嵌入查詢	platform-apex-generate	實作情境
從日誌分析慢查詢症狀	platform-apex-logs-debug	執行期證據
將查詢支援的 UI 接線	experience-lwc-generate	前端整合

---

評分指南

分數	意義
90+	生產環境最佳化查詢
80–89	良好查詢，有輕微改善空間
70–79	功能正常，但仍有效能疑慮
< 70	需修訂後才能用於生產環境

---

參考檔案索引

檔案	何時閱讀
references/soql-syntax-reference.md	語法、運算子、日期字面值、關係查詢模式
references/query-optimization.md	選擇性規則、索引策略、governor 限制、安全模式
references/soql-reference.md	快速參考 — 運算子、日期函式、彙總函式、WITH 子句
references/anti-patterns.md	常見 SOQL 錯誤及其修正 — 定稿任何查詢前閱讀
references/selector-patterns.md	Apex selector 層模式 — 在 Apex 類別中嵌入查詢時閱讀
references/field-coverage-rules.md	欄位涵蓋驗證 — 在 Apex 程式碼內產生 SOQL 時閱讀
references/cli-commands.md	sf CLI 查詢執行、大量匯出、查詢計畫指令
assets/basic-queries.soql	常見物件的入門查詢範例
assets/relationship-queries.soql	父對子與子對父關係查詢模式
assets/aggregate-queries.soql	COUNT、SUM、GROUP BY、ROLLUP 查詢模式
assets/optimization-patterns.soql	選擇性篩選與索引感知查詢模式
assets/bulkified-query-pattern.cls	觸發器環境的 Apex Map 型大量查詢模式
assets/selector-class.cls	完整 selector 類別實作範本
scripts/post-tool-validate.py	寫入後掛鉤 — 在 .soql 檔案編輯後執行靜態 SOQL 驗證與即時查詢計畫分析