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)` |

### 请求示例

```json
{
  "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 | 该对象的匹配记录列表 |

### 响应示例

**成功响应**

```json
{
  "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": []
  }
}
```

**错误响应**

```json
{
  "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. **基本搜索**

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

2. **多对象搜索**

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

3. **指定搜索范围**

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

4. **限制结果数量**

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

5. **带条件的搜索**

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

6. **短语搜索**

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

7. **通配符搜索**

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

### SOSL 与 SOQL 的区别

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

### 注意事项

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

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

3. **性能优化**
   - 避免使用过于宽泛的搜索词
   - 合理使用搜索范围缩小结果集
   - 限制返回的对象和字段数量

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

## 相关接口

- [执行 SOQL 查询](./001-query.md)
- [查询所有记录（包括已删除的）](./002-query-all.md)
- [获取查询结果的下一页](./003-query-more.md)

## 更新日志

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