Updated on 2024-08-19 GMT+08:00

Creating a Queue

Function

This API is used to create a queue. The queue will be bound to specified compute resources.

It takes 5 to 15 minutes to start a job using a new queue for the first time.

URI

  • URI format

    POST /v1.0/{project_id}/queues

  • Parameter description
    Table 1 URI parameter

    Parameter

    Mandatory

    Type

    Description

    project_id

    Yes

    String

    Project ID, which is used for resource isolation. For details about how to obtain its value, see Obtaining a Project ID.

Request

Table 2 Request parameters

Parameter

Mandatory

Type

Description

queue_name

Yes

String

Name of a newly created resource queue. The name can contain only digits, letters, and underscores (_), but cannot contain only digits or start with an underscore (_). Length range: 1 to 128 characters.

NOTE:

The queue name is case-insensitive. The uppercase letters will be automatically converted to lowercase letters.

queue_type

No

String

Queue type. The options are as follows:

  • sql: Queues used to run SQL jobs
  • general: Queues used to run Flink and Spark Jar jobs.
NOTE:

If the type is not specified, the default value sql is used.

description

No

String

Description of a queue.

cu_count

Yes

Integer

Minimum number of CUs that are bound to a queue. Currently, the value can only be 16, 64, or 256.

charging_mode

No

Integer

Billing mode of a queue. This value can only be set to 1, indicating that the billing is based on the CUH used.

enterprise_project_id

No

String

Enterprise project ID. The value 0 indicates the default enterprise project.

NOTE:

Users who have enabled Enterprise Management can set this parameter to bind a specified project.

platform

No

String

CPU architecture of compute resources.

  • x86_64

resource_mode

No

Integer

Queue resource mode. The options are as follows:

0: shared resource mode

1: dedicated resource mode

labels

No

Array of Strings

Tag information of the queue to be created. Currently, the tag information includes whether the queue is cross-AZ (JSON string). The value can only be 2, that is, a dual-AZ queue whose compute resources are distributed in two AZs is created.

feature

No

String

Type of image used by the queue. The options are:

  • basic: basic type
  • ai: AI-enhanced (Only the SQL x86_64 dedicated queue supports this option.)

The default value is basic.

NOTE:

AI-enhanced means that the queue is loaded with an AI image that integrates algorithm packages related to AI on top of the basic image.

tags

No

Array of objects

Queue tags for identifying cloud resources. A tag consists of a key and tag value. For details, see Table 3.

Table 3 tags parameters

Parameter

Mandatory

Type

Description

Key

Yes

String

Tag key.
NOTE:

A tag key can contain a maximum of 128 characters. Only letters, digits, spaces, and special characters (_.:=+-@) are allowed, but the value cannot start or end with a space or start with _sys_.

value

Yes

String

Tag value.
NOTE:

A tag value can contain a maximum of 255 characters. Only letters, digits, spaces, and special characters (_.:=+-@) are allowed. The value cannot start or end with a space.

Response

Table 4 Response parameters

Parameter

Mandatory

Type

Description

is_success

No

Boolean

Indicates whether the request is successfully executed. Value true indicates that the request is successfully executed.

message

No

String

System prompt. If execution succeeds, the parameter setting may be left blank.

queue_name

No

String

Name of the created queue.

NOTE:

The queue name is case-insensitive. The uppercase letters will be automatically converted to lowercase letters.

Example Request

Create a dedicated general-purpose queue named queue1, with specifications of 16 CUs and compute resources distributed in two AZs.

{
    "queue_name": "queue1",
    "description": "test",
    "cu_count": 16,
    "resource_mode": 1,
    "enterprise_project_id": "0",
    "queue_type": "general",
    "labels": ["multi_az=2"]
}

Creating a queue in a specified elastic resource pool

{
    "queue_name": "queue2",
    "description": "test_esp",
    "cu_count": 16,
    "resource_mode": 1,
    "enterprise_project_id": "0",
    "queue_type": "general",
    "labels": ["multi_az=2"],
    "elastic_resource_pool_name": "elastic_pool_0622_10"
}

Example Response

{
  "is_success": true,
  "message": "",
  "queue_name": "queue1"
}

Status Codes

Table 5 describes the status code.

Table 5 Status codes

Status Code

Description

200

The job is created successfully.

400

Request error.

500

Internal service error.

Error Codes

If an error occurs when this API is invoked, the system does not return the result similar to the preceding example, but returns the error code and error information. For details, see Error Codes.