sf-datacloud-retrieve：Data Cloud Retrieve 阶段
用途
当用户需要对 Data Cloud 进行查询、搜索和元数据内省时使用本技能，包括：同步 SQL、分页 SQL、异步查询流程、表 describe、向量搜索、混合搜索或搜索索引操作。
该技能负责的任务范围包括：
- sf data360 query *
- sf data360 search-index *
- sf data360 metadata *
- sf data360 profile * 或 sf data360 insight * 的检查
- 理解 Data Cloud SQL 结果或查询形态
当用户仅编写标准 CRM SOQL 时，应交给 sf-soql；设计 segment 或 calculated insight 资产时交给 sf-datacloud-segment；分析 STDM/会话追踪/parquet 遥测时交给 sf-ai-agentforce-observability。
需要先收集的上下文
需要询问或推断：
- 目标 org 别名
- 用户需要的是快速计数、中等结果集、大规模导出、模式检查还是语义搜索
- 已知的表或索引名称
- 任务是只读 SQL 还是搜索索引生命周期管理
核心操作规则
- 将 Data Cloud SQL 视为其自身的查询语言，而非 SOQL。
- 在依赖查询/搜索面之前，先运行共享就绪分类器：node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --json。
- 先使用 describe，再猜测列。
- 较大的结果集优先使用 sqlv2 或异步查询流程。
- 仅当搜索索引生命周期健康时使用向量搜索或混合搜索。
- 将 STDM/parquet/会话追踪工作流排除在本技能家族之外。
推荐工作流
- 为 retrieve 工作分类就绪状态
node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --json
可选的查询平面探测，仅在已知真实表名时使用
node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
- 选择最小的正确查询形态
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
- 在猜测字段前使用 describe
sf data360 query describe -o <org> --table ssot__Individual__dlm 2>/dev/null
- 仅当索引存在时使用向量或混合搜索
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
- 创建索引时复用精选的搜索索引示例
使用该阶段自带的示例，而不是凭空编写 JSON：
- examples/search-indexes/vector-knowledge.json
- examples/search-indexes/hybrid-structured.json
重要注意事项
- Data Cloud SQL 不是 SOQL。
- 表名在 SQL 中应使用双引号。
- 对于中等结果集，sqlv2 优于临时的 OFFSET 分页。
- 对于大结果，异步查询更可取。
- search-index 操作与向量/混合查询依赖索引生命周期健康。
- 混合搜索可以使用 --prefilter，但仅能用于创建搜索索引时配置为支持 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>
参考资料
- README.md
- examples/search-indexes/vector-knowledge.json
- examples/search-indexes/hybrid-structured.json
- ../sf-datacloud/assets/definitions/search-index.template.json
- ../sf-datacloud/references/plugin-setup.md
- ../sf-datacloud/references/feature-readiness.md