14.sql-performance.md•11.5 kB
# OceanBase API文档整理
---
## 一、SQL性能统计相关
### 1. 查询SQL的性能统计
**路径**: `GET /api/v2/ob/clusters/{clusterId}/tenants/{tenantId}/topSql`
#### 请求参数
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|--------------|------------|------|----------------------------|----------------------------------------------------------------------|
| clusterId | Integer | 是 | 1 | 集群ID |
| tenantId | Integer | 是 | 1001 | 租户ID |
| startTime | Datetime | 是 | 2020-02-16T05:32:16+08:00 | 起始时间 |
| endTime | Datetime | 是 | 2020-02-16T07:32:16+08:00 | 结束时间 |
| serverId | Integer | 否 | 300 | 指定服务器ID，不指定则查询所有服务器 |
| inner | Boolean | 否 | false | 是否包含内部SQL（默认false） |
| sqlText | String | 否 | hello | SQL文本关键词（不区分大小写） |
| searchAttr | String | 否 | executions | 高级搜索指标名（需配合searchOp和searchVal） |
| searchOp | String | 否 | GT | 操作符（EQ/NE/GT/GE/LT/LE） |
| searchVal | String | 否 | 1543 | 高级搜索值（需配合searchAttr和searchOp） |
#### 返回结构
- **基础字段**：
| 参数 | 类型 | 说明 |
|--------------|------------|--------------------------------|
| data | Object | 业务数据对象 |
| successful | Boolean | 请求是否成功 |
| timestamp | Datetime | 服务端完成时间戳 |
| duration | Integer | 请求处理时间（毫秒） |
| status | Integer | HTTP状态码 |
| traceId | String | 请求追踪ID |
| server | String | 响应服务端地址 |
- **data.contents字段**：
包含SQL性能指标的详细数据，如：
```json
{
"sqlId": "字符串",
"executions": 整数,
"avgElapsedTime": 浮点数,
"failCount": 整数,
...
}
```
#### 示例
```http
GET /api/v2/ob/clusters/1/tenants/1001/topSql?searchAttr=executions&searchOp=GE&searchVal=500&startTime=2020-11-03T19%3A00%3A00%2B08%3A00&endTime=2020-11-03T20%3A00%3A00%2B08%3A00
```
---
### 2. 查询SQL的性能统计趋势
**路径**: `GET /api/v2/ob/clusters/{clusterId}/tenants/{tenantId}/sqls/{sqlId}/trends`
#### 请求参数
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|--------------|------------|------|----------------------------|----------------------------------------------------------------------|
| clusterId | Integer | 是 | 1 | 集群ID |
| tenantId | Integer | 是 | 1001 | 租户ID |
| sqlId | String | 是 | C9B3A63AFF8F2A408CCF3D5B0F36682D | SQL唯一标识符 |
| startTime | Datetime | 是 | 2020-02-16T05:32:16+08:00 | 起始时间 |
| endTime | Datetime | 是 | 2020-02-16T07:32:16+08:00 | 结束时间 |
| serverId | Integer | 否 | 300 | 指定服务器ID |
| dbName | String | 否 | oceanbase | 数据库名称，不指定则查询所有数据库 |
#### 返回结构
- **基础字段**：同上
- **data.contents字段**：
```json
{
"timestamp": "ISO8601时间",
"executions": 整数,
"execPs": 浮点数,
"avgElapsedTime": 浮点数,
...
}
```
#### 示例
```http
GET /api/v2/ob/clusters/1/tenants/1001/sqls/C9B3A63AFF8F2A408CCF3D5B0F36682D/trends?startTime=2020-11-03T19%3A00%3A00%2B08%3A00&endTime=2020-11-03T20%3A00%3A00%2B08%3A00&dbName=oceanbase&serverId=2
```
---
## 二、执行计划相关
### 1. 查询执行计划的性能统计
**路径**: `GET /api/v2/ob/clusters/{clusterId}/tenants/{tenantId}/sqls/{sqlId}/topPlan`
#### 请求参数
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|--------------|------------|------|----------------------------|----------------------------------------------------------------------|
| clusterId | Integer | 是 | 1 | 集群ID |
| tenantId | Integer | 是 | 1001 | 租户ID |
| sqlId | String | 是 | C9B3A63AFF8F2A408CCF3D5B0F36682D | SQL唯一标识符 |
| startTime | Datetime | 是 | 2020-02-16T05:32:16+08:00 | 起始时间 |
| endTime | Datetime | 是 | 2020-02-16T07:32:16+08:00 | 结束时间 |
| serverId | Integer | 否 | 300 | 指定服务器ID，不指定则查询所有服务器 |
#### 返回结构
- **基础字段**：同上
- **data.contents字段**：
```json
{
"uid": "字符串",
"server": "IP:端口",
"planType": "LOCAL/REMOTE/DIST",
"executions": 整数,
"avgElapsedTime": 浮点数,
"tableScan": 布尔值,
...
}
```
#### 示例
```http
GET /api/v2/ob/clusters/1/tenants/1/sqls/520A740747059F992A31CE41876BB161/topPlan?startTime=2020-11-11T11%3A30%3A00%2B08%3A00&endTime=2020-11-11T12%3A00%3A00%2B08%3A00
```
---
### 2. 查询执行计划的性能趋势
**路径**: `GET /api/v2/ob/clusters/{clusterId}/tenants/{tenantId}/plans/{uid}/trends`
#### 请求参数
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|--------------|------------|------|----------------------------|----------------------------------------------------------------------|
| clusterId | Integer | 是 | 1 | 集群ID |
| tenantId | Integer | 是 | 1001 | 租户ID |
| uid | String | 是 | AAAAAAAAAAEAAAAAAAKOvgAFs1_j8s3i | 执行计划唯一标识符 |
| startTime | Datetime | 是 | 2020-02-16T05:32:16+08:00 | 起始时间 |
| endTime | Datetime | 是 | 2020-02-16T07:32:16+08:00 | 结束时间 |
#### 返回结构
- **基础字段**：同上
- **data.contents字段**：
```json
{
"timestamp": "ISO8601时间",
"executions": 整数,
"execPs": 浮点数,
"avgElapsedTime": 浮点数,
"tableScan": 布尔值,
...
}
```
#### 示例
```http
GET /api/v2/ob/clusters/1/tenants/1001/plans/AAAAAAAAAAEAAAAAAAAJ_AAFszE_cnfR/trends?startTime=2020-11-03T19%3A00%3A00%2B08%3A00&endTime=2020-11-03T20%3A00%3A00%2B08%3A00
```
---
## 三、执行计划算子结构
### 查询执行计划的算子结构
**路径**: `GET /api/v2/ob/clusters/{clusterId}/tenants/{tenantId}/plans/{uid}/explain`
#### 请求参数
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|--------------|------------|------|----------------------------|----------------------------------------------------------------------|
| clusterId | Integer | 是 | 1 | 集群ID |
| tenantId | Integer | 是 | 1001 | 租户ID |
| uid | String | 是 | AAAAAAAAAAEAAAAAAAAJ_AAFszE_cnfR | 执行计划唯一标识符 |
| startTime | Datetime | 是 | 2020-02-16T05:32:16+08:00 | 起始时间 |
| endTime | Datetime | 是 | 2020-02-16T07:32:16+08:00 | 结束时间 |
#### 返回结构
- **基础字段**：同上
- **data.rootOperations字段**：
```json
[
{
"operator": "算子名称",
"objectName": "操作对象（如表名）",
"rows": 整数,
"cost": 整数,
"children": [子节点数组]
}
]
```
#### 示例
```http
GET /api/v2/ob/clusters/1/tenants/1001/plans/AAAAAAAAAAEAAAAAAAAJ_AAFszE_cnfR/explain?startTime=2020-11-03T19%3A00%3A00%2B08%3A00&endTime=2020-11-03T20%3A00%3A00%2B08%3A00
```
---
## 四、SQL文本查询
### 查询SQL的全文
**路径**: `GET /api/v2/ob/clusters/{clusterId}/tenants/{tenantId}/sqls/{sqlId}/text`
#### 请求参数
| 参数 | 类型 | 必选 | 示例值 | 描述 |
|--------------|------------|------|----------------------------|----------------------------------------------------------------------|
| clusterId | Integer | 是 | 1 | 集群ID |
| tenantId | Integer | 是 | 1001 | 租户ID |
| sqlId | String | 是 | C9B3A63AFF8F2A408CCF3D5B0F36682D | SQL唯一标识符 |
| startTime | Datetime | 是 | 2020-02-16T05:32:16+08:00 | 起始时间 |
| endTime | Datetime | 是 | 2020-02-16T07:32:16+08:00 | 结束时间 |
#### 返回结构
- **基础字段**：同上
- **data.fulltext字段**：
```json
{
"fulltext": "SQL完整文本字符串"
}
```
#### 示例
```http
GET /api/v2/ob/clusters/1/tenants/1001/sqls/C9B3A63AFF8F2A408CCF3D5B0F36682D/text?startTime=2020-11-03T19%3A00%3A00%2B08%3A00&endTime=2020-11-03T20%3A00%3A00%2B08%3A00
```