Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ SQL Throttling/ Creating a SQL Throttling Task
Updated on 2025-08-19 GMT+08:00

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:

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

Status Codes

Error Codes

For details, see Error Codes.