sf-datacloud-retrieve

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sf-datacloud-retrieve

Use this skill for the query and metadata plane.

Beast references:

Beast preflight: docs/beast-preflight.md
Phase proof matrix: docs/phase-proof-matrix.json
Public operating model: docs/operating-model.md
Interoperability decision map: docs/data360/interoperability-decision-map.md
RAG/search-index playbook: docs/data360/rag-search-index-retriever-playbook.md
Developer Guide index: docs/data360/developer/index.md
Companion MCP installs: docs/mcp-dependencies.md
Proof ledger: docs/proof-ledger.md
Public LLM map: docs/llms.txt
Limits source precedence: docs/data360/limits-source-precedence.md
For exact Salesforce behavior, fetch official Help/Developer docs on demand with
```
sf-docs
```
.
For endpoint shape, use OpenAPI from the official spec or the user-supplied Swagger before writing payloads.

本技能适用于查询与元数据层面。

Beast参考资料：

Beast预检查：docs/beast-preflight.md
阶段验证矩阵：docs/phase-proof-matrix.json
公开运营模型：docs/operating-model.md
互操作性决策图谱：docs/data360/interoperability-decision-map.md
RAG/搜索索引手册：docs/data360/rag-search-index-retriever-playbook.md
开发者指南索引：docs/data360/developer/index.md
配套MCP安装：docs/mcp-dependencies.md
验证台账：docs/proof-ledger.md
公开LLM图谱：docs/llms.txt
限制源优先级：docs/data360/limits-source-precedence.md
如需了解Salesforce精准行为，使用
```
sf-docs
```
按需获取官方帮助/开发者文档。
如需端点结构，在编写负载前使用官方规范中的OpenAPI或用户提供的Swagger。

Default surfaces

默认接口

Apex
```
ConnectApi.CdpQuery.queryAnsiSqlV2
```
```
POST /ssot/queryv2
```
```
POST /ssot/query-sql
```
```
GET /ssot/query-sql/:queryId
```
```
GET /ssot/query-sql/:queryId/rows
```
```
GET /ssot/metadata
```
```
GET /ssot/profile/metadata
```
```
GET /ssot/profile/:dataModelName
```
```
GET /ssot/insight/metadata
```
```
GET /ssot/insight/metadata/:ciName
```
Universal ID Lookup
Data Graph API retrieval
Data 360 MCP facade tools:
```
search
```
,
```
payload_examples
```
,
```
execute
```

Apex
```
ConnectApi.CdpQuery.queryAnsiSqlV2
```
```
POST /ssot/queryv2
```
```
POST /ssot/query-sql
```
```
GET /ssot/query-sql/:queryId
```
```
GET /ssot/query-sql/:queryId/rows
```
```
GET /ssot/metadata
```
```
GET /ssot/profile/metadata
```
```
GET /ssot/profile/:dataModelName
```
```
GET /ssot/insight/metadata
```
```
GET /ssot/insight/metadata/:ciName
```
通用ID查询
数据图谱API检索
Data 360 MCP facade工具：
```
search
```
、
```
payload_examples
```
、
```
execute
```

Rules

规则

