Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ SQL Explorer/ Querying SQL Link Information

Updated on 2025-10-20 GMT+08:00

View PDF

Querying SQL Link Information

Function

This API is used to query full link information about a SQL statement execution (corresponding to the normalized SQL ID and unique SQL ID), including multidimensional time consumption statistics of each phase. For a distributed instance, you can query the full link of a SQL statement execution, including the time consumed by the SQL statement on both CNs and DNs. Before calling this API:

Learn how to authenticate this API.
Obtain the required region and endpoint.

Debugging

You can debug this API in API Explorer.

URI

GET /v3/{project_id}/instances/{instance_id}/full-sql/sql-trace

**Table 1** Parameter description
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID of a tenant in a region. To obtain the value, see Obtaining a Project ID. Constraints N/A Range The value can contain 32 characters. Only letters and digits are allowed. Default Value N/A
instance_id	Yes	String	Definition Instance ID, which uniquely identifies an instance. Constraints N/A Range The value can contain 36 characters. Only letters and digits are allowed. Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. You can obtain the token by calling the IAM API used to obtain a user token. After the request is processed, the value of X-Subject-Token in the message header is the token value. Constraints N/A Range N/A Default Value N/A
X-Language	No	String	Definition Language. Constraints N/A Range zh-cn en-us Default Value en-us

**Table 3** Request query parameters
Parameter	Mandatory	Type	Description
sql_id	No	String	Definition Normalized SQL ID, which corresponds to the kernel parameter unique_sql_id. Constraints N/A Range N/A Default Value N/A
sql_exec_id	No	String	Definition Unique SQL ID, which corresponds to the kernel parameter debug_query_id. Constraints N/A Range N/A Default Value N/A
transaction_id	No	String	Definition Transaction ID, which corresponds to the kernel parameter transaction_id. Constraints N/A Range N/A Default Value N/A
trace_id	No	String	Definition Link ID, which corresponds to the kernel field trace_id. Constraints N/A Range N/A Default Value N/A

Considering the characteristics of SQL Explorer, at least one of the preceding four parameters must be specified. Do not call this API without any filtering conditions.

Response Parameters

**Table 4** Response body parameters
Parameter	Type	Description
[Array element]	Array of NodeExecutionInfo	Definition SQL execution details on different nodes. For details, see Table 5.

**Table 5** NodeExecutionInfo
Parameter	Type	Description
component_id	String	Definition Component ID. Range N/A
node_id	String	Definition Node ID. Range N/A
transaction_id	String	Definition Transaction ID. Range N/A
sql_id	String	Definition Normalized SQL ID. Range N/A
sql_exec_id	String	Definition Unique SQL statement ID. Range N/A
db_name	String	Definition Database name. Range N/A
schema_name	String	Definition Schema name. Range N/A
start_time	String	Definition Statement start time, in the yyyy-mm-ddThh:mm: ssssssZ format. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, in the Beijing time zone, the time zone offset is shown as +0800. Range N/A
finish_time	String	Definition Statement end time, in the yyyy-mm-ddThh:mm: ssssssZ format. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, in the Beijing time zone, the time zone offset is shown as +0800. Range N/A
all_time	Long	Definition Total execution time (unit: μs). Range N/A
user_name	String	Definition Username. Range N/A
client_addr	String	Definition IP address of the client that initiated the request. Range N/A
client_port	Integer	Definition Port number of the client that initiated the request. Range N/A
trace_id	String	Definition Driver-specific trace ID, which is associated with an application request. Range N/A
application_name	String	Definition Name of the application that sends a request. Range N/A
session_id	String	Definition Session ID of a user. Range N/A
is_slow_sql	Boolean	Definition Whether the SQL statement is slow. Range N/A
execution_time_details	Object of ExecutionTimeDetail	Definition Execution time details. For details, see Table 6.

