Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ SQL Explorer/ Querying Full Data by SQL Statement
Updated on 2025-10-22 GMT+08:00
View PDF
Share

Querying Full Data by SQL Statement

Function

This API is used to query full data of a single SQL statement. Enhanced condition-based filtering is supported. For example, multiple conditions can be combined for SQL text query (using the query field), and the db_time field can be used for filtering based on conditions such as greater than, less than, and range.

Debugging

You can debug this API in API Explorer.

URI

POST /v3/{project_id}/instances/{instance_id}/list-full-sqls

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 body parameters

Parameter

Mandatory

Type

Description

node_id

No

String

Definition

Node ID.

Constraints

N/A

Range

N/A

Default Value

N/A

begin_time

Yes

String

Definition

Query start time.

Constraints

The value must use the format yyyy-mm-ddThh:mm:ssZ and conform to the ISO 8601 UTC standard. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset.

The plus sign (+) in the time zone must be URL-encoded to %2B, and the minus sign (-) in the time zone does not need to be encoded.

For example, in the Beijing time zone, the time zone offset is shown as +0800 and the value (2024-03-15T17:20:33+0800) of begin_time needs to be encoded as 2024-03-15T17:20:33%2B0800.

Range

The time range from begin_time to end_time cannot exceed 30 days.

Default Value

N/A

end_time

Yes

String

Definition

Query end time.

Constraints

The value must use the format yyyy-mm-ddThh:mm:ssZ and conform to the ISO 8601 UTC standard. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset.

The plus sign (+) in the time zone must be URL-encoded to %2B, and the minus sign (-) in the time zone does not need to be encoded.

For example, in the Beijing time zone, the time zone offset is shown as +0800 and the value (2024-03-16T17:20:33+0800) of end_time needs to be encoded as 2024-03-16T17:20:33%2B0800.

Range

The time range from begin_time to end_time cannot exceed 30 days.

Default Value

N/A

query

No

String

Definition

SQL text.

Constraints

N/A

Range

The value can contain 1 to 4,096 characters.

Default Value

N/A

sql_id

No

String

Definition

Normalized SQL ID.

Constraints

N/A

Range

N/A

Default Value

N/A

sql_exec_id

No

String

Definition

Unique SQL statement ID.

Constraints

N/A

Range

N/A

Default Value

N/A

transaction_id

No

String

Definition

Transaction ID.

Constraints

N/A

Range

N/A

Default Value

N/A

trace_id

No

String

Definition

Link ID.

Constraints

N/A

Range

N/A

Default Value

N/A

db_name

No

String

Definition

Database name.

Constraints

N/A

Range

N/A

Default Value

N/A

schema_name

No

String

Definition

Schema name.

Constraints

N/A

Range

N/A

Default Value

N/A

username

No

String

Definition

Username.

Constraints

N/A

Range

N/A

Default Value

N/A

client_addr

No

String

Definition

Client address.

Constraints

N/A

Range

N/A

Default Value

N/A

client_port

No

String

Definition

Client port.

Constraints

N/A

Range

N/A

Default Value

N/A

order_by

No

String

Definition

Sorting field.

Constraints

N/A

Range

begin_time: start time.

Default Value

begin_time

is_slow_sql

No

Boolean

Definition

Whether the SQL statement is slow.

Constraints

N/A

Range

  • true: The SQL statement is slow.
  • false: The SQL statement is not slow.

Default Value

N/A

order

No

String

Definition

Sorting mode, which can be ascending or descending.

Constraints

N/A

Range

  • DESC: descending order
  • desc: descending order
  • ASC: ascending order
  • asc: ascending order

Default Value

DESC

multi_queries

No

Array of MultiMergeCondition

Definition

Query conditions for field aggregation. Default value: [].

For details, see Table 4.

Constraints

Only full AND or full OR queries can be performed on the query field.

compare_conditions

No

Array of CompareCondition

Definition

Combined comparison query condition. You can combine conditions such as range, greater than, and less than for a specified filter field. Default value: []. For details, see Table 5.

