# 执行 SOQL 查询

## 接口概述

执行标准的 SOQL (Salesforce Object Query Language) 查询语句，从 Salesforce 获取数据。

## 基本信息

| 属性 | 值 |
|------|-----|
| 接口名称 | 执行 SOQL 查询 |
| 接口路径 | `/partner/query` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 需要认证 | 是 |
| 所属模块 | datai-salesforce-partner |

## 请求参数

### 请求体 (Request Body)

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| soql | String | 是 | SOQL 查询语句 | `SELECT Id, Name FROM Account LIMIT 10` |
| batchSize | Integer | 否 | 批次大小，默认 500，最大 2000 | `500` |

### 请求示例

```json
{
  "soql": "SELECT Id, Name, BillingCity, Industry FROM Account WHERE Industry = 'Technology' LIMIT 10",
  "batchSize": 500
}
```

## 响应参数

### 响应体 (Response Body)

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

### data 对象结构

| 参数名 | 类型 | 说明 |
|--------|------|------|
| records | Array | 记录列表，每个记录是一个键值对对象 |
| queryLocator | String | 查询定位器，用于 QueryMore 获取下一页 |
| done | Boolean | 是否完成（true 表示没有更多数据） |
| size | Integer | 记录数量 |
| success | Boolean | 是否成功 |
| errors | Array | 错误信息列表 |

### 响应示例

**成功响应**

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "records": [
      {
        "Id": "001xx000003DHb2AAG",
        "Name": "Acme Corporation",
        "BillingCity": "San Francisco",
        "Industry": "Technology"
      },
      {
        "Id": "001xx000003DHb3AAH",
        "Name": "Tech Solutions Inc",
        "BillingCity": "New York",
        "Industry": "Technology"
      }
    ],
    "queryLocator": "01gD0000002J6ozIAC-2000",
    "done": false,
    "size": 2,
    "success": true,
    "errors": []
  }
}
```

**错误响应**

```json
{
  "code": 500,
  "msg": "SOQL 查询失败: Invalid query",
  "data": null
}
```

## 错误码

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

## 使用说明

### SOQL 语法示例

1. **基本查询**

```json
{
  "soql": "SELECT Id, Name FROM Account"
}
```

2. **带条件查询**

```json
{
  "soql": "SELECT Id, Name, BillingCity FROM Account WHERE Industry = 'Technology' AND BillingCity = 'San Francisco'"
}
```

3. **排序和限制**

```json
{
  "soql": "SELECT Id, Name, CreatedDate FROM Account ORDER BY CreatedDate DESC LIMIT 10"
}
```

4. **关联查询**

```json
{
  "soql": "SELECT Id, Name, Account.Name, Account.Industry FROM Contact WHERE Account.Industry = 'Technology'"
}
```

5. **聚合查询**

```json
{
  "soql": "SELECT Industry, COUNT(Id) FROM Account GROUP BY Industry"
}
```

### 分页处理

当查询结果超过批次大小时，使用返回的 `queryLocator` 调用 `queryMore` 接口获取下一页数据。

### 注意事项

1. SOQL 语句必须以 `SELECT` 开头
2. 批次大小范围：1-2000，默认 500
3. 查询结果最大记录数限制为 50,000
4. 复杂查询可能超时，建议添加适当的过滤条件和 LIMIT
5. 字段名区分大小写
6. 字符串值需要用单引号包裹

## 相关接口

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

## 更新日志

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