data360-query

data360-query：Data Cloud 检索阶段

当用户需要对 Data Cloud 执行查询、搜索和元数据检查时，使用此技能：同步 SQL、分页 SQL、异步查询工作流、表描述、向量搜索、混合搜索或搜索索引操作。

此技能负责的任务

以下工作使用 data360-query：

• sf data360 query *
• sf data360 search-index *
• sf data360 metadata *
• 检查 sf data360 profile * 或 sf data360 insight *
• 理解 Data Cloud SQL 结果或查询形式

以下情况应委派给其他技能：

• 仅编写标准 CRM SOQL → platform-soql-query
• 设计细分或计算洞察资产 → data360-segment
• 分析 STDM／会话跟踪／parquet 遥测数据 → agentforce-observe

---

首先收集所需上下文

询问或推断：

• 目标组织别名
• 用户需要的是快速计数、中等结果集、大规模导出、架构检查还是语义搜索
• 已知的表／索引名称
• 任务是只读 SQL，还是搜索索引生命周期管理

---

核心操作规则

• 将 Data Cloud SQL 视为独立的查询语言，而不是 SOQL。
• 在依赖查询／搜索功能之前，运行共享就绪状态分类器：node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase retrieve --json。
• 先使用 describe，再推测列。
• 对较大的结果集，优先使用 sqlv2 或异步查询流程。
• 仅当搜索索引生命周期状态正常时，才使用向量搜索或混合搜索。
• STDM／parquet／会话跟踪工作不属于此技能系列。

---

推荐工作流

1. 对检索任务的就绪状态进行分类

node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase retrieve --json
# optional query-plane probe, only with a real table name
node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json

2. 选择满足需求的最小查询形式

sf data360 query sql -o <org> --sql 'SELECT COUNT(*) FROM "ssot__Individual__dlm"' 2>/dev/null
sf data360 query sqlv2 -o <org> --sql 'SELECT * FROM "ssot__Individual__dlm"' 2>/dev/null
sf data360 query async-create -o <org> --sql 'SELECT * FROM "ssot__Individual__dlm"' 2>/dev/null

3. 先使用 describe，再推测字段

sf data360 query describe -o <org> --table ssot__Individual__dlm 2>/dev/null

4. 仅当索引存在时使用向量或混合搜索

sf data360 search-index list -o <org> 2>/dev/null
sf data360 query vector -o <org> --index Knowledge_Index --query "reset password" --limit 5 2>/dev/null
sf data360 query hybrid -o <org> --index Knowledge_Index --query "reset password" --limit 5 2>/dev/null
sf data360 query hybrid -o <org> --index Insurance_Index --query "weather damage coverage" --prefilter "Type_of_Insurance__c='Home'" --limit 10 2>/dev/null

5. 创建索引时复用经过整理的搜索索引示例

使用由此阶段管理的示例，不要从头编写 JSON：

• examples/search-indexes/vector-knowledge.json
• examples/search-indexes/hybrid-structured.json

---

重要注意事项

• Data Cloud SQL 不是 SOQL。
• 在 SQL 中，表名应使用双引号括起来。
• 对中等结果集，sqlv2 比临时使用 OFFSET 分页更合适。
• 对大型结果集，优先使用异步查询。
• 搜索索引操作和向量／混合查询依赖于正常的索引生命周期状态。
• 混合搜索可以使用 --prefilter，但只能用于创建搜索索引时配置为支持预筛选的字段。
• HNSW 索引参数通常在创建时为只读；除非平台明确说明其他用法，否则请保留 userValues: []。
• query describe 不是通用的租户探测工具；只有在更广泛的就绪状态得到确认后，才对已知的 DMO 或 DLO 表运行它。

---

输出格式

Retrieve task: <sql / sqlv2 / async / describe / vector / search-index>
Target org: <alias>
Target object: <table or index>
Commands: <key commands run>
Verification: <query rows / schema / status>
Next step: <segment / harmonize / follow-up>

---

参考资料

• examples/search-indexes/vector-knowledge.json
• examples/search-indexes/hybrid-structured.json
• ../data360-orchestrate/assets/definitions/search-index.template.json
• ../data360-orchestrate/references/plugin-setup.md
• ../data360-orchestrate/references/feature-readiness.md