For Calculated Insight SQL, use sf-datacloud-calculated-insights after metadata discovery.
Query Editor is the official UI surface for SQL exploration, data validation, query testing, and troubleshooting across DLOs, DMOs, CIOs, and data graphs.
Use Data Explorer to validate object data and formulas; use Profile Explorer to validate unified profile views.
Data 360 SQL is ANSI/PostgreSQL-like, not SOQL.
SOQL can query supported Data 360 profile, data source, or DMO objects through REST API query or Apex, but it is a narrower platform-integrated path. Use ANSI SQL / Query APIs for broad Data 360 querying unless the user specifically needs SOQL behavior.
Quote identifiers carefully when the surface requires it.
Use
```
IS NOT NULL
```
for null checks.
Use metadata/profile discovery before inventing table or field names.
For RAG troubleshooting, search indexes produce chunk and index DMOs. Probe them directly with small
```
SELECT ... LIMIT 10
```
queries and compare chunk/index counts with source DMO counts before blaming prompts.
For pro-code RAG, use Data 360 SQL
```
vector_search
```
or
```
hybrid_search
```
through Query SQL or Apex
```
ConnectApi.CdpQuery
```
when no-code retrievers cannot express nested filters, unsupported operators, post-filters, majority-vote classification, custom joins, or record access checks.
Prefer query-sql or
```
ConnectApi.CdpQuery
```
when you need robust pagination or large result handling.
Use Data 360 API / Direct API for high-performance tenant-side read paths when available.
Treat query jobs as asynchronous: submit, poll, page rows, and handle status codes.
For query performance, reason from the object layer first: DLO, DMO, CIO, or data graph. Selective predicates, date filters, projected fields, join grain, and row counts often matter more than cosmetic SQL changes.
Prefer filtered queries with explicit field lists over broad record retrieval; query cost and credits are part of the design, not just an admin afterthought.
Treat Trino-like or Iceberg-style query behavior as an inferred mental model only. Use it to choose proof steps such as metadata checks, smaller probes, count queries, and predicate selectivity tests.
For zero-copy work, distinguish live query, accelerated query, and file federation. Live query is freshness-first and source-compute-dependent; accelerated query trades freshness for repeated-read performance; file federation is read-only and depends on object format, partitioning, pruning, and region/I/O.
Push predicates and aggregations to the source when using query federation. Avoid unfiltered scans over massive federated datasets.
Prefer profile endpoints when you need record-centric retrieval instead of ad hoc SQL.
Use metadata retrieval before exposing objects to agents or semantic models.
Governed queries can omit fields from
```
SELECT *
```
; explicit inaccessible fields should fail.
View All/Modify All can expose metadata in some UI paths, but query policy enforcement still applies.
Dynamic masking is applied at retrieval time; do not use masked values as join/filter truth.
For data spaces, check token exchange, SQL connector/Python connector
```
dataspace
```
, or ConnectApi extra parameter handling before blaming query syntax.

对于Calculated Insight SQL，在元数据发现后使用sf-datacloud-calculated-insights。
Query Editor是用于SQL探索、数据验证、查询测试以及跨DLO、DMO、CIO和数据图谱故障排查的官方UI界面。
使用Data Explorer验证对象数据和公式；使用Profile Explorer验证统一档案视图。
Data 360 SQL类ANSI/PostgreSQL，而非SOQL。
SOQL可通过REST API查询或Apex查询受支持的Data 360档案、数据源或DMO对象，但这是一条更窄的平台集成路径。除非用户明确需要SOQL行为，否则使用ANSI SQL/查询API进行广泛的Data 360查询。
当界面要求时，谨慎引用标识符。
使用
```
IS NOT NULL
```
进行空值检查。
在自定义表或字段名称前，先进行元数据/档案发现。
对于RAG故障排查，搜索索引会生成块和索引DMO。直接使用小型
```
SELECT ... LIMIT 10
```
查询探查它们，并在质疑提示前比较块/索引计数与源DMO计数。
对于编码式RAG，当无代码检索器无法表达嵌套过滤器、不支持的运算符、后置过滤器、多数投票分类、自定义连接或记录访问检查时，通过Query SQL或Apex
```
ConnectApi.CdpQuery
```
使用Data 360 SQL的
```
vector_search
```
或
```
hybrid_search
```
。
当需要强大的分页或处理大型结果时，优先使用query-sql或
```
ConnectApi.CdpQuery
```
。
当可用时，使用Data 360 API/Direct API实现高性能租户端读取路径。
将查询作业视为异步操作：提交、轮询、分页获取行数据并处理状态码。
对于查询性能，首先从对象层分析：DLO、DMO、CIO或数据图谱。选择性谓词、日期过滤器、投影字段、连接粒度和行数通常比SQL的表面修改更重要。
优先使用带显式字段列表的过滤查询，而非广泛的记录检索；查询成本和积分是设计的一部分，而非事后的管理考量。
仅将类Trino或Iceberg风格的查询行为视为推断的思维模型。用它选择验证步骤，如元数据检查、小型探查、计数查询和谓词选择性测试。
对于零拷贝工作，区分实时查询、加速查询和文件联邦。实时查询优先保证新鲜度，依赖源计算；加速查询以新鲜度换取重复读取性能；文件联邦为只读模式，依赖对象格式、分区、修剪以及区域/I/O。
使用查询联邦时，将谓词和聚合推送到源端。避免对大规模联邦数据集进行无过滤扫描。
当需要以记录为中心的检索而非临时SQL时，优先使用档案端点。
在向Agent或语义模型暴露对象前，先进行元数据检索。
受控查询可从
```
SELECT *
```
中省略字段；显式不可访问的字段应返回失败。
View All/Modify All可能在某些UI路径中暴露元数据，但查询策略仍会强制执行。
动态掩码在检索时应用；不要使用掩码值作为连接/过滤的依据。
对于数据空间，在质疑查询语法前，先检查令牌交换、SQL连接器/Python连接器
```
dataspace
```
或ConnectApi额外参数的处理方式。

