Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ SQL Throttling/ Creating a SQL Throttling Task (v3.1)

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

View PDF

Creating a SQL Throttling Task (v3.1)

Function

This API is used to create a SQL throttling task based on the specific scope and type. 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.

Constraints

Autonomous throttling (auto throttling for short) is unavailable to distributed instances.
SQL throttling cannot be performed for system-level users (such as root).
Each instance supports a maximum of 1,000 throttling tasks.
For a keyword-based throttling task, keywords are separated by commas (,), and the sequence of keywords is not distinguished.
SQL throttling is available only for DB instances of version V2.0-8.0 or later.

URI

POST /v3.1/{project_id}/instances/{instance_id}/limit-task

**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. The value of X-Subject-Token in the response 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
task_scope	Yes	String	Definition Throttling task scope. Currently, SQL and SESSION are supported. Constraints N/A Range SQL SESSION Default Value N/A
start_time	No	String	Definition Task start time. If the value is earlier than the current time, the time obtained by subtracting two minutes from the current time is used. Constraints This parameter is mandatory when task_scope is set to SQL. Range The time format must be yyyy-mm-ddThh:mm:ssZ. The current time is the UTC time. Default Value N/A
end_time	No	String	Definition Task end time. Constraints This parameter is mandatory when task_scope is set to SQL. Range The value must be later than the task start time. The format must be yyyy-mm-ddThh:mm:ssZ. The current time is the UTC time. Default Value N/A
sql_model	No	String	Definition SQL template. Constraints This parameter is mandatory if limit_type is set to SQLID. Range N/A Default Value N/A
limit_type	Yes	String	Definition Throttling type. Constraints N/A Range When task_scope is set to SQL, this parameter value can be SQL_ID or SQL_TYPE. When task_scope is set to SESSION, this parameter value can be SESSION_ACTIVE_MAX_COUNT. Default Value N/A
limit_type_value	No	String	Definition Throttling type value. Constraints N/A Range When limit_type is set to SQL_ID, the value of this parameter is the SQL ID of the selected template. When limit_type is set to SQL_TYPE, the value of this parameter can be select, update, insert, delete, or merge. When limit_type is set to SESSION_ACTIVE_MAX_COUNT, the value of this parameter can only be CPU_OR_MEMORY. Default Value N/A
key_words	No	String	Definition Keyword. Constraints This parameter is mandatory only when limit_type is set to SQL_TYPE. Range You can enter 2 to 100 keywords and separate multiple keywords by commas (,). Each keyword can contain 2 to 64 characters and cannot start and end with a space. The specifical characters ("\{}) and null are not allowed. Default Value N/A
task_name	Yes	String	Definition Throttling task name. Constraints N/A Range The value can contain up to 100 characters. Only letters, underscores (_), digits, and dollar signs ($) are allowed. Default Value N/A
parallel_size	Yes	Integer	Definition Maximum concurrency. Constraints N/A Range The value can be 0 or a positive integer. Value range: 0 to 2147483647 Default Value N/A
cpu_utilization	No	Integer	Definition CPU usage threshold. Constraints If limit_type is set to SESSION_ACTIVE_MAX_COUNT, this parameter is mandatory. This parameter and memory_utilization cannot be both set to 0. If you only need one of them for throttling, set the other threshold to 0. Range The value is an integer in the range [0,100). Default Value N/A
memory_utilization	No	Integer	Definition Memory usage threshold. Constraints If limit_type is set to SESSION_ACTIVE_MAX_COUNT, this parameter is mandatory. This parameter and cpu_utilization cannot be both set to 0. If you only need one of them for throttling, set the other threshold to 0. Range The value is an integer in the range [0,100). Default Value N/A
databases	No	String	Definition Database names. Throttling is applied only to the specified databases. Separate multiple names with commas (,). Constraints This parameter is mandatory when limit_type is set to SQL_TYPE. Range N/A Default Value N/A
node_infos	No	Array of objects	Definition Node information list. The number of objects in the list cannot exceed 10. For details, see Table 4. Constraints This parameter is mandatory when limit_type is set to SQL_ID.

**Table 4** CreateLimitTaskNodeOption
Parameter	Mandatory	Type	Description
node_id	Yes	String	Definition Node ID. Constraints It must be a node ID of the current instance. Range N/A Default Value N/A
sql_ids	Yes	Array of strings	Definition IDs of SQL statements executed on a node. Constraints Up to 10 SQL IDs are allowed per node. Range N/A Default Value N/A

Response Parameters

**Table 5** Response body parameters
Parameter	Type	Description
job_id	String	Definition Job ID. Range N/A

Example Request

Creating a throttling task whose scope is SQL and type is SQL_ID

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0611f1bd8b00d5d32f17c017f15b599f/instances/3d39c18788b54a919bab633874c159dfin14/limit-task
{
    "limit_type": "SQL_ID",
    "task_name": "t_limit",
    "limit_type_value": "2983157089",
    "task_scope": "SQL",
    "sql_model": "select * from t_limit;",
    "parallel_size": 2,
    "start_time": "2025-09-18T03:16:17+0000",
    "end_time": "2025-09-18T04:16:22+0000",
    "node_infos": [
        {
            "node_id": "a2a8c1f02782475ea3ac73e34ffe5dd8no14",
            "sql_ids": [
                "2983157089"
            ]
        }
    ],
    "databases": "t_limit"
}

Creating a throttling task whose scope is SQL and type is SQL_TYPE

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0611f1bd8b00d5d32f17c017f15b599f/instances/3d39c18788b54a919bab633874c159dfin14/limit-task
{
	"limit_type": "SQL_TYPE",
	"task_name": "t_limit_key_word",
	"limit_type_value": "select",
	"task_scope": "SQL",
	"parallel_size": 2,
	"start_time": "2025-09-18T08:49:07+0000",
	"end_time": "2025-09-18T08:55:13+0000",
	"key_words": "abc,def",
	"databases": "db_ecs_fe1,db_liujian,t_limit"
}

Creating a throttling task whose scope is SESSION and type is SESSION_ACTIVE_MAX_COUNT

POST https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0611f1bd8b00d5d32f17c017f15b599f/instances/3d39c18788b54a919bab633874c159dfin14/limit-task
{
	"parallel_size": 0,
	"task_name": "t_limit_resource",
	"cpu_utilization": 10,
	"memory_utilization": 33,
	"limit_type": "SESSION_ACTIVE_MAX_COUNT",
	"limit_type_value": "CPU_OR_MEMORY",
	"task_scope": "SESSION"
}

Example Response

{ 
  "job_id" : "d8819ac11297598d06e591b5786aab86" 
}

Status Code

Normal
202
Abnormal
For details, see Status Codes.

Error Codes

For details, see Error Codes.

Parent topic: SQL Throttling

Previous topic: SQL Throttling

Next topic: Modifying a SQL Throttling Task (v3.1)

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