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.

Parent topic: Queue-related APIs (Recommended)

Previous topic: Queue-related APIs (Recommended)

Next topic: Deleting a Queue