Query MCP

When a local query tool helps, prefer the official Data 360 MCP server configured from docs/mcp-dependencies.md. Use any legacy local query MCP only if it is already present in the user's workspace and the user authorizes live org access.

当本地查询工具有用时，优先使用从docs/mcp-dependencies.md配置的官方Data 360 MCP服务器。仅当用户工作区中已存在旧版本地查询MCP且用户授权实时组织访问时，才使用该旧版工具。

Hard-won rules

经验规则

Query success does not prove segment SQL will compile.
CI tables are fine for discovery queries and proposal logic.
DBT segment creation is stricter than the query plane.
Analytics, segments, transforms, and activations can consume the same logical data through different serving or processing paths; validate the target surface directly.
Profile, metadata, calculated insight, and data graph retrieval all have different response shapes; do not normalize them casually.
When a query differs from a segment, graph, report, or transform result, check governance enforcement differences before assuming data drift.

查询成功不代表细分SQL可以编译。
CI表适用于发现查询和提案逻辑。
DBT细分创建比查询层面更严格。
分析、细分、转换和激活可通过不同的服务或处理路径使用相同的逻辑数据；直接验证目标界面。
档案、元数据、Calculated Insight和数据图谱检索的响应结构各不相同；不要随意标准化它们。
当查询结果与细分、图谱、报告或转换结果不同时，在假设数据漂移前先检查治理执行差异。

Doc-Synced Notes

文档同步说明

Data Spaces in Query Tooling

查询工具中的数据空间

Auto-synced from the local sf-docs cached Salesforce Help export (official docs only).

Sources (sf-docs cached Help):

data.c360_a_using_data_cloud_apis_with_data_spaces.htm — Use Data Cloud APIs with Data Spaces

Source fingerprint:

914b475541498c62cea77808

Notes:

If results differ by user or environment, confirm whether the query path is scoped by a data space (token exchange, connector property, or API extra parameter).
Treat data space selection as part of proof: include the data space in readbacks and troubleshooting probes.

从本地sf-docs缓存的Salesforce帮助导出自动同步（仅官方文档）。

来源（sf-docs缓存帮助）：

data.c360_a_using_data_cloud_apis_with_data_spaces.htm — 将Data Cloud API与数据空间配合使用

来源指纹：

914b475541498c62cea77808

说明：

如果结果因用户或环境而异，确认查询路径是否受数据空间限制（令牌交换、连接器属性或API额外参数）。
将数据空间选择视为验证的一部分：在反馈和故障排查探查中包含数据空间信息。

Explore and Query Tooling (Data Explorer, Profile Explorer, Query Editor)

探索与查询工具（Data Explorer、Profile Explorer、Query Editor）

Distilled from official Salesforce sources only.

Sources:

data.c360_a_data_explorer.htm — Data Explorer
data.c360_a_profile_explorer.htm — Profile Explorer
data.c360_a_query_editor.htm — Query Editor
developer.salesforce.com/docs/data/data-cloud-query-guide/guide/dc-query-section.html — Get Started With Data 360 SQL
developer.salesforce.com/docs/data/data-cloud-query-guide/guide/int-apps-data-cloud.html — Data 360 Integrated Apps
developer.salesforce.com/docs/data/data-cloud-query-guide/guide/write-simple-query.html — Write a Simple Query

Three query/exploration surfaces — pick the right one:

Tool	Best for	Output
Data Explorer	Browse DLO/DMO records, inspect schema, filter rows without writing SQL	UI grid, downloadable CSV
Profile Explorer	Inspect a specific Unified Individual: contact points, engagement, related DMOs, calculated insights	Per-profile JSON-like view
Query Editor	Write SQL across DLOs and DMOs, save queries, share workspaces	Tabular results, save/share

Data Explorer workflow:

Data Explorer tab → select Data Lake or Data Model.
Choose object → see record count and schema.
Browse records (paginated) → apply filters via UI controls.
Download a CSV slice for offline inspection.
Use this as a first-pass before writing SQL — confirm record counts and field shapes before designing CIs/segments.

