datai/datai-scenes/datai-scene-salesforce/docs/api-docs/partner-api/PartnerQueryController/001-query.md

执行 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

请求示例

{
  "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	错误信息列表

响应示例

成功响应

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

错误响应

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

错误码

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

使用说明

SOQL 语法示例

1. 基本查询

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

2. 带条件查询

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

3. 排序和限制

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

4. 关联查询

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

5. 聚合查询

{
  "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. 字符串值需要用单引号包裹

相关接口

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

更新日志

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