Constraints

N/A

limit

No

Long

Definition

Maximum number of records returned by a query. For example, if this parameter is set to 10, a maximum of 10 records can be displayed.

Constraints

For version 25.5.0.1 and later in Huawei Cloud environments, this parameter is deprecated and do not need to be set. A system parameter is used to control the maximum number of records that can be returned. The default value is 200.

Range

[1, 1000]

Default Value

10
Table 4 MultiMergeCondition

Parameter

Type

Description

name

String

Definition

Name of the field to be queried.

Constraints

Only the character string query is supported.

Range

1 to 128 characters, including letters (case-sensitive), digits, and underscores (_)

Default Value

N/A

condition

String

Definition

Combined condition.

Constraints

N/A

Range

The value can only be and, or, AND or OR.

Default Value

N/A

values

Array of strings

Definition

Set of multiple search criteria. The value is a list of 1 to 5 characters.

Constraints

N/A

is_fuzzy

Boolean

Definition

Set of multiple search criteria.

Constraints

The value can only be true for fuzzy query.

Range

  • true: fuzzy search
  • false: exact match

Default Value

true
Table 5 CompareCondition

Parameter

Mandatory

Type

Description

name

Yes

String

Definition

Query field name. Currently, only specified numeric fields are supported.

Constraints

N/A

Range

  • db_time: valid DB time.
  • cpu_time: CPU time.
  • data_io_time: I/O time.
  • execution_time: execution time in the executor.

Default Value

N/A

enable_equal

No

Boolean

Definition

Whether to include the Equal to condition. If this parameter value is set to true, the boundary values (for min and max) are included in the range condition.

Constraints

N/A

Range

  • true: The range boundary values are included.
  • false: The range boundary values are not included.

Default Value

true

min

No

Long

Definition

Value for evaluating the minimum threshold (greater-than condition).

Constraints

N/A

Range

[0, 2^63-1]

Default Value

N/A

max

No

Long

Definition

Value for evaluating the maximum threshold (less-than condition).

Constraints

N/A

Range

[0, 2^63-1]

Default Value

N/A

value

No

Long

Definition

Value for evaluating the equality threshold (equal-to condition). The value parameter has the highest priority. If value is not left blank, the settings for min and max are ignored. If value is left blank, the min and max filtering conditions are enabled.

Constraints

N/A

Range

[0, 2^63-1]

Default Value

N/A

Response Parameters

Table 6 Response body parameters

Parameter

Type

Description

total_count

Integer

Definition

Total number of records.

Range

N/A

limit_count

Integer

Definition

Maximum number of records returned by a query. This parameter is used for frontend interaction control.

Range

N/A

full_sqls

Array of FullSqlRecord

Definition

Records of a single SQL statement.

For details, see Table 7.

parser

String

Definition

Reserved field, which is not involved in Huawei Cloud. Ignore it.

Range

N/A

cursor_time

String

Definition

Reserved field, which is not involved in Huawei Cloud. Ignore it.

Range

N/A
Table 7 FullSqlRecord

Parameter

Type

Description

id

String

Definition

Unique key ID of a SQL statement record.

Range

N/A

instance_id

String

Definition

Instance ID.

Range

N/A

node_id

String

Definition

Node ID.

Range

N/A

component_id

String

Definition

Component ID.

Range

N/A

db_name

String

Definition

Database name.

Range

N/A

schema_name

String

Definition

Schema name.

Range

N/A

username

String

Definition

Username.

Range

N/A

application_name

String

Definition

Name of the application that sends a request.

Range

N/A

client_addr

String

Definition

IP address of the client that initiated the request.

Range

N/A

client_port

String

Definition

Port number of the client that initiated the request.

Range

N/A

sql_id

String

Definition

Normalized SQL ID, which corresponds to the kernel parameter unique_sql_id.

Range

N/A

sql_exec_id

String

Definition

Unique SQL ID, which corresponds to the kernel parameter debug_query_id.

Range

N/A

transaction_id

String

Definition