Profile Explorer workflow:

Profile Explorer tab → search for an individual by name, email, or profile ID.
Inspect the unified profile and all linked source profiles.
View related contact points, engagement events, calculated insights.
Trace identity resolution decisions (which records merged, which reconciliation rules fired).
Use this to debug identity resolution issues and to confirm that activation contact-point selection is what the user expects.

Query Editor workflow:

Query Editor tab → select or create a Workspace.
Workspace defines the DMOs/DLOs accessible to your queries (data space scoped).
Write SQL:
```
SELECT … FROM <DMO/DLO> WHERE …
```
.
Click Run; inspect tabular results.
Click Save to persist the query.
Share the workspace with collaborators (subject to permissions).

Data 360 SQL essentials:

Use
```
SELECT *
```
for exploration; explicit field lists for production queries (FLS-aware).
Filters via
```
WHERE
```
clause:
```
BETWEEN
```
,
```
LIKE
```
, comparison operators, combined with
```
AND
```
/
```
OR
```
.
Aggregations:
```
COUNT
```
,
```
SUM
```
,
```
AVG
```
,
```
MIN
```
,
```
MAX
```
,
```
STDDEV
```
,
```
CORR
```
.
Joins: inner, left outer, right outer, full outer.
Join records on both
```
ssot__Id__c
```
and
```
KQ_Id__c
```
(key qualifier) for accurate matches — fully qualified key uniqueness.
```
GROUP BY
```
for aggregations;
```
ORDER BY
```
for sorting;
```
LIMIT
```
for pagination.

Integrated apps for query/visualization:

Tableau (native via Tableau Semantics).
DBeaver (JDBC connection).
Custom apps via Connect API and Query API.

Pitfalls:

A query that succeeds in Query Editor may not compile as a segment SQL (DBT segment compiler is stricter). Validate at the segment plane.
Profile Explorer may show data the running user cannot see in segments due to RLS/masking differences — use Profile Explorer as admin-debug tool, not as governance proof.
Workspace selection scopes the result; switching workspace can change query results.
Cached query results may not reflect very recent ingestion — refresh the workspace if results look stale.

仅提炼自Salesforce官方来源。

来源：

data.c360_a_data_explorer.htm — Data Explorer
data.c360_a_profile_explorer.htm — Profile Explorer
data.c360_a_query_editor.htm — Query Editor
developer.salesforce.com/docs/data/data-cloud-query-guide/guide/dc-query-section.html — 开始使用Data 360 SQL
developer.salesforce.com/docs/data/data-cloud-query-guide/guide/int-apps-data-cloud.html — Data 360集成应用
developer.salesforce.com/docs/data/data-cloud-query-guide/guide/write-simple-query.html — 编写简单查询

三种查询/探索界面——选择合适的工具：

工具	最佳用途	输出
Data Explorer	浏览DLO/DMO记录、检查 schema、无需编写SQL即可过滤行数据	UI表格、可下载CSV
Profile Explorer	检查特定统一个体：联系点、互动、相关DMO、Calculated Insight	单档案类JSON视图
Query Editor	跨DLO和DMO编写SQL、保存查询、共享工作区	表格结果、保存/共享

Data Explorer工作流：

进入Data Explorer标签页 → 选择数据湖或数据模型。
选择对象 → 查看记录数和schema。
浏览记录（分页）→ 通过UI控件应用过滤器。
下载CSV切片以便离线检查。
在编写SQL前先用此工具进行初步检查——在设计CI/细分前确认记录数和字段结构。

Profile Explorer工作流：

进入Profile Explorer标签页 → 通过姓名、邮箱或档案ID搜索个体。
检查统一档案和所有关联的源档案。
查看相关联系点、互动事件、Calculated Insight。
追踪身份解析决策（哪些记录已合并、哪些协调规则已触发）。
使用此工具调试身份解析问题，并确认激活联系点选择符合用户预期。

Query Editor工作流：

进入Query Editor标签页 → 选择或创建工作区。
工作区定义了查询可访问的DMO/DLO（受数据空间限制）。
编写SQL：
```
SELECT … FROM <DMO/DLO> WHERE …
```
。
点击运行；检查表格结果。
点击保存以持久化查询。
与协作者共享工作区（受权限限制）。

Data 360 SQL要点：

