Creating a SQL Throttling Task

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.

Constraints

SQL ID-based and auto throttling is unavailable for 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 8.0 or later.

URI

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

**Table 1** Parameter description
Name	Mandatory	Description
project_id	Yes	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	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
task_scope	Yes	String	Definition Throttling task scope. Constraints N/A Range Currently, SQL and SESSION are supported. Default Value N/A
start_time	No	String	Definition Task start time. Constraints This parameter is mandatory when task_scope is set to SQL. The format must be yyyy-mm-ddThh:mm:ss+0000. Range Any time greater than or equal to the current time (UTC) minus two minutes Default Value N/A
end_time	No	String	Definition Task end time. Constraints This parameter is mandatory when task_scope is set to SQL. The format must be yyyy-mm-ddThh:mm:ss+0000. Range The time must be later than the task start time. Default Value N/A
limit_type	Yes	String	Definition Throttling type. Constraints N/A Range If task_scope is set to SQL, this parameter value can be SQL_ID or SQL_TYPE. If task_scope is set to SESSION, this parameter value can be SESSION_ACTIVE_MAX_COUNT. Default Value N/A
limit_type_value	Yes	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 Keywords. Constraints This parameter is mandatory 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
sql_model	No	String	Definition SQL template. Constraints If limit_type is set to SQLID, this parameter is mandatory. Range N/A Default Value N/A
parallel_size	Yes	Integer	Definition Maximum concurrency. Constraints An integer greater than or equal to 0. Range [0, 2147483647] Default Value N/A
cpu_utilization	No	Integer	Definition CPU usage threshold. Constraints This parameter is mandatory when limit_type is set to SESSION_ACTIVE_MAX_COUNT. 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 This parameter is mandatory when limit_type is set to SESSION_ACTIVE_MAX_COUNT. 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 Databases of the instance. Databases are separated by 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 CN information. 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_id	Yes	String	Definition ID of the SQL statement executed on the node. Constraints If limit_type is set to SQL_ID, this parameter value must be the same as that of limit_type_value. Range N/A Default Value N/A

Response Parameters

**Table 5** Response body parameters
Parameter	Type	Description
task_id	String	Definition Throttling task ID. Range N/A
task_scope	String	Definition Throttling task scope. Range Currently, SQL and SESSION are supported.
limit_type	String	Definition Throttling task type. Range If task_scope is set to SQL, this parameter value can be SQL_ID or SQL_TYPE. If task_scope is set to SESSION, this parameter value can be SESSION_ACTIVE_MAX_COUNT.
limit_type_value	String	Definition Throttling task type value. Range When limit_type is set to SQL_ID, the value of this parameter is the SQL ID of the selected template. If limit_type is set to SQL_TYPE, this parameter value can be one of the following SQL operation types: SELECT, UPDATE, INSERT, DELETE, or MERGE. If limit_type is set to SESSION_ACTIVE_MAX_COUNT type, this parameter value can be CPU_OR_MEMORY.
databases	String	Definition Databases of the instance. Databases are separated by commas (,). Range N/A
task_name	String	Definition Throttling task name. Range N/A
sql_model	String	Definition SQL template. This parameter is returned only when the task type is SQL_ID. Range N/A
key_words	String	Definition Keyword. This parameter is returned only when the task type is SQL_TYPE. Range N/A
status	String	Definition Throttling task status. Range The value can be CREATING, UPDATING, DELETING, WAIT_EXECUTE, EXECUTING, TIME_OVER, DELETED, CREATE_FAILED, UPDATE_FAILED, DELETE_FAILED, EXCEPTION, or NODE_SHUT_DOWN.
instance_id	String	Definition Instance ID. Range N/A
rule_name	String	Definition Rule name. Range N/A
parallel_size	Integer	Definition Maximum concurrency. Range [0, 2147483647]
cpu_utilization	Integer	Definition CPU usage threshold. This parameter is returned with only its integer part retained when the task type is SESSION_ACTIVE_MAX_COUNT. Range [0,100)
memory_utilization	Integer	Definition Memory usage threshold. This parameter is returned with only its integer part retained when the task type is SESSION_ACTIVE_MAX_COUNT. Range [0,100)
start_time	String	Definition Start time of the throttling task. The format is yyyy-mm-ddThh:mm:ssZ. This parameter is returned when task_scope is set to SQL. Range N/A
end_time	String	Definition End time of the throttling task. The format is yyyy-mm-ddThh:mm:ssZ. This parameter is returned when task_scope is set to SQL. Range N/A
created	String	Definition Creation time. The format is yyyy-mm-ddThh:mm:ss+0000. Range N/A
updated	String	Definition Update time. The format is yyyy-mm-ddThh:mm:ss+0000. Range N/A
creator	String	Definition Creator. Range N/A
modifier	String	Definition Modifier. Range N/A
node_infos	Array of Table 6 objects	Definition CN node information list. If the type is SQLID, this value is returned and is the same as the value of the request parameter node_infos.
job_id	String	Definition Job ID. Range N/A

**Table 6** CreateLimitTaskNodeResult
Parameter	Type	Description
node_id	String	Definition Node ID. Range N/A
sql_id	String	Definition ID of the SQL statement executed on the node. Range N/A

Example Request

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

https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0611f1bd8b00d5d32f17c017f15b599f/instances/3d39c18788b54a919bab633874c159dfin14/limit-task
{
   "task_scope" : "SQL",
   "start_time" : "2023-06-06T01:47:20+0800",
   "end_time" : "2023-06-07T01:47:20+0800",
   "limit_type" : "SQL_ID",
   "limit_type_value" : "39b6a1a",
   "task_name" : "test1",
   "sql_model" : "select * from a where b = ?",
   "parallel_size" : 100,
   "node_infos" : [ {
      "node_id" : "46d996fdda594f58b17fe509061e0893no14",
     "sql_id" : "39b6a1a"
   } ]
}

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

https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0611f1bd8b00d5d32f17c017f15b599f/instances/3d39c18788b54a919bab633874c159dfin14/limit-task
{
   "task_scope" : "SQL",
   "start_time" : "2023-06-06T01:47:20+0800",
   "end_time" : "2023-06-07T01:47:20+0800",
   "limit_type" : "SQL_TYPE",
   "limit_type_value" : "select",
   "task_name" : "test1",
   "key_words" : "table1,id",
   "parallel_size" : 100,
   "databases" : "test1"
}

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

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

Example Response

{
   "task_id" : "59b6a1a278844ac48119d86512e0000",
   "task_scope" : "SQL",
   "task_name" : "test1",
   "limit_type" : "SQL_TYPE",
   "limit_type_value" : "select",
   "instance_id" : "cb651ac71c5a447685ef981e44a0422fin14",
   "key_words" : "test",
   "databases" : "test1",
   "status" : "creating",
   "parallel_size" : 100,
   "rule_name" : "dsa48119d86512e0000bin066a1a27",
   "start_time" : "2023-12-30T02:00:00Z",
   "end_time" : "2023-12-30T02:00:00Z",
   "created" : "2023-12-30T02:00:00Z",
   "updated" : "2023-12-30T02:00:00Z",
   "creator" : "dbs_rds_guangzhou_l00417929_01",
   "job_id" : "d8819ac11297598d06e591b5786aab86"
}