**Table 6** ExecutionTimeDetail
Parameter	Type	Description
resource_time	Object of ResourceTime	Definition Elapsed time for resources. For details, see Table 7.
kernel_time	Object of KernelTime	Definition Elapsed time for the kernel module. For details, see Table 9.
kernel_execution_time	Object of KernelExecutionTime	Definition Elapsed time for kernel execution. For details, see Table 11.
wait_event_time	Object of WaitEventTime	Definition Elapsed time for wait and statement lock events. For details, see Table 13.

**Table 7** ResourceTime
Parameter	Type	Description
all_time	Long	Definition Total time (unit: μs). Range N/A
resource_time_details	Object of ResourceTimeDetail	Definition Details about the elapsed time for resources. For details, see Table 8.

**Table 8** ResourceTimeDetail
Parameter	Type	Description
cpu_time	Long	Definition CPU time (unit: μs). Range N/A
data_io_time	Long	Definition I/O time (unit: μs). Range N/A
other_time	Long	Definition Other execution time (unit: μs). Range N/A

**Table 9** KernelTime
Parameter	Type	Description
all_time	Long	Definition Total time (unit: μs). Range N/A
kernel_time_details	Object of KernelTimeDetail	Definition Details about the elapsed time for the kernel. For details, see Table 10.

**Table 10** KernelTimeDetail
Parameter	Type	Description
parse_time	Long	Definition SQL parsing time (unit: μs). Range N/A
rewrite_time	Long	Definition SQL rewriting time (unit: μs). Range N/A
plan_time	Long	Definition SQL plan generation time (unit: μs). Range N/A
execution_time	Long	Definition Execution time in the executor (unit: μs). Range N/A
other_time	Long	Definition Other execution time (unit: μs). Range N/A

**Table 11** KernelExecutionTime
Parameter	Type	Description
all_time	Long	Definition Total time (unit: μs). Range N/A
kernel_execution_time_details	Object of KernelExecTimeDetail	Definition Details about the elapsed time for kernel execution. For details, see Table 12.

**Table 12** KernelExecTimeDetail
Parameter	Type	Description
execution_time	Long	Definition Execution time in the executor (unit: μs). Range N/A
other_time	Long	Definition Other execution time (unit: μs). Range N/A

**Table 13** WaitEventTime
Parameter	Type	Description
code_wait_event_time	Object of CodeWaitEventTime	Definition Elapsed time for code-related wait events. For details, see Table 14.
resource_wait_event_time	Object of ResourceWaitEventTime	Definition Elapsed time for resource-related wait events. For details, see Table 15.

**Table 14** CodeWaitEventTime
Parameter	Type	Description
all_time	Long	Definition Total time (unit: μs). Range N/A
code_wait_event_time_details	Object of EventTime	Definition Elapsed time for the kernel module. For details, see Table 20.

**Table 15** ResourceWaitEventTime
Parameter	Type	Description
all_time	Long	Definition Total time (unit: μs). Range N/A
resource_wait_event_time_details	Object of ResourceWaitEvenTimeDetail	Definition Details about the elapsed time for resource-related wait events. For details, see Table 16.
other_time	Long	Definition Elapsed time for non-event processing (unit: μs). Range N/A

**Table 16** ResourceWaitEvenTimeDetail
Parameter	Type	Description
data_io_time	Object of DataIoTime	Definition Elapsed time for I/O. For details, see Table 17.
lock_time	Object of LockTime	Definition Elapsed time for locks. For details, see Table 18.
lwlock_time	Object of LwlockTime	Definition Elapsed time for lightweight locks. For details, see Table 19.

**Table 17** DataIoTime
Parameter	Type	Description
all_time	Long	Definition Total time (unit: μs). Range N/A
data_io_time_details	Object of EventTime	Definition I/O time details on the kernel. For details, see Table 20.

**Table 18** LockTime
Parameter	Type	Description
all_time	Long	Definition Total time (unit: μs). Range N/A
lock_time_details	Object of EventTime	Definition Details about the time required for acquiring locks on the kernel. For details, see Table 20.

**Table 19** LwlockTime
Parameter	Type	Description
all_time	Long	Definition Total time (unit: μs). Range N/A
lwlock_time_details	Object of EventTime	Definition Details about the elapsed time for lightweight locks on the kernel. For details, see Table 20.

