# 获取查询结果的下一页

## 接口概述

使用 queryLocator 获取查询结果的下一页数据。当查询结果超过批次大小时，可以通过此接口分页获取剩余数据。

## 基本信息

| 属性 | 值 |
|------|-----|
| 接口名称 | 获取查询结果的下一页 |
| 接口路径 | `/partner/queryMore` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 需要认证 | 是 |
| 所属模块 | datai-salesforce-partner |

## 请求参数

### 请求体 (Request Body)

| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|--------|------|------|------|--------|
| queryLocator | String | 是 | 查询定位器，从 Query 或 QueryAll 的结果中获取 | `01gD0000002J6ozIAC-2000` |

### 请求示例

```json
{
  "queryLocator": "01gD0000002J6ozIAC-2000"
}
```

## 响应参数

### 响应体 (Response Body)

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

### data 对象结构

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

### 响应示例

**成功响应（还有更多数据）**

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "records": [
      {
        "Id": "001xx000003DHb4AAI",
        "Name": "Global Tech Solutions",
        "BillingCity": "Los Angeles",
        "Industry": "Technology"
      },
      {
        "Id": "001xx000003DHb5AAJ",
        "Name": "Innovate Corp",
        "BillingCity": "Chicago",
        "Industry": "Technology"
      }
    ],
    "queryLocator": "01gD0000002J6ozIAC-4000",
    "done": false,
    "size": 2,
    "success": true,
    "errors": []
  }
}
```

**成功响应（最后一页）**

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "records": [
      {
        "Id": "001xx000003DHb6AAK",
        "Name": "Future Systems",
        "BillingCity": "Boston",
        "Industry": "Technology"
      }
    ],
    "queryLocator": null,
    "done": true,
    "size": 1,
    "success": true,
    "errors": []
  }
}
```

**错误响应**

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

## 错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 400 | 请求参数错误 | 检查 queryLocator 是否有效 |
| 401 | 认证失败 | 检查 Salesforce 认证信息是否有效 |
| 404 | 查询定位器不存在 | queryLocator 可能已过期或无效 |
| 500 | 服务器内部错误 | 检查 queryLocator 格式是否正确 |

## 使用说明

### 分页查询流程

1. **首次查询**

调用 `query` 或 `queryAll` 接口获取第一批数据：

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

2. **检查是否还有更多数据**

查看响应中的 `done` 字段：
- `done: false` - 还有更多数据
- `done: true` - 已获取所有数据

3. **获取下一页**

如果 `done` 为 false，使用返回的 `queryLocator` 调用 `queryMore`：

```json
{
  "queryLocator": "01gD0000002J6ozIAC-2000"
}
```

4. **重复步骤 2-3**

直到 `done` 为 true。

### 完整分页示例

```javascript
// 伪代码示例
let queryLocator = null;
let allRecords = [];

// 首次查询
const firstResult = await query({
  soql: "SELECT Id, Name FROM Account",
  batchSize: 500
});
allRecords = allRecords.concat(firstResult.data.records);
queryLocator = firstResult.data.queryLocator;

// 循环获取剩余数据
while (queryLocator && !firstResult.data.done) {
  const result = await queryMore({ queryLocator });
  allRecords = allRecords.concat(result.data.records);
  queryLocator = result.data.queryLocator;
  
  if (result.data.done) {
    break;
  }
}

console.log(`总共获取 ${allRecords.length} 条记录`);
```

### 注意事项

1. **queryLocator 有效期**
   - queryLocator 在查询会话期间有效
   - 会话超时后 queryLocator 会失效
   - 建议在合理时间内完成分页查询

2. **批次大小**
   - 首次查询的 batchSize 决定每页的记录数
   - queryMore 无法修改批次大小
   - 建议根据实际需求设置合适的批次大小

3. **性能优化**
   - 避免一次性获取过多数据
   - 根据业务需求合理设置批次大小
   - 考虑使用更精确的查询条件减少数据量

4. **错误处理**
   - 捕获并处理 queryLocator 过期的情况
   - 当 queryLocator 失效时，需要重新执行初始查询

## 相关接口

- [执行 SOQL 查询](./001-query.md)
- [查询所有记录（包括已删除的）](./002-query-all.md)
- [执行 SOSL 搜索](./004-search.md)

## 更新日志

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