编写 SOSL 查询

学习目标

完成本单元后，您将能够：

描述 SOSL 和 SOQL 之间的差异。
使用 SOSL 查询跨多个对象搜索字段。
使用 Developer Console 中的查询编辑器执行 SOSL 查询。

备注

用中文（简体）学习？在此徽章中，Trailhead 实践挑战验证使用英文。括号中提供了译文，用作参考。在您的 Trailhead playground 中，您需确保 (1) 将区域设置切换为美国，(2) 将语言切换为英语，(3) 仅复制粘贴英文值。按此处说明进行。

查看 Trailhead 本地化语言徽章详细了解如何利用 Trailhead 译文。

SOSL 入门

Salesforce 对象搜索语言 (SOSL) 是一种 Salesforce 搜索语言，用于在记录中执行文本搜索。使用 SOSL 在 Salesforce 中跨多个标准和自定义对象记录搜索字段。SOSL 类似于 Apache Lucene。

向 Apex 添加 SOSL 查询非常简单 — 您可以直接在您的 Apex 代码中嵌入 SOSL 查询。当 SOSL 嵌入到 Apex 中时，它被称为内嵌式 SOSL

这是 SOSL 查询的一个示例，该查询用于搜索包含 "SFDC"一词的任何字段的客户和联系人。

List<List<SObject>> searchList = [FIND 'SFDC' IN ALL FIELDS 
                                      RETURNING Account(Name), Contact(FirstName,LastName)];

SOQL 与 SOSL 的差异与相似性

与 SOQL 一样，SOSL 允许您搜索组织的记录以获取特定信息。与一次只能查询一个标准或自定义对象的 SOQL 不同，单个 SOSL 查询可以搜索所有对象。

另一个区别是 SOSL 基于单词匹配的方式来匹配字段，而默认情况下即便不使用通配符，SOQL 仍然执行精确匹配。例如，在 SOSL 中搜索 "Digital" 会返回字段值为 "Digital" 或 "The Digital Company" 的记录，但 SOQL 只返回字段值为 "Digital" 的记录。

SOQL 和 SOSL 是两种不同语法的独立语言。每种语言都有一个独特的用例：

使用 SOQL 检索单个对象的记录。
使用 SOSL 跨多个对象搜索字段。SOSL 查询可以搜索对象上的大多数文本字段。

先决条件

本单元中部分查询示例的前提是组织内已存在客户和联系人。如果您在 SOQL 单元中未创建过示例数据，请在本单元创建示例数据。如果已创建，则可以跳过在本部分中创建示例数据的步骤。

从 Developer Console 的 Debug（调试）菜单中打开 Execute Anonymous（执行匿名）窗口。
在窗口中插入以下片段，然后单击 Execute（执行）。

// Add account and related contact
Account acct = new Account(
    Name='SFDC Computing',
    Phone='(415)555-1212',
    NumberOfEmployees=50,
    BillingCity='San Francisco');
insert acct;
// Once the account is inserted, the sObject will be 
// populated with an ID.
// Get this ID.
ID acctID = acct.ID;
// Add a contact to this account.
Contact con = new Contact(
    FirstName='Carol',
    LastName='Ruiz',
    Phone='(415)555-1212',
    Department='Wingo',
    AccountId=acctID);
insert con;
// Add account with no contact
Account acct2 = new Account(
    Name='The SFDC Query Man',
    Phone='(310)555-1213',
    NumberOfEmployees=50,
    BillingCity='Los Angeles',
    Description='Expert in wing technologies.');
insert acct2;

使用查询编辑器

Developer Console 提供查询编辑器控制台，使您能够运行 SOSL 查询并查看结果。查询编辑器提供了一种快速检查数据库的方法。将 SOSL 查询添加到 Apex 代码前，建议先测试 SOSL 查询。当您使用查询编辑器时，您只需提供 SOSL 语句，而不包含围绕它的 Apex 代码。

让我们试着运行以下 SOSL 示例：

在 Developer Console 中，单击 Query Editor（查询编辑器）选项卡。
将以下内容复制并粘贴到查询编辑器下的第一个框中，然后单击 Execute（执行）。

FIND {Wingo} IN ALL FIELDS RETURNING Account(Name), Contact(FirstName,LastName,Department)

组织中满足条件的所有客户和联系人记录都在 Query Results（查询结果）部分显示为包含字段的行。结果按每个对象（客户或联系人）的选项卡进行分组。SOSL 查询返回值与 Wingo 匹配的字段的记录。根据我们的示例数据，只有一个联系人具有 Wingo 值的字段，因此返回此联系人。

备注

查询编辑器和 API 中的搜索查询必须用大括号括起来 ({Wingo})。相反，在 Apex 中，搜索查询包含在单引号内 ('Wingo')。

SOSL 基础语法

SOSL 允许您指定以下搜索条件：

要搜索的文本表达式（单个单词或短语）
要搜索的字段范围
要检索的对象和字段列表
在源对象中选择行的条件

以下是 Apex 中的 SOSL 基础查询语法：

FIND 'SearchQuery' [IN SearchGroup] [RETURNING ObjectsAndFields]