**Table 20** EventTime
Parameter	Type	Description
events	Array of TopTime	Definition Top 5 events by elapsed time. For details, see Table 21.
left_time	Long	Definition Elapsed time for other events (unit: μs). Range N/A
other_time	Long	Definition Elapsed time for non-event processing (unit: μs). Range N/A

**Table 21** TopTime
Parameter	Type	Description
event_name	String	Definition Event name. Range N/A
event_time	Long	Definition Elapsed time for event processing (unit: μs). Range N/A

Example Request

Querying the link information of a specified SQL statement

GET https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/4a89780fa1024361bcb855fed6aab89e/instances/cf9c879513144362bce2b3760ed81d3bin14/full-sql/sql-trace?sql_id=67570929&sql_exec_id=72620543991485094&id=f084ca811d62f93af3dff2d508a981bc

Example Response

[
    {
        "component_id": "cn_5001",
        "node_id": "b470c6297bb24c258e3eccf8dcaaa3f0no14",
        "transaction_id": "0",
        "sql_id": "67570929",
        "sql_exec_id": "72620543991485094",
        "db_name": "postgres",
        "schema_name": "\"$user\",public",
        "start_time": "2025-08-08 09:59:28 +0000",
        "finish_time": "2025-08-08 09:59:28 +0000",
        "all_time": 474,
        "user_name": "rdsAdmin",
        "client_addr": "127.0.0.1",
        "client_port": 51698,
        "trace_id": "",
        "application_name": "cm_agent",
        "session_id": "140316080338496",
        "is_slow_sql": false,
        "execution_time_details": {
            "resource_time": {
                "all_time": 474,
                "resource_time_details": {
                    "cpu_time": 417,
                    "data_io_time": 0,
                    "other_time": 57
                }
            },
            "kernel_time": {
                "all_time": 474,
                "kernel_time_details": {
                    "parse_time": 21,
                    "rewrite_time": 3,
                    "plan_time": 132,
                    "execution_time": 16,
                    "other_time": 318
                }
            },
            "kernel_execution_time": {
                "all_time": 474,
                "kernel_execution_time_details": {
                    "execution_time": 16,
                    "other_time": 458
                }
            },
            "wait_event_time": {
                "code_wait_event_time": {
                    "all_time": 474,
                    "code_wait_event_time_details": {
                        "events": [
                            {
                                "event_name": "wait seq scan",
                                "event_time": 57
                            },
                            {
                                "event_name": "flush data",
                                "event_time": 28
                            },
                            {
                                "event_name": "wait xact commit command",
                                "event_time": 21
                            },
                            {
                                "event_name": "wait xact start command",
                                "event_time": 13
                            },
                            {
                                "event_name": "wait heap hot search buffer",
                                "event_time": 9
                            }
                        ],
                        "left_time": 0,
                        "other_time": 346
                    }
                },
                "resource_wait_event_time": {
                    "all_time": 474,
                    "resource_wait_event_time_details": {
                        "data_io_time": {
                            "all_time": 0,
                            "data_io_time_details": {
                                "events": [
                                    {
                                        "event_name": "BufHashTableSearch",
                                        "event_time": 16
                                    }
                                ],
                                "left_time": 0,
                                "other_time": 0
                            }
                        },
                        "lock_time": {
                            "all_time": 0,
                            "lock_time_details": {
                                "events": [],
                                "left_time": 0,
                                "other_time": 0
                            }
                        },
                        "lwlock_time": {
                            "all_time": 0,
                            "lwlock_time_details": {
                                "events": [],
                                "left_time": 0,
                                "other_time": 0
                            }
                        }
                    },
                    "other_time": 0
                }
            }
        }
    }
]

Status Codes

Normal
200
Abnormal
For details, see Status Codes.

Error Codes

For details, see Error Codes.

Parent topic: SQL Explorer

Previous topic: Querying Full Data by SQL Statement

Next topic: Querying Full SQL Statistics of an Instance

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot