Updated on 2025-08-06 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

    Definition

    Project ID, which is used for resource isolation. For how to obtain a project ID, see Obtaining a Project ID.

    Example: 48cc2c48765f481480c7db940d6409d1

    Constraints

    None

    Range

    The value can contain up to 64 characters. Only letters and digits are allowed.

    Default Value

    None

Request Parameters

Table 2 Request parameters

Parameter

Mandatory

Type

Description

queue_name

Yes

String

Name of the new queue

Definition

Name of the new queue

Constraints

  • The name cannot contain only digits or start with an underscore (_). Only digits, letters, and underscores (_) are allowed.
  • The value can contain up to 128 characters.
  • The queue name is case-insensitive. Uppercase letters will be automatically converted to lowercase letters.

Range

None

Default Value

None

queue_type

No

String

Definition

Queue type

Constraints

If not specified, the default value sql is used.

Range

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

Default Value

None

description

No

String

Definition

Queue description

Constraints

None

Range

None

Default Value

None

cu_count

Yes

Integer

Definition

Minimum number of CUs bound to a queue

Constraints

None

Range

The options are 16, 64, and 256.

Default Value

None

charging_mode

No

Integer

Definition

Billing mode of a queue

Constraints

None

Range

The value can only be 1, indicating that the billing is based on the CUH.

Default Value

None

enterprise_project_id

No

String

Definition

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

Constraints

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

Range

None

Default Value

None

platform

No

String

Definition

CPU architecture of queue compute resources

Constraints

None

Range

  • x86_64

Default Value

None

resource_mode

No

Integer

Definition

Queue resource mode

Constraints

None

Range

0: shared resource mode

1: dedicated resource mode

Default Value

None

labels

No

Array of Strings

Definition

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.

Constraints

None

Range

None

Default Value

None

feature

No

String

Definition

Type of images used by the queue

Constraints

None

Range

  • basic: basic type
  • ai: AI-enhanced (available only for SQL x86_64 dedicated queues). An AI image is loaded to the queue. The image integrates AI-related algorithm packages based on the base image.

Default Value

The default value is basic.

tags

No

Array of objects

Definition

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

Constraints

None

Range

None

Default Value

None

elastic_resource_pool_name

No

String

Definition

Name of the elastic resource pool the new queue belongs to

Constraints

The name can contain only digits, lowercase letters, and underscores (_), but cannot contain only digits or start with an underscore (_).

The value can contain 1 to 128 characters.

To add a queue to an elastic resource pool, set resource_mode to dedicated. Otherwise, this parameter does not take effect.

Range

None

Default Value

None

engine

No

String

Definition

Engine type of the queue

Constraints

This parameter is available only when queue_type is set to sql.

Range

The options are spark and hetuEngine.

  • spark: Spark engine
  • hetuEngine: HetuEngine engine

For details about the engine types and descriptions, see DLI Overview.

Default Value

The default value is spark.

properties

No

object

Definition

Queue properties. For details, see Table 4.

Constraints

Currently, Spark Native attributes can be set only in the following regions:
  • AP-Bangkok
  • AP-Singapore

Range

For details, see Table 4.

Default Value

None

Table 3 tags parameters

Parameter

Mandatory

Type

Description

Key

Yes

String

Definition

Tag key

Constraints

None

Range

A tag key can contain up to 128 characters, cannot start or end with a space, and cannot start with _sys_. Only letters, digits, spaces, and the following special characters are allowed: _.:+-@

Default Value

None

value

Yes

String

Definition

Tag value

Constraints

None

Range

A tag value can contain up to 255 characters. Only letters, digits, spaces, and the following special characters are allowed: _.:+-@

Default Value

None

Table 4 properties parameter descriptions

Parameter

Mandatory

Type

Description

computeEngine.spark.nativeEnabled

No

String

Definition

Spark Native is a core component of Apache Spark designed to enhance the performance of Spark SQL computations. By utilizing vectorized C++ acceleration libraries, it accelerates the performance of Spark operators. Enables the Spark Native engine to improve Spark SQL job performance and reduce CPU and memory usage.

Whether to enable Spark Native for a queue. This function can be currently enabled for Scan and Filter operators.

Constraints

Modifying the properties of an existing queue requires a restart for the changes to take effect.

Range

Currently, Spark Native can be enabled only for Scan and Filter operators.

  • Scan: The Scan operator is typically triggered by query statements, such as select * from test_table.
    Spark Native can be enabled for Scan operators only when the following conditions are met:
    • Hive tables and datasource tables in Parquet format
    • Datasource tables in ORC format
  • Filter: The Filter operator is typically triggered by WHERE clauses, such as select * from test_table where id = xxx.

    Using the EXPLAIN statement, you can view the types of operators triggered by SQL commands, for example, Explain select * from test_table.

Default Value

None

Response Parameters

Table 5 Response parameters

Parameter

Mandatory

Type

Description

is_success

No

Boolean

Definition

Whether the request is successfully executed. true indicates that the request is successfully executed.

Range

None

message

No

String

Definition

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

Range

None

queue_name

No

String

Definition

Name of the created queue. The queue name is case-insensitive. Uppercase letters will be automatically converted to lowercase letters.

Range

None

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 6 describes the status codes.

Table 6 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.