Salesforce：查询对象

说明

通过 Salesforce 的 Bulk API 2.0，将一个 Salesforce 对象（标准或自定义）读取到项目表中。选择 Salesforce 连接、对象和字段，步骤会构建查询、分页读取整个结果集，并将每一列按 Salesforce 声明的类型落入。无需编写查询。

Salesforce 通过其 REST API 以云直连方式访问，因此此步骤不需要 PlaidLink 代理。

配置

字段	必填	备注
Salesforce 连接	是	用于读取数据的 Salesforce 连接。连接在 Tools > Connections 中管理。
环境	否	读取该连接的哪个环境：将沙盒环境指向沙盒组织，将生产环境指向生产组织。默认为该连接的 `default` 环境。
对象	是	对象的 API 名称，如 `Account`、`Opportunity`、`Invoice__c`。选择器会列出该连接的 Run As 用户可以查询的对象，也接受手动输入的名称，因此在无法进行对象发现时，已保存的步骤仍可继续工作。
目标表	是	行落入的项目表。
包含已删除和已归档的记录	否	同时读取回收站中的记录和已归档的活动，与 Salesforce 的 `queryAll` 一致。
字段	是	勾选要提取的字段。至少需要一个：Bulk API 2.0 会拒绝对整个对象的选择，因此列列表始终需要逐一列出。
筛选器	否	在 Salesforce 端缩小提取范围。请参阅在 Salesforce 端筛选。
窗口标记	否	为提取窗口命名。请参阅提取窗口只运行一次。

无论是否勾选，Id 始终会被包含，它是每次重新运行时合并所依据的键。如果对象带有 CurrencyIsoCode，货币字段也会一并拉取该列。

行如何落入

每次运行都会在您的筛选条件下完整读取对象，并按 Id 将每一页合并到目标表。表中已有的行会被就地替换，因此中断后恢复的运行不会重复落入任何内容。

落入的列使用 Salesforce 在其自身字段元数据中声明的类型，绝不会根据第一页数据猜测类型。字段选择器中的落入列就是该声明的类型，因此您在表单中确认的结构就是表最终得到的结构。

各类型落入为何种类型

Salesforce 字段类型	落入为
`id`、`reference`、`string`、`textarea`、`phone`、`url`、`email`、`picklist`、`multipicklist`、`combobox`	文本
`boolean`	布尔值
`date`	日期
`datetime`	时间戳
`time`	时间
`int`	整数；如果字段声明了 10 位或更多位数，则为 64 位整数
`double`、`currency`、`percent`	数值：宽十进制数，38 位数字，其中 10 位小数

该表带来三个约定，在基于输出构建内容之前值得了解：

货币落入为数字，而不是货币类型。 实际的组织声明的货币字段小数位数有 0、2、3 和 4 位，因此所有数值类型都落入同一种足以容纳它们的十进制类型。列上没有货币符号，也没有每个字段的小数位数约束。如果对象带有 CurrencyIsoCode，该列会与货币字段一并带出，使金额保留其币种；单一货币的组织在对象上没有这个字段，也不会凭空生成。
百分比是 Salesforce 报告的整数值。20 表示 20%，而不是 0.2。导入过程中不做任何缩放。
空值落入为 NULL。 Bulk 结果无法区分真正的 null 与显式的空字符串，因此两者都落入为 NULL，每一列都是如此，包括文本列。如果某一列必须保留空字符串语义，则需要在 Salesforce 端使用公式字段。

步骤拒绝的字段

某些 Salesforce 字段类型无法如实落入，因此字段选择器会将其标记为不可用并说明原因，而不是让您保存一个在运行时失败的步骤。每次拒绝都会指明字段及其 Salesforce 类型。

Salesforce 字段类型	原因	替代做法
`address`、`location`（复合字段）	复合字段在 Bulk 查询中没有可直接读取的值。	勾选其组成字段：`BillingStreet`、`BillingCity`、`BillingState`、`BillingPostalCode`、`BillingCountry`，以及地理位置的纬度和经度。选择器会为您当前查看的字段指出其组成字段。
`base64`	文件和二进制内容从不以内联方式返回，需要单独的二进制下载，而此步骤不执行该操作。	读取记录的其他字段，并单独处理附件。
`encryptedstring`	当 Run As 用户缺少 View Encrypted Data 权限时，Salesforce 返回的是掩码值而不是错误，而且没有任何方法能区分掩码数据与真实数据。悄悄落入一整行星号比拒绝更糟糕。	请审慎决定这些数据是否应该离开 Salesforce；通过此步骤提取它们没有受支持的方式。
`anyType`	实际类型可能逐行不同，而表的一列只有一种类型。	提取带类型的字段，或将值呈现为文本的公式字段。
步骤无法识别的任何类型	会被拒绝，而不是落入为文本，因为那样会悄悄改变值的含义。	请联系支持团队，为该类型添加映射。

提取窗口只运行一次

窗口标记为一次运行所加载的数据窗口命名，例如期间或批次标签，如 2026-09。它支持工作流变量：标记 {period} 会在每次步骤运行时解析为该变量的值。

提取窗口只运行一次。重新运行已经完成的窗口，不会再次访问 Salesforce：步骤会明确报告它没有重新读取，并说明所显示的行数属于之前的运行。这是明确提示的空操作，而不是静默的空操作，也正是它避免了重新运行再次分页获取已经落入的结果集的副本。

使用该步骤有三种方式：

将标记留空，把步骤当作一次性加载。第一次运行会读取；同一步骤的第二次运行会重放并报告它没有重新读取。可用它来构建和验证提取，以及用于只加载一次的表。
输入标记，并在加载下一个窗口时更改它，例如 2026-09，然后是 2026-10。编辑标记会开启一个新窗口，因此由人工逐步推进的月度加载正好按字面意思工作。
根据工作流变量构建标记，用于无人值守的周期性拉取，例如 {period}，由工作流中较早的步骤设置为正在加载的期间。每次计划运行都会为自己的窗口命名，同一期间内的重新运行会恢复或重放该窗口，而不是开启另一个窗口。

REST API 或 MCP 调用方直接传入 extract_tag，并自行为每个窗口提供不同的值。

被中断的运行会恢复同一个窗口，因此只要该窗口可能仍需完成，就请保持标记不变。更改标记会开启新窗口并向 Salesforce 发出新的查询。每当您更改筛选器或字段时，也请更改标记：在已运行过的标记下编辑配置，会因冲突而被拒绝。

在 Salesforce 端筛选

请在 Salesforce 端缩小提取范围，而不是拉取整个对象之后再筛选。每个筛选项由字段、运算符和值组成，各项之间以 AND 组合。值可以使用工作流变量，如 {region}。

运算符	备注
`=`、`!=`、`<`、`<=`、`>`、`>=`	与输入的值进行比较。
`LIKE`	使用 `%` 作为通配符，例如 `Acme%`。
`IN`、`NOT IN`	提供以逗号分隔的值列表。

在构建查询之前，字段和运算符都会与您所选的字段进行核对，并且没有可编写的自由文本 WHERE 子句，因此筛选器无法越出提取的范围。请对您也已勾选的字段进行筛选；指定了提取未选择的字段的筛选器会被拒绝。

步骤不提供行数限制和排序。当查询带有其中任何一项时，Bulk API 2.0 会关闭其内部分块，这会使大型提取更慢，也更容易超时。对于过大或过慢的查询，Salesforce 自身的解决办法是使用有选择性的筛选条件。

数据量与变动率的适用性

这种形态（按计划完整读取对象）适合数据量中等、变动率中等的对象：账户、商机、销售线索、营销活动，以及规模相近的自定义对象。

对于高数据量、高变动率的对象，例如 Task、EmailMessage，或每天有数百万行变化的大型自定义对象，它并不合适。对这些对象每晚完整拉取，会消耗增量同步所不需要的挂钟时间和 API 容量。如果对象很大但只有一部分有价值，使用能限定提取范围的筛选器（日期范围、记录类型、所有者），即可使其重新成为中等数据量的拉取。

运行未能完成时

您看到的现象	发生了什么	处理方法
一条警告，指出作业在 15 分钟后仍在运行	步骤在前台等待 Salesforce 完成查询，这一等待有时间上限。后台不会有任何东西推进该作业。	重新运行步骤。它会在同一个 Salesforce 作业上继续等待，绝不会提交第二个作业。如果持续超出上限，请使用筛选条件缩小提取范围。
一条警告，指出该窗口已经完成且未重新读取	该窗口之前已经运行过。显示的行数是之前那次运行的。	使用不同的窗口标记运行提取，或推进用于构建标记的变量，请参阅提取窗口只运行一次。
一个错误，指出作业失败或已中止	失败的 Bulk 查询作业不会产生部分结果，也无法恢复。该窗口现已作废。	使用不同的窗口标记重新运行。重新运行同一窗口只会重放失败并且不提交任何内容，而在同一标记下编辑步骤配置会因冲突被拒绝。
一次拒绝，指出 Salesforce 的请求限制	该组织滚动 24 小时的 API 请求额度已用尽。Salesforce 没有为此提供重试等待时间的说明。	等待该窗口清除后再重新运行，提取仍可恢复，没有任何内容丢失。
一次拒绝，指出某个字段及其 Salesforce 类型	该字段类型无法落入，或 Run As 用户无法读取该字段。	请参阅步骤拒绝的字段以及 Run As 用户的字段级安全。

Salesforce 会将已完成查询作业的结果保留 7 天以供检索，这正是被中断的提取得以恢复的原因，也限定了恢复在结果消失之前最多可以等待多久。作业可在 Salesforce 的 Setup > Environments > Jobs > Bulk Data Load Jobs 下查看。