Back to Details

data360-query

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

data360-query: Data Cloud Retrieve Phase

data360-query: 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 
data360-query
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 → platform-soql-query
  • designing segment or calculated insight assets → data360-segment
  • analyzing STDM/session tracing/parquet telemetry → agentforce-observe
当工作涉及以下内容时，使用
data360-query
：
  • sf data360 query *
  • sf data360 search-index *
  • sf data360 metadata *
  • sf data360 profile *
    或 
    sf data360 insight *
    检查
  • 理解Data Cloud SQL结果或查询结构
当用户进行以下操作时，请转交至其他skill：
  • 仅编写标准CRM SOQL → platform-soql-query
  • 设计细分或计算洞察资产 → data360-segment
  • 分析STDM/会话追踪/parquet遥测数据 → agentforce-observe

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 ../data360-orchestrate/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 ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase retrieve --json
    。
  • 在猜测列之前先使用describe。
  • 对于较大的结果集，优先使用
    sqlv2
    或异步查询流程。
  • 仅当搜索索引生命周期健康时，才使用向量搜索或混合搜索。
  • 请勿将STDM/parquet/会话追踪工作流纳入此skill范畴。

Recommended Workflow

推荐工作流

1. Classify readiness for retrieve work

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

bash
node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase retrieve --json
bash
node ../data360-orchestrate/scripts/diagnose-org.mjs -o <org> --phase retrieve --json

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

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
undefined
node ../data360-orchestrate/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
  • ../data360-orchestrate/assets/definitions/search-index.template.json
  • ../data360-orchestrate/references/plugin-setup.md
  • ../data360-orchestrate/references/feature-readiness.md
  • README.md
  • 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