Back to Details

sf-datacloud-retrieve

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

sf-datacloud-retrieve: Data Cloud Retrieve Phase

sf-datacloud-retrieve: Data Cloud 检索阶段

Use this skill when the user needs query, search, and metadata introspection for Data Cloud: sync SQL, paginated SQL, async query workflows, table describe, vector search, hybrid search, or search index operations.
当用户需要对Data Cloud执行查询、搜索和元数据自省操作时，可使用此Skill：同步SQL、分页SQL、异步查询工作流、表describe操作、向量搜索、混合搜索或搜索索引操作。

When This Skill Owns the Task

此Skill的适用场景

Use 
sf-datacloud-retrieve
when the work involves:
  • sf data360 query *
  • sf data360 search-index *
  • sf data360 metadata *
  • sf data360 profile *
    or 
    sf data360 insight *
    inspection
  • understanding Data Cloud SQL results or query shape
Delegate elsewhere when the user is:
  • writing standard CRM SOQL only → sf-soql
  • designing segment or calculated insight assets → sf-datacloud-segment
  • analyzing STDM/session tracing/parquet telemetry → sf-ai-agentforce-observability
当工作涉及以下操作时，请使用
sf-datacloud-retrieve
：
  • sf data360 query *
  • sf data360 search-index *
  • sf data360 metadata *
  • sf data360 profile *
    或 
    sf data360 insight *
    检查
  • 理解Data Cloud SQL结果或查询结构
当用户进行以下操作时，请转用其他Skill：
  • 仅编写标准CRM SOQL → sf-soql
  • 设计细分受众群或计算洞察资产 → sf-datacloud-segment
  • 分析STDM/会话追踪/Parquet遥测数据 → sf-ai-agentforce-observability

Required Context to Gather First

需优先收集的上下文信息

Ask for or infer:
  • target org alias
  • whether the user needs quick count, medium result set, large export, schema inspection, or semantic search
  • table/index name if known
  • whether the task is read-only SQL or search-index lifecycle management
询问或推断：
  • 目标组织别名
  • 用户是否需要快速计数、中等规模结果集、大规模导出、架构检查或语义搜索
  • 已知的表/索引名称
  • 任务为只读SQL还是搜索索引生命周期管理

Core Operating Rules

核心操作规则

  • Treat Data Cloud SQL as its own query language, not SOQL.
  • Run the shared readiness classifier before relying on query/search surfaces: 
    node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --json
    .
  • Use describe before guessing columns.
  • Prefer 
    sqlv2
    or async query flows for larger result sets.
  • Use vector search or hybrid search only when the search index lifecycle is healthy.
  • Keep STDM/parquet/session-tracing workflows out of this skill family.
  • 将Data Cloud SQL视为独立的查询语言，而非SOQL。
  • 在依赖查询/搜索界面之前，运行共享就绪性分类器：
    node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --json
    。
  • 在猜测列之前先使用describe操作。
  • 对于较大的结果集，优先使用
    sqlv2
    或异步查询流程。
  • 仅当搜索索引生命周期健康时，才使用向量搜索或混合搜索。
  • 请勿在本Skill中处理STDM/Parquet/会话追踪工作流。

Recommended Workflow

推荐工作流

1. Classify readiness for retrieve work

1. 分类检索工作的就绪状态

bash
node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --json
bash
node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --json

optional query-plane probe, only with a real table name

可选的查询平面探测，仅在有真实表名时使用

node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
undefined
node ~/.claude/skills/sf-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
undefined

2. Choose the smallest correct query shape

2. 选择最小且正确的查询结构

bash
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
bash
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. Use describe before guessing fields

3. 在猜测字段之前先使用describe操作

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

4. Use vector or hybrid search only when an index exists

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

bash
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
bash
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. Reuse curated search-index examples when creating indexes

5. 创建索引时复用精选的搜索索引示例

Use the phase-owned examples instead of inventing JSON from scratch:
  • examples/search-indexes/vector-knowledge.json
  • examples/search-indexes/hybrid-structured.json
使用本阶段专属的示例，而非从头编写JSON：
  • examples/search-indexes/vector-knowledge.json
  • examples/search-indexes/hybrid-structured.json

High-Signal Gotchas

高信号注意事项

  • Data Cloud SQL is not SOQL.
  • Table names should be double-quoted in SQL.
  • sqlv2
    is better than ad hoc OFFSET paging for medium result sets.
  • async query is preferable for large results.
  • search-index operations and vector/hybrid queries depend on the index lifecycle being healthy.
  • Hybrid search can use 
    --prefilter
    , but only on fields configured as prefilter-capable when the search index was created.
  • HNSW index parameters are typically read-only on create; leave 
    userValues: []
    unless the platform explicitly documents otherwise.
  • query describe
    is not a universal tenant probe; only run it with a known DMO or DLO table after broader readiness has been confirmed.
  • Data Cloud SQL 不是 SOQL。
  • SQL中的表名需要用双引号包裹。
  • 对于中等规模的结果集，
    sqlv2
    比临时OFFSET分页更优。
  • 对于大规模结果，异步查询是更优选择。
  • 搜索索引操作和向量/混合查询依赖于健康的索引生命周期。
  • 混合搜索可使用
    --prefilter
    ，但仅适用于创建搜索索引时配置为支持预过滤的字段。
  • HNSW索引参数通常在创建后为只读；除非平台有明确文档说明，否则请保留
    userValues: []
    。
  • query describe
    不是通用的租户探测工具；仅在确认整体就绪性后，对已知的DMO或DLO表运行该操作。

Output Format

输出格式

text
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>
text
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>

References

参考资料

  • 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
  • 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