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 https://{Endpoint}/v3/{project_id}/instances/{instance_id}/limit-task

**Table 1** Parameter description
Parameter	Mandatory	Description
project_id	Yes	Explanation: Project ID of a tenant in a region. For details about how to obtain the value, see Obtaining a Project ID. Restrictions: None Value range: The value can contain 32 characters. Only letters and digits are allowed. Default value: None
instance_id	Yes	Instance ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	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.
X-Language	No	String	Language. Default value: en-us Value range: zh-cn en-us

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
task_scope	Yes	String	Task scope. Currently, SQL and SESSION are supported.
start_time	No	String	Task start time. This parameter is mandatory when task_scope is set to SQL. Value range: two minutes later than or equal to the current time (UTC time) The format must be yyyy-mm-ddThh:mm:ss+0000.
end_time	No	String	Task end time. This parameter is mandatory when task_scope is set to SQL. Value range: later than the task start time. The format must be yyyy-mm-ddThh:mm:ss+0000.
limit_type	Yes	String	Throttling type. When task_scope is set to SQL, the value can be SQL_ID or SQL_TYPE. When task_scope is set to SESSION, the value can be SESSION_ACTIVE_MAX_COUNT.
limit_type_value	Yes	String	Throttling type value. 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.
key_words	No	String	Keyword. This parameter is mandatory when limit_type is set to SQL_TYPE. 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.
task_name	Yes	String	Name of the SQL throttling task. The value can contain up to 100 characters. Only uppercase letters, lowercase letters, underscores (_), digits, and dollar signs ($) are allowed.
sql_model	No	String	SQL template. If limit_type is set to SQLID, this parameter is mandatory.
parallel_size	Yes	Integer	Maximum concurrency. The value can be 0 or a positive integer. Value range: [0, 2147483647]
cpu_utilization	No	Integer	CPU usage threshold. The value is an integer ranging from [0, 100). 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.
memory_utilization	No	Integer	Memory usage threshold. The value is an integer ranging from [0, 100). 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.
databases	No	String	Databases of the instance. Databases are separated by commas (,). This parameter is mandatory when limit_type is set to SQL_TYPE.
node_infos	No	Array of objects	CN information. For details, see Table 4. This parameter is mandatory when limit_type is set to SQL_ID.

**Table 4** CreateLimitTaskNodeOption
Parameter	Mandatory	Type	Description
node_id	Yes	String	Node ID.
sql_id	Yes	String	ID of the SQL statement executed on the node. If limit_type is set to SQL_ID, the value of this parameter must be the same as that of limit_type_value.

Response Parameters

**Table 5** Response body parameters
Parameter	Type	Description
task_id	String	Throttling task ID.
task_scope	String	Throttling task scope.
limit_type	String	Throttling task type.
limit_type_value	String	Throttling task type value.
databases	String	Databases of the instance. Databases are separated by commas (,).
task_name	String	Throttling task name.
sql_model	String	SQL template. This parameter is returned only when the task type is SQL_ID.
key_words	String	Keyword. This parameter is returned only when the task type is SQL_TYPE.
status	String	Throttling task status. The value can be CREATING, UPDATING, DELETING, WAIT_EXECUTE, EXCUTING, TIME_OVER, DELETED, CREATE_FAILED, UPDATE_FAILED, DELETE_FAILED, EXCEPTION or NODE_SHUT_DOWN.
instance_id	String	Instance ID.
rule_name	String	Rule name.
parallel_size	Integer	Maximum concurrency.
cpu_utilization	Integer	CPU usage threshold. This parameter is returned with only its integer part retained when the task type is SESSION_ACTIVE_MAX_COUNT.
memory_utilization	Integer	Memory usage threshold. This parameter is returned with only its integer part retained when the task type is SESSION_ACTIVE_MAX_COUNT.
start_time	String	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.
end_time	String	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.
created	String	Creation time. The format is yyyy-mm-ddThh:mm:ss+0000.
updated	String	Update time. The format is yyyy-mm-ddThh:mm:ss+0000.
creator	String	Creator.
modifier	String	Modifier.
node_infos	Array of Table 6 objects	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	Job ID.

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

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"
}