探索时使用
```
SELECT *
```
；生产查询使用显式字段列表（支持FLS）。
通过
```
WHERE
```
子句过滤：
```
BETWEEN
```
、
```
LIKE
```
、比较运算符，结合
```
AND
```
/
```
OR
```
使用。
聚合函数：
```
COUNT
```
、
```
SUM
```
、
```
AVG
```
、
```
MIN
```
、
```
MAX
```
、
```
STDDEV
```
、
```
CORR
```
。
连接类型：内连接、左外连接、右外连接、全外连接。
基于
```
ssot__Id__c
```
和
```
KQ_Id__c
```
（键限定符）连接记录以确保匹配准确——完全限定键的唯一性。
聚合使用
```
GROUP BY
```
；排序使用
```
ORDER BY
```
；分页使用
```
LIMIT
```
。

用于查询/可视化的集成应用：

Tableau（原生支持Tableau语义）。
DBeaver（JDBC连接）。
通过Connect API和Query API构建的自定义应用。

注意事项：

在Query Editor中成功运行的查询可能无法作为细分SQL编译（DBT细分编译器更严格）。需在细分层面验证。
由于RLS/掩码差异，Profile Explorer可能显示运行用户在细分中无法查看的数据——将Profile Explorer用作管理员调试工具，而非治理验证工具。
工作区选择会限制结果；切换工作区可能改变查询结果。
缓存的查询结果可能无法反映最新的 ingestion——如果结果看起来过时，请刷新工作区。

Query surface selection gate

查询界面选择指南

Auto-synced from sf-docs captures of official Salesforce Developer documentation.

Sources:

https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/query-guide-get-started.html - Query Data in Data 360 | Data 360 Query Guide | Salesforce Developers
https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/obj-specific-apis.html - Object Specific APIs | Query Data in Data 360 | Data 360 Query Guide | Salesforce Developers
https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/dc-sql-query-apis.html - Data 360 SQL Query APIs | Query Data in Data 360 | Data 360 Query Guide | Salesforce Developers
https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/dc-apex-query.html - Query Data 360 Data with Apex | Query Data in Data 360 | Data 360 Query Guide | Salesforce Developers
https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/dc-soql.html - SOQL With Apex | Query Data in Data 360 | Data 360 Query Guide | Salesforce Developers

Source fingerprint:

f5688f5a26555828fd52169a

Implementation notes:

Prefer an object-specific API when it covers the target object and workflow; use custom Data 360 SQL when joins, aggregation, or unsupported objects require it.
Use asynchronous query and polling patterns for large Apex workloads, and start with limited data to protect governor limits and validate semantics.
Treat SOQL as a constrained Platform query path: no
```
SELECT *
```
, and Data 360 SOQL does not currently provide the relationship behavior needed to replace SQL joins.
Calculated insights and data transforms use SQL contracts that differ from the Query Guide; validate in the owning phase rather than reusing Query SQL unchanged.

从sf-docs捕获的Salesforce官方开发者文档自动同步。

来源：

https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/query-guide-get-started.html - 在Data 360中查询数据 | Data 360查询指南 | Salesforce开发者
https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/obj-specific-apis.html - 对象特定API | 在Data 360中查询数据 | Data 360查询指南 | Salesforce开发者
https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/dc-sql-query-apis.html - Data 360 SQL查询API | 在Data 360中查询数据 | Data 360查询指南 | Salesforce开发者
https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/dc-apex-query.html - 使用Apex查询Data 360数据 | 在Data 360中查询数据 | Data 360查询指南 | Salesforce开发者
https://developer.salesforce.com/docs/data/data-cloud-query-guide/guide/dc-soql.html - 结合Apex使用SOQL | 在Data 360中查询数据 | Data 360查询指南 | Salesforce开发者

来源指纹：

f5688f5a26555828fd52169a

实现说明：

当对象特定API覆盖目标对象和工作流时优先使用；当需要连接、聚合或不支持的对象时，使用自定义Data 360 SQL。
对于大型Apex工作负载，使用异步查询和轮询模式，并从有限数据开始，以保护 governor limits 并验证语义。
将SOQL视为受限的平台查询路径：不支持
```
SELECT *
```
，且Data 360 SOQL目前无法提供替代SQL连接所需的关系行为。
Calculated Insight和数据转换使用与查询指南不同的SQL约定；需在所属阶段验证，而非直接复用查询SQL。