Transaction ID, which corresponds to the kernel parameter debug_query_id.

Range

N/A

trace_id

String

Definition

Link ID.

Range

N/A

query

String

Definition

Normalized SQL statement.

Range

N/A

sql

String

Definition

Original SQL text after parsing.

Range

When track_stmt_parameter is enabled, variables in the collected SQL text are replaced with their actual values, so you can see the original SQL statement. However, for SQL text collected when track_stmt_parameter is disabled, the original values of the variables cannot be retrieved, and no content will be displayed here.

begin_time

String

Definition

Start time in the yyyy-mm-ddThh:mm:ss.SSSSSZ format.

Range

N/A

end_time

String

Definition

End time in the yyyy-mm-ddThh:mm:ss.SSSSSZ format.

Range

N/A

all_time

Long

Definition

Total execution time (unit: μs).

Range

N/A

db_time

Long

Definition

Valid DB time (unit: μs).

Range

N/A

cpu_time

Long

Definition

CPU time (unit: μs).

Range

N/A

data_io_time

Long

Definition

I/O time (unit: μs).

Range

N/A

execution_time

Long

Definition

Execution time in the executor (unit: μs).

Range

N/A

scan_lines

Long

Definition

Scanned rows.

Range

N/A

insert_rows

Long

Definition

Number of rows inserted.

Range

N/A

update_rows

Long

Definition

Number of rows updated.

Range

N/A

delete_rows

Long

Definition

Number of rows deleted.

Range

N/A

is_slow_sql

Boolean

Definition

Whether the SQL statement is slow.

Range

N/A

start_timestamp

Long

Definition

Start time of SQL statement execution. The value is a 13-digit standard timestamp, for example, 1754647168354.

Range

N/A

finish_timestamp

Long

Definition

End time of SQL statement execution. The value is a 13-digit standard timestamp, for example, 1754647168355.

Range

N/A

hit_rate

Double

Definition

SQL hit ratio.

This parameter is about to be brought offline. Do not use it.

Range

N/A

Example Request

Querying full data by SQL statement

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/4a89780fa1024361bcb855fed6aab89e/instances/cf9c879513144362bce2b3760ed81d3bin14/list-full-sqls
{
    "begin_time": "2025-08-08T08:59:29+0000",
    "end_time": "2025-08-08T09:59:29+0000",
    "compare_conditions": [{
            "name": "db_time",
            "min": 474,
            "max": 475,
            "enable_equal": true
        }
    ],
    "multi_queries": [{
            "name": "query",
            "condition": "AND",
            "is_fuzzy": true,
            "values": ["select node_name", "from pg_catalog.pgxc_node"]
        }
    ]
}

Example Response

