编写 SOSL 查询

学习目标

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

• 描述 SOSL 和 SOQL 之间的区别。
  
• 使用 SOSL 查询跨多个对象搜索字段。
  
• 使用 Developer Console 中的查询编辑器执行 SOSL 查询。
  
• 在 Web Console（Web 控制台）中以 Anonymous Apex（匿名 Apex）脚本的形式执行 SOSL 查询。
  

备注

用中文（简体）学习？在中文（简体）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 单元中未创建过示例数据，请在本单元创建示例数据。如果已创建，则可以跳过在本部分中创建示例数据的步骤。

1. 在 Web Console（Web 控制台）中以 Apex Anonymous（匿名 Apex）脚本的形式执行此代码。
   

// Add account and related contact
Account acct = new Account(
    Name='SFDC Computing',
    Phone='(415)555-1212',
    NumberOfEmployees=50,
    BillingCity='San Francisco');
insert as user 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 as user 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 as user acct2;

在 Developer Console 中使用 Query Editor（查询编辑器）

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

首先，在组织中启用 Developer Console。

1. 单击 () 打开 Setup（设置）。
   
2. 在 Setup（设置）中，从 Quick Find（快速查找）搜索并选择 Web Console（Web 控制台）。
   
3. 在 Enable Developer Console to:（启用 Developer Console 以：）部分，将开关切换为 Active（有效）。
   
4. 刷新页面。现在，您可以从快速访问菜单 () 中使用 Developer Console 了。如果 Developer Console 仍然不可用，请尝试再次刷新页面。
   

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

1. 在 Developer Console 中，单击 Query Editor（查询编辑器）选项卡。
   
2. 将以下内容复制并粘贴到查询编辑器下的第一个框中，然后单击 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 搜索结果。

SOSL Apex 示例

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

在 Web Console（Web 控制台）中以 Anonymous Apex（匿名 Apex）脚本的形式执行此片段。接下来，检查调试日志以验证是否返回所有记录。

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)

资源

• Salesforce 开发人员：SOQL 和 SOSL 查询
• Salesforce 开发人员：使用匿名 Apex