datai/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/004-search.md

执行 SOSL 搜索

接口概述

执行 SOSL (Salesforce Object Search Language) 全文搜索，在多个对象中快速查找匹配的记录。

基本信息

属性	值
接口名称	执行 SOSL 搜索
接口路径	/partner/search
请求方法	POST
Content-Type	application/json
需要认证	是
所属模块	datai-salesforce-partner

请求参数

请求体 (Request Body)

参数名	类型	必填	说明	示例值
sosl	String	是	SOSL 搜索语句	FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name), Contact(Id, Name)

请求示例

{
  "sosl": "FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name, BillingCity), Contact(Id, FirstName, LastName, Email)"
}

响应参数

响应体 (Response Body)

参数名	类型	说明
code	Integer	响应状态码，200 表示成功
msg	String	响应消息
data	Object	响应数据

data 对象结构

参数名	类型	说明
searchRecords	Array	搜索结果列表
success	Boolean	是否成功
errors	Array	错误信息列表

searchRecords 对象结构

参数名	类型	说明
objectName	String	对象名称
records	Array	该对象的匹配记录列表

响应示例

成功响应

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "searchRecords": [
      {
        "objectName": "Account",
        "records": [
          {
            "Id": "001xx000003DHb2AAG",
            "Name": "Acme Corporation",
            "BillingCity": "San Francisco"
          },
          {
            "Id": "001xx000003DHb3AAH",
            "Name": "Acme Solutions",
            "BillingCity": "New York"
          }
        ]
      },
      {
        "objectName": "Contact",
        "records": [
          {
            "Id": "003xx000003DHb2AAG",
            "FirstName": "John",
            "LastName": "Acme",
            "Email": "john.acme@example.com"
          }
        ]
      }
    ],
    "success": true,
    "errors": []
  }
}

错误响应

{
  "code": 500,
  "msg": "SOSL 搜索失败: Invalid search query",
  "data": null
}

错误码

错误码	说明	处理建议
400	请求参数错误	检查 sosl 语句格式是否正确
401	认证失败	检查 Salesforce 认证信息是否有效
500	服务器内部错误	检查 SOSL 语句语法是否正确

使用说明

SOSL 语法结构

FIND {搜索词} IN {搜索范围} RETURNING {对象列表}

搜索范围选项

搜索范围	说明
ALL FIELDS	所有可搜索字段
NAME FIELDS	名称字段
EMAIL FIELDS	邮箱字段
PHONE FIELDS	电话字段
SIDEBAR FIELDS	侧边栏字段

SOSL 语法示例

1. 基本搜索

{
  "sosl": "FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name)"
}

2. 多对象搜索

{
  "sosl": "FIND {Technology} IN ALL FIELDS RETURNING Account(Id, Name, Industry), Contact(Id, FirstName, LastName), Opportunity(Id, Name, Amount)"
}

3. 指定搜索范围

{
  "sosl": "FIND {john@example.com} IN EMAIL FIELDS RETURNING Contact(Id, FirstName, LastName, Email), Lead(Id, FirstName, LastName, Email)"
}

4. 限制结果数量

{
  "sosl": "FIND {Acme} IN NAME FIELDS RETURNING Account(Id, Name, BillingCity LIMIT 10), Contact(Id, FirstName, LastName LIMIT 5)"
}

5. 带条件的搜索

{
  "sosl": "FIND {Technology} IN ALL FIELDS RETURNING Account(Id, Name, Industry WHERE Industry = 'Technology' LIMIT 10)"
}

6. 短语搜索

{
  "sosl": "FIND {\"San Francisco\"} IN ALL FIELDS RETURNING Account(Id, Name, BillingCity)"
}

7. 通配符搜索

{
  "sosl": "FIND {Acme*} IN ALL FIELDS RETURNING Account(Id, Name)"
}

SOSL 与 SOQL 的区别

特性	SOSL	SOQL
搜索类型	全文搜索	精确查询
搜索范围	多个对象	单个对象
搜索字段	可搜索字段	任意字段
性能	适合模糊搜索	适合精确查询
使用场景	全局搜索、快速查找	数据报表、复杂查询

注意事项

1. 搜索词限制

   • 搜索词长度至少 2 个字符
   • 不区分大小写
   • 支持通配符 (*)

2. 结果限制

   • 每个对象最多返回 200 条记录
   • 总记录数限制为 2000 条
   • 建议使用 LIMIT 限制结果数量

3. 性能优化

   • 避免使用过于宽泛的搜索词
   • 合理使用搜索范围缩小结果集
   • 限制返回的对象和字段数量

4. 特殊字符

   • 短语搜索需要使用双引号
   • 转义特殊字符：, *, ", '
   • 空格表示 AND 关系

相关接口

• 执行 SOQL 查询
• 查询所有记录（包括已删除的）
• 获取查询结果的下一页

更新日志

版本	日期	更新内容	作者
1.0.0	2026-01-30	初始版本	AI Assistant