{
    "parser": null,
    "total_count": 4,
    "limit_count": 1000,
    "cursor_time": null,
    "full_sqls": [
        {
            "id": "f084ca811d62f93af3dff2d508a981bc",
            "instance_id": "cf9c879513144362bce2b3760ed81d3bin14",
            "node_id": "b470c6297bb24c258e3eccf8dcaaa3f0no14",
            "component_id": "cn_5001",
            "query": "select node_name from pg_catalog.pgxc_node where nodeis_central;",
            "sql": "",
            "sql_id": "67570929",
            "sql_exec_id": "72620543991485094",
            "transaction_id": "0",
            "trace_id": "",
            "db_name": "postgres",
            "schema_name": "\"$user\",public",
            "username": "rdsAdmin",
            "begin_time": "2025-08-08 09:59:28 +0000",
            "end_time": "2025-08-08 09:59:28 +0000",
            "all_time": 424,
            "db_time": 474,
            "cpu_time": 417,
            "data_io_time": 0,
            "execution_time": 16,
            "scan_lines": 0,
            "update_rows": 0,
            "insert_rows": 0,
            "delete_rows": 0,
            "application_name": "cm_agent",
            "client_addr": "127.0.0.1",
            "client_port": 51698,
            "is_slow_sql": false,
            "hit_rate": 1.0,
            "start_timestamp": 1754647168354,
            "finish_timestamp": 1754647168355
        },
        {
            "id": "3118514c31fa176d98e1503a24a048fd",
            "instance_id": "cf9c879513144362bce2b3760ed81d3bin14",
            "node_id": "b470c6297bb24c258e3eccf8dcaaa3f0no14",
            "component_id": "cn_5001",
            "query": "select node_name from pg_catalog.pgxc_node where nodeis_central;",
            "sql": "",
            "sql_id": "67570929",
            "sql_exec_id": "72620543991483793",
            "transaction_id": "0",
            "trace_id": "",
            "db_name": "postgres",
            "schema_name": "\"$user\",public",
            "username": "rdsAdmin",
            "begin_time": "2025-08-08 09:57:40 +0000",
            "end_time": "2025-08-08 09:57:40 +0000",
            "all_time": 418,
            "db_time": 474,
            "cpu_time": 414,
            "data_io_time": 0,
            "execution_time": 22,
            "scan_lines": 0,
            "update_rows": 0,
            "insert_rows": 0,
            "delete_rows": 0,
            "application_name": "cm_agent",
            "client_addr": "127.0.0.1",
            "client_port": 51698,
            "is_slow_sql": false,
            "hit_rate": 1.0,
            "start_timestamp": 1754647060067,
            "finish_timestamp": 1754647060067
        },
        {
            "id": "b39f4a4f1e082ee2cd92522596394219",
            "instance_id": "cf9c879513144362bce2b3760ed81d3bin14",
            "node_id": "b470c6297bb24c258e3eccf8dcaaa3f0no14",
            "component_id": "cn_5001",
            "query": "select node_name from pg_catalog.pgxc_node where nodeis_central;",
            "sql": "",
            "sql_id": "67570929",
            "sql_exec_id": "72620543991483600",
            "transaction_id": "0",
            "trace_id": "",
            "db_name": "postgres",
            "schema_name": "\"$user\",public",
            "username": "rdsAdmin",
            "begin_time": "2025-08-08 09:57:23 +0000",
            "end_time": "2025-08-08 09:57:23 +0000",
            "all_time": 405,
            "db_time": 474,
            "cpu_time": 415,
            "data_io_time": 0,
            "execution_time": 19,
            "scan_lines": 0,
            "update_rows": 0,
            "insert_rows": 0,
            "delete_rows": 0,
            "application_name": "cm_agent",
            "client_addr": "127.0.0.1",
            "client_port": 51698,
            "is_slow_sql": false,
            "hit_rate": 1.0,
            "start_timestamp": 1754647043025,
            "finish_timestamp": 1754647043026
        },
        {
            "id": "bca651bfa3628029cea483db1ab629e6",
            "instance_id": "cf9c879513144362bce2b3760ed81d3bin14",
            "node_id": "b470c6297bb24c258e3eccf8dcaaa3f0no14",
            "component_id": "cn_5001",
            "query": "select node_name from pg_catalog.pgxc_node where nodeis_central;",
            "sql": "",
            "sql_id": "67570929",
            "sql_exec_id": "72620543991483104",
            "transaction_id": "0",
            "trace_id": "",
            "db_name": "postgres",
            "schema_name": "\"$user\",public",
            "username": "rdsAdmin",
            "begin_time": "2025-08-08 09:56:42 +0000",
            "end_time": "2025-08-08 09:56:42 +0000",
            "all_time": 420,
            "db_time": 475,
            "cpu_time": 410,
            "data_io_time": 0,
            "execution_time": 19,
            "scan_lines": 0,
            "update_rows": 0,
            "insert_rows": 0,
            "delete_rows": 0,
            "application_name": "cm_agent",
            "client_addr": "127.0.0.1",
            "client_port": 51698,
            "is_slow_sql": false,
            "hit_rate": 1.0,
            "start_timestamp": 1754647002918,
            "finish_timestamp": 1754647002918
        }
    ]
}

Status Codes

Error Codes

For details, see Error Codes.

Parent topic: SQL Explorer