Overview
You can call this API to query the sampling data of specific slow SQL statements in a specified period of time. This API returns the detailed performance metrics, resource consumption, and waiting events of SQL execution, which helps you analyze and optimize SQL performance.
API details
Constraints
The caller must have an AccessKey for accessing APIs of OceanBase Cloud. For information about how to obtain the AccessKey ID and AccessKey secret, see Manage AccessKeys.
Request path
GET /api/v2/instances/{instanceId}/tenants/{tenantId}/sqls/{sqlId}/samples
Request parameters
Path
| Name | Type | Required | Description | Example value |
|---|---|---|---|---|
| instanceId | String | Yes | The ID of the OceanBase cluster. | obcluster-***** |
| tenantId | String | Yes | The ID of the tenant. | t4louaeei**** |
| sqlId | String | Yes | The unique identifier of the SQL statement. | sql_123456789 |
Query
| Name | Type | Required | Description | Example value |
|---|---|---|---|---|
| requestId | String | Yes | The ID of the request, which is used for tracing. | dc302d76-66b5-48d8-ab53-a035******** |
| dbName | String | No | The name of the database. | test11 |
| startTime | String | Yes | The start time in UTC. | 2026-02-25 15:40:43+00:00 |
| endTime | String | Yes | The end time in UTC. | 2026-02-26 10:40:43+00:00 |
Response parameters
| Parameter | Type | Description | Example |
|---|---|---|---|
| data | Object | The data. | {} |
| dataList | Array | The data list. | [] |
| causeType | String | The sampling type. | SLOW_SQL |
| affectedRows | Long | The average number of rows updated during the period. | 0 |
| blockCacheHit | Double | The number of times the BlockCache was hit. | 0.0 |
| blockIndexCacheHit | Double | The number of times the BlockIndexCache was hit. | 0.0 |
| bloomFilterCacheHit | Double | The number of times the BloomFilterCache was hit. | 0.0 |
| clientIp | String | The IP address of the client. | xx.xx.xx.xx |
| clientPort | Long | The port number of the client. | 19580 |
| cpuTime | Double | The CPU time in milliseconds. | 1949.68 |
| dbName | String | The name of the database. | test11 |
| decodeTime | Double | The time spent on syntax parsing in milliseconds. | 0.0 |
| diskReads | Double | The number of disk reads. | 0.0 |
| elapsedTime | Double | The response time in milliseconds. | 1956.43 |
| executeTime | Double | The plan execution time in milliseconds. | 1949.66 |
| executorRpc | Boolean | Indicates whether an RPC was initiated. | false |
| expectedWorkerCount | Long | The degree of parallelism. | 0 |
| fullSqlText | String | The complete SQL text. | select * from high_d |
| getPlanTime | Double | The time spent on plan generation in milliseconds. | 0.03 |
| hitPlan | Boolean | Indicates whether the execution plan was hit. | true |
| inner | Boolean | Indicates whether the SQL statement is an internal SQL statement. | false |
| memstoreReadRows | Long | The number of rows read from the MemStore. | 0 |
| netTime | Double | The network transmission time in milliseconds. | 0.0 |
| netWaitTime | Double | The network queueing time in milliseconds. | 0.0 |
| partitionCount | Long | The average number of partitions accessed during the period. | 1 |
| planId | Long | The ID of the execution plan. | 1049 |
| planType | String | The type of the plan. | LOCAL |
| queueTime | Double | The queuing time in milliseconds. | 6.75 |
| requestId | Long | The request ID. | 369604 |
| requestTime | String | The request time of the SQL statement. | 2025-12-23T06:47:06.207Z |
| retCode | Long | The result code. | 0 |
| retryCount | Long | The number of retries. | 0 |
| returnRows | Long | The average number of rows returned during the period. | 1 |
| rowCacheHit | Double | The number of times the RowCache was hit. | 0.0 |
| rpcCount | Long | The number of RPCs sent. | 0 |
| server | String | The server where the SQL statement is executed. | i-uf******** |
| sqlId | String | The ID of the SQL statement. | 5D51DC02208F9A448157FD8A******** |
| sqlTextShort | String | The short text of the SQL statement. | select * from high_disk_read_2 where id > ? order by id desc limit ? |
| sqlType | String | The type of the SQL statement. | SELECT |
| ssstoreReadRows | Long | The number of rows read from the SsStore. | 525 |
| tableScan | Boolean | Indicates whether a full table scan was performed. | true |
| traceId | String | The trace ID. | YB420A7100C3-00064694CC824665-0-0 |
| transHash | String | The transaction hash. | 0 |
| usedWorkerCount | Long | The actual number of execution threads. | 0 |
| userClientIp | String | The IP address of the user client. | xx.xx.xx.xx |
| userName | String | The username. | test11 |
| waitCount | Long | The number of waits. | 0 |
| waitEvent | String | The longest waiting event during the period. | event:, p1text:, p1:0, p2text:, p2:0, p3text:, p3:0 |
Examples
Request example
curl --digest -u '<Your ak:sk>' \
-X GET \
'https://api-cloud.oceanbase.com/api/v2/instances/{instanceId}/tenants/{tenantId}/sqls/{sqlId}/samples?requestId={requestId}&startTime={startTime}&endTime={endTime}' \
-G \
-d 'dbName={dbName}'
Response example
JSON format
{
"data": {
"dataList": [
{
"affectedRows": 0,
"blockCacheHit": 0.0,
"blockIndexCacheHit": 0.0,
"bloomFilterCacheHit": 0.0,
"clientIp": "xx.xx.xx.xx",
"clientPort": 19580,
"cpuTime": 1949.68,
"dbName": "test11",
"decodeTime": 0.0,
"diskReads": 0.0,
"elapsedTime": 1956.43,
"executeTime": 1949.66,
"executorRpc": false,
"expectedWorkerCount": 0,
"fullSqlText": "select * from high_disk_read_2 where id > -4413621632286266099 order by id desc limit 1",
"getPlanTime": 0.03,
"hitPlan": true,
"inner": false,
"memstoreReadRows": 0,
"netTime": 0.0,
"netWaitTime": 0.0,
"partitionCount": 1,
"planId": 1049,
"planType": "LOCAL",
"queueTime": 6.75,
"requestId": 369604,
"requestTime": "2025-12-23T06:47:06.207Z",
"retCode": 0,
"retryCount": 0,
"returnRows": 1,
"rowCacheHit": 0.0,
"rpcCount": 0,
"server": "xxx.xxx.x.xxx:xxxx",
"sqlId": "5D51DC02208F9A448157FD8A********",
"sqlTextShort": "select * from high_disk_read_2 where id > ? order by id desc limit ?",
"sqlType": "SELECT",
"ssstoreReadRows": 525,
"tableScan": true,
"traceId": "YB420A7100C3-00064694CC824665-0-0",
"transHash": "0",
"usedWorkerCount": 0,
"userClientIp": "xx.xx.xx.xx",
"userName": "test11",
"waitCount": 0,
"waitEvent": "event:, p1text:, p1:0, p2text:, p2:0, p3text:, p3:0"
}
]
},
"requestId": "4c437bbe-d404-4b7a-afcb-88749e4d47a2",
"success": true
}