# 查询Top SQL列表 - QueryingTopSQLStatements #### 功能介绍 根据实例ID查询Top SQL信息。 - 调用接口前，您需要了解API [认证鉴权](https://support.huaweicloud.com/api-gaussdb/gaussdb_api_011.html)。 - 调用接口前，您需要提前获取到[地区和终端节点](https://developer.huaweicloud.com/endpoint)。 #### 接口约束 仅支持包含有CN或DN（主、备）组件的节点。 #### 调试 您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?product=GaussDBforopenGauss&api=ListTopSqls)中调试该接口。 #### URI POST /v3/{project_id}/instances/{instance_id}/top-sql-list 表1参数说明 | 名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | project_id | 是 | String | **参数解释：** 租户在某一Region下的项目ID。 获取方法请参见[获取项目ID](https://support.huaweicloud.com/api-gaussdb/gaussdb_api_196.html)。 **约束限制：** 不涉及。 **取值范围：** 只能由英文字母、数字组成，且长度为32个字符。 **默认取值**： 不涉及。 | | instance_id | 是 | String | **参数解释：** 实例ID，此参数是用户创建实例的唯一标识。请参考[查询数据库实例列表 - QueryingDBInstances](https://support.huaweicloud.com/api-gaussdb/gaussdb_api_328.html)接口获取实例ID。 **约束限制：** 不涉及。 **取值范围：** 只能由英文字母、数字组成，且长度为36个字符。 **默认取值** **：** 不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释：** 用户Token。 通过调用IAM服务[获取用户Token](https://support.huaweicloud.com/api-iam/iam_30_0001.html)接口获取。 请求响应成功后在响应消息头中包含的"X-Subject-Token"的值即为Token值。 **约束限制：** 不涉及。 **取值范围** **：** 不涉及。 **默认取值** **：** 不涉及。 | | X-Language | 否 | String | **参数解释：** 指定接口返回信息的语言类型。 **约束限制：** 不涉及。 **取值范围** **：** - **zh-cn：**中文 - **en-us** **：**英文 **默认取值** **：** **en-us** | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | instance_id | 是 | String | **参数解释：** 实例ID，此参数是用户创建实例的唯一标识。请参考[查询数据库实例列表 - QueryingDBInstances](https://support.huaweicloud.com/api-gaussdb/gaussdb_api_328.html)接口获取实例ID。 **约束限制：** 不涉及。 **取值范围：** 只能由英文字母、数字组成，且长度为36个字符。 **默认取值** **：** 不涉及。 | | node_ids | 是 | Array of strings | **参数解释：** 所选实例节点ID列表。获取方式请参考[查询实例的组件列表 - QueryingtheComponentsofaDBInstance](https://support.huaweicloud.com/api-gaussdb/gaussdb_api_028.html)。 **约束限制：** 不涉及。 | | start_time | 是 | Long | **参数解释：** 起始时间。 **约束限制：** 13位UNIX时间戳格式，单位是毫秒，时区是UTC。 **取值范围：** 不涉及。 **默认取值**： 不涉及。 | | end_time | 是 | Long | **参数解释：** 结束时间。 **约束限制：** 13位UNIX时间戳格式，单位是毫秒，时区是UTC。 **取值范围：** 不涉及。 **默认取值**： 不涉及。 | | start_time_utc | 否 | String | **参数解释：** 起始时间。 **约束限制：** UTC时间。格式必须为yyyy-mm-ddThh:mm:ssZ。 **取值范围：** 不涉及。 **默认取值**： 不涉及。 | | end_time_utc | 否 | String | **参数解释：** 结束时间。 **约束限制：** UTC时间。格式必须为yyyy-mm-ddThh:mm:ssZ。 **取值范围：** 不涉及。 **默认取值**： 不涉及。 | | support_system | 否 | Boolean | **参数解释：** 是否支持展示系统用户。 **约束限制：** 不涉及 **取值范围：** - true：支持展示系统用户。 - false：不支持展示系统用户。 **默认取值**： 不涉及。 | | sql_id | 否 | String | **参数解释：** Top SQL的归一化SQL ID。获取方式请参考[查询全量单条SQL列表 - QueryingFullDatabySQLStatement](https://support.huaweicloud.com/api-gaussdb/gaussdb_api_541.html)。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值**： 不涉及。 | | db_name | 否 | String | **参数解释：** Top SQL的数据库名。 **约束限制：** 引擎版本8.200及以上显示。 **取值范围：** 不涉及。 **默认取值**： 不涉及。 | | user_name | 否 | String | **参数解释：** Top SQL的用户名。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值**： 不涉及。 | | sql_text | 否 | String | **参数解释：** Top SQL的SQL文本。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值**： 不涉及。 | | multi_queries | 否 | Array of objects | **参数解释** **：** 字段汇聚查询条件列表。 详情请参见[表4]。 **约束限制：** 只支持针对query字段全与或者全或的查询。 | 表4MultiMergeCondition | **参数** | 是否必选 | **参数类型** | **描述** | |:---|:---|:---|:---| | name | 是 | String | **参数解释** **：** 查询字段名称。 **约束限制：** 只支持字符串"query"。 **取值范围：** "query"：表示查询。 **默认取值** **：** 不涉及。 | | condition | 是 | String | **参数解释** **：** 合并条件。多个筛选条件之间的逻辑合并方式。当查询涉及多个筛选条件时，通过该参数指定条件之间是"且"还是"或"的关系。 **约束限制：** 不涉及。 **取值范围：** - "and"："与"。 - "or"："或"。 - "AND"："与"。 - "OR"："或"。 **默认取值** **：** 不涉及。 | | values | 是 | Array of strings | **参数解释** **：** 多个过滤检索条件内容集合。每个字符串为一个SQL文本查询条件，用于对query字段进行模糊匹配。 **约束限制：** 由 1 至 5 个字符串组成的列表。 | | is_fuzzy | 否 | Boolean | **参数解释** **：** 是否进行模糊查询。 **约束限制：** 只支持为true进行模糊查询。 **取值范围：** - true 表示模糊查询。 - false 表示精确匹配。 **默认取值** **：** true | #### 响应参数 表5响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | top_sql_infos | Array of objects | **参数解释：** Top SQL信息列表。详细内容请参见[表6]。 | | total | Integer | **参数解释：** Top SQL总条数。 **取值范围：** 不涉及。 | 表6TopSqlInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | sql_id | String | **参数解释：** Top SQL的归一化SQL ID。 **取值范围：** 不涉及。 | | user_name | String | **参数解释：** Top SQL的用户名。 **取值范围：** 不涉及。 | | sql_text | String | **参数解释：** Top SQL的SQL文本。 **取值范围：** 不涉及。 | | calls_percent | String | **参数解释：** Top SQL的调用频率占比。 **取值范围：** 0-100。 | | cpu_percent | String | **参数解释：** Top SQL的CPU开销占比。 **取值范围：** 0-100。 | | io_percent | String | **参数解释：** Top SQL的IO开销占比。 **取值范围：** 0-100。 | | calls | String | **参数解释：** Top SQL的调用次数。 **取值范围：** 大于等于0。 | | returned_rows | String | **参数解释：** Top SQL的返回元组数。 **取值范围：** 大于等于0。 | | tuple_read | String | **参数解释：** Top SQL的读取元组数。 **取值范围：** 大于等于0。 | | avg_elapse_time | String | **参数解释：** Top SQL的平均时间开销。单位ms。 **取值范围：** 大于等于0。 | | total_elapse_time | String | **参数解释：** Top SQL的总时间开销。单位ms。 **取值范围：** 大于等于0。 | | cpu_time | String | **参数解释：** Top SQL的CPU开销。单位ms。 **取值范围：** 不涉及。 | | io_time | String | **参数解释：** Top SQL的IO开销。单位ms。 **取值范围：** 不涉及。 | | min_elapse_time | String | **参数解释：** Top SQL的最小执行时间。单位ms。 **取值范围：** 不涉及。 | | max_elapse_time | String | **参数解释：** Top SQL的最大执行时间。单位ms。 **取值范围：** 不涉及。 | | sql_hit_ratio | String | **参数解释：** Top SQL的SQL命中率。 **取值范围：** 大于等于0。 | | node_id | String | **参数解释：** Top SQL的节点ID。 **取值范围：** 不涉及。 | | node_name | String | **参数解释：** Top SQL的节点名称。 **取值范围：** 不涉及。 | | db_name | String | **参数解释：** Top SQL的数据库名（引擎版本8.200及以上支持）。 **取值范围：** 不涉及。 | #### 请求示例 查询Top SQL列表信息。 ``` POST https://gaussdb-opengauss.cn-north-1.myhuaweicloud.com/v3/0611f1bd8b00d5d32f17c017f15b599f/instances/3d39c18788b54a919bab633874c159dfin14/top-sql-list { "instance_id": "3d39c18788b54a919bab633874c159dfin14", "node_ids": [ "ce86fdea77304bfb9469d0b75ea3943ano14" ], "start_time": 1745477837000, "end_time": 1745564237000, "start_time_utc": "2025-04-24T06:57:17+0000", "end_time_utc": "2025-04-25T06:57:17+0000", "user_name": "dbmind_server", "sql_text": "BEGIN", "sql_id": "1872435845", "db_name": "postgres", "support_system": false, "multi_queries": [ { "name": "query", "condition": "AND", "is_fuzzy": true, "values": [ "BEGIN" ] } ] } ``` #### 响应示例 查询慢SQL节点信息成功。 ``` { "top_sql_infos": [ { "sql_id": "1872435845", "user_name": "dbmind_server", "sql_text": "BEGIN", "calls_percent": "48.15", "cpu_percent": "20.16", "io_percent": "0.00", "calls": "117", "returned_rows": "0", "tuple_read": "0", "avg_elapse_time": "0.0520", "total_elapse_time": "6.0830", "cpu_time": "9.2660", "io_time": "0.0000", "min_elapse_time": "0.0210", "max_elapse_time": "0.1820", "sql_hit_ratio": "0", "node_id": "ce86fdea77304bfb9469d0b75ea3943ano14", "node_name": "gauss-6e34-gaussdbv5cn_0", "db_name": "postgres" } ], "total": 1 } ``` #### 状态码 - 正常 200 - 异常 请参见[状态码](https://support.huaweicloud.com/api-gaussdb/gaussdb_api_194.html)。 #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-gaussdb/gaussdb_api_195.html)。