请记住，在查询编辑器和 API 中，语法略有不同：

FIND {SearchQuery} [IN SearchGroup] [RETURNING ObjectsAndFields]

SearchQuery 表示要搜索的文本（单个单词或短语）。搜索词可以与逻辑运算符（AND、OR）和括号组合。此外，搜索词可以包含通配符（*、?）。通配符 * 在搜索词的中间或结尾匹配零个或多个字符。通配符 ? 只匹配搜索词中间或结尾的一个字符。

文本搜索不区分大小写。例如，搜索 Customer、customer 或 CUSTOMER 都会返回相同的结果。

SearchGroup 是可选的。它表示要搜索的字段范围。如果未指定，则默认搜索范围是所有字段。SearchGroup 可以取以下值之一。

ALL FIELDS
NAME FIELDS
EMAIL FIELDS
PHONE FIELDS
SIDEBAR FIELDS

ObjectsAndFields 是可选的。它表示在搜索结果中返回的信息 — 单个或多个 sObject 列表，并且在每个 sObject 中，包含一个或多个字段的列表、并带有可筛选的值。如果未指定，则搜索结果包含找到的所有对象的 ID。

单个单词或短语

SearchQuery 包含两种类型的文本：

单词— 单个单词，例如 test 或 hello。SearchQuery 中的单词以空格、标点符号和从字母到数字（或者数字到字母的）的变化来分隔。单词总是不区分大小写。
短语— 由双引号包围的单词和空格的集合，例如 "john smith"。多个单词可以与逻辑和分组运算符组合在一起，形成一个更复杂的查询。

搜索示例

要了解 SOSL 搜索的工作原理，让我们使用不同的搜索字符串，看看基于示例数据会输出什么结果。下表列出了各种示例搜索字符串和 SOSL 搜索结果。

在所有字段中搜索：	搜索描述	匹配记录和字段
The Query	此搜索返回文本任意位置中字段包含两个单词 The 和 Query 的所有记录。搜索词的单词顺序可任意排列。	客户：The SFDC Query Man（匹配名称字段）
Wingo OR Man	此搜索使用 OR 逻辑运算符。返回字段包含单词 Wingo 或 Man 的记录。	联系人：Carol Ruiz，部门：'Wingo' 客户：The SFDC Query Man（匹配名称字段）
1212	此搜索返回字段包含 1212 字样的所有记录。匹配以 -1212 结尾的电话字段，因为 1212 在以破折号分隔时被视为一个词。	客户：The SFDC Query Man，电话： '(415)555-1212' 联系人：Carol Ruiz，电话：'(415)555-1212'
wing*	这是通配符搜索。此搜索返回具有以 wing 开头的字段值的所有记录。	联系人：Maria Ruiz，部门：'Wingo' 客户：The SFDC Query Man，描述：'Expert in wing technologies.’

SOSL Apex 示例

此示例展示如何在 Apex 中运行 SOSL 查询。首先，为变量 soslFindClause 分配搜索查询，该查询由通过 OR 逻辑运算符结合的两个词（Wingo 和 SFDC）组成。SOSL 查询通过在变量前加上冒号来引用此本地变量，也称为绑定所生成的 SOSL 查询将搜索所有字段中的 Wingo 或 SFDC。本示例返回所有示例客户，因为每个客户都有包含其中一个词的字段。SOSL 搜索结果以列表的形式返回。每个列表包含返回记录的数组。这种情况下，列表有两个元素。在索引 0 处，列表包含客户数组。在索引 1 处，列表包含联系人数组。

在 Developer Console 的 Execute Anonymous（执行匿名）窗口中执行此代码片段。接下来，检查调试日志以验证是否返回所有记录。

String soslFindClause = 'Wingo OR SFDC';
List<List<sObject>> searchList = [FIND :soslFindClause IN ALL FIELDS
                    RETURNING Account(Name),Contact(FirstName,LastName,Department)];
Account[] searchAccounts = (Account[])searchList[0];
Contact[] searchContacts = (Contact[])searchList[1];
System.debug('Found the following accounts.');
for (Account a : searchAccounts) {
    System.debug(a.Name);
}
System.debug('Found the following contacts.');
for (Contact c : searchContacts) {
    System.debug(c.LastName + ', ' + c.FirstName);
}

了解详细信息...

您可以筛选、重新排序和限制 SOSL 查询的返回结果。因为 SOSL 查询可以返回多个 sObject，所以这些筛选器应用在 RETURNING 子句中的每个 sObject 中。

您可以通过在对象的 WHERE 子句中添加条件来筛选 SOSL 结果。例如，这将仅返回服装行业的客户：RETURNING Account(Name, Industry WHERE Industry='Apparel')

同样，支持通过为对象添加 ORDER BY 实现对 sObject 的结果进行排序。例如，这会导致返回的客户按名称字段排序：RETURNING Account(Name, Industry ORDER BY Name)。

返回记录的数量可以限制为记录的一个子集。此示例限制仅返回 10 个客户： RETURNING Account(Name, Industry LIMIT 10)

资源

SOQL 和 SOSL 引用