Updated on 2025-09-04 GMT+08:00

Creating a StarRocks Instance

Function

This API is used to create a StarRocks instance. Before calling this API:

URI

POST /v3/{project_id}/instances/{instance_id}/starrocks

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID of a tenant in a region.

To obtain this value, see Obtaining a Project ID.

Constraints

N/A

Range

The value contains 32 characters. Only letters and digits are allowed.

Default Value

N/A

instance_id

Yes

String

Definition

TaurusDB instance ID, which is compliant with the UUID format.

Constraints

N/A

Range

The value contains 36 characters with a suffix of in07. 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. To obtain this value, call the IAM API for obtaining a user token.

The value of X-Subject-Token in the response header is the token value.

Constraints

N/A

Range

N/A

Default Value

N/A

Content-Type

Yes

String

Definition

Content type.

Constraints

N/A

Range

application/json

Default Value

application/json

X-Language

No

String

Definition

Request language type.

Constraints

N/A

Range

  • en-us

  • zh-cn

Default Value

en-us

Table 3 Request body parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Definition

Instance name. Instances of the same type can have the same name under the same tenant.

Constraints

N/A

Range

The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed. Chinese names are not supported.

Default Value

N/A

engine

Yes

engine object

Definition

Engine information.

Constraints

N/A

ha

Yes

ha object

Definition

Deployment information.

Constraints

N/A

fe_flavor_id

Yes

String

Definition

Specification ID of the frontend node. You can use the value of id in the response to querying HTAP specifications.

Constraints

N/A

Range

N/A

Default Value

N/A

be_flavor_id

Yes

String

Definition

Specification ID of the backend node. You can use the value of id in the response to querying HTAP specifications.

Constraints

N/A

Range

N/A

Default Value

N/A

db_root_pwd

Yes

String

Definition

Database password.

Constraints

N/A

Range

The password consists of 8 to 32 characters and contains at least three types of the following: uppercase letters, lowercase letters, digits, and special characters (~!@#$%^*-_=+?,()&|.). You are advised to enter a strong password to improve security and prevent security risks such as brute force cracking. If you enter a weak password, the system automatically determines that the password is invalid.

Default Value

N/A

fe_count

Yes

Integer

Definition

Number of frontend nodes.

Constraints

N/A

Range

  • The value is fixed to 1 for a single-node instance.

  • For a cluster instance, the value ranges from 3 to 10.

Default Value

N/A

be_count

Yes

Integer

Definition

Number of backend nodes.

Constraints

N/A

Range

  • The value is fixed to 1 for a single-node instance.

  • For a cluster instance, the value ranges from 3 to 10.

Default Value

N/A

az_mode

Yes

String

Definition

AZ type.

Range

Currently, only single AZ is supported.

fe_volume

Yes

fe_volume object

Storage information of the frontend node.

be_volume

Yes

be_volume object

Storage information of the backend node.

az_code

Yes

String

AZ code.

time_zone

No

String

Definition

Time zone.

Range

The default time zone is UTC+08:00.

tags_info

Yes

tags_info object

Tag information.

security_group_id

No

String

Definition

Security group ID. By default, the value is the same as the ID of the security group associated with the TaurusDB instance.

Range

N/A

pay_info

No

pay_info object

Payment information. This parameter is mandatory for yearly/monthly billing.

region_code

No

String

AZ. This parameter is mandatory for yearly/monthly billing.

Table 4 engine

Parameter

Mandatory

Type

Description

type

Yes

String

Definition

Engine type.

Constraints

N/A

Range

Only StarRocks is supported.

Default Value

N/A

version

Yes

String

Definition

Major version number of the engine.

Constraints

N/A

Range

N/A

Default Value

N/A

Table 5 ha

Parameter

Mandatory

Type

Description

mode

Yes

String

Definition

Deployment mode.

Constraints

N/A

Range

  • Single: single-node deployment

  • Cluster: cluster deployment

Default Value

N/A

Table 6 fe_volume

Parameter

Mandatory

Type

Description

io_type

Yes

String

Storage type. The value can be obtained from the response to querying HTAP engine resources.

capacity_in_gb

Yes

Integer

Definition

Disk capacity, in GB.

Increment: 10 GB

Range

N/A

Table 7 be_volume

Parameter

Mandatory

Type

Description

io_type

Yes

String

Storage type. The value can be obtained from the response to querying HTAP engine resources.

capacity_in_gb

Yes

Integer

Definition

Disk capacity, in GB.

Increment: 10 GB

Range

N/A

Table 8 tags_info

Parameter

Mandatory

Type

Description

sys_tags

Yes

Array of sys_tags objects

System tags.

Table 9 sys_tags

Parameter

Mandatory

Type

Description

key

Yes

String

Tag key.

value

Yes

String

Tag value.

Table 10 pay_info

Parameter

Mandatory

Type

Description

pay_model

No

String

Definition

Billing mode. The default value is 0. This parameter is mandatory for yearly/monthly billing.

Range

  • 0: pay-per-use

  • 1: yearly/monthly

period

No

String

Yearly/monthly subscription period. This parameter is mandatory for yearly/monthly billing.

period_type

No

String

Definition

Subscription period type. This parameter is mandatory for yearly/monthly billing.

Range

  • 2: monthly

  • 3: yearly

is_auto_renew

No

String

Definition

Whether to automatically renew the yearly/monthly subscription. This parameter is mandatory for yearly/monthly billing.

Range

  • 1: auto-renewal enabled

  • 0: auto-renewal disabled

Response Parameters

Status code: 201

Table 11 Response body parameters

Parameter

Type

Description

instance

instance object

Instance information.

job_id

String

Workflow ID.

Table 12 instance

Parameter

Type

Description

id

String

StarRocks instance ID, which is compliant with the UUID format.

az_code

String

AZ code.

az_mode

String

Definition

AZ type.

Range

single: single AZ

multi: multiple AZs

name

String

Instance name.

engine

engine object

Engine information.

vpc_id

String

VPC ID.

security_group_id

String

Security group ID.

sub_net_id

String

Subnet ID.

db_user

String

Database user. The default value is root.

port

Integer

Database port number. The default value is 3306.

ha_mode

String

Deployment mode.

pay_info

pay_info object

Billing information.

enable_ssl

Boolean

Whether to enable SSL.

status

String

Instance status.

region

String

Region where the instance is deployed.

tags_info

tags_info object

Instance tags.

Table 13 engine

Parameter

Type

Description

type

String

Engine type.

version

String

Major version number of the engine.

Table 14 pay_info

Parameter

Type

Description

pay_model

String

Definition

Billing mode.

Range

  • 0: pay-per-use

  • 1: yearly/monthly

Default Value

StarRocks instances support only pay-per-use billing. The default value is 0.

order_id

String

Yearly/monthly order ID.

period

String

Yearly/monthly subscription period.

period_type

String

Subscription period type.

is_auto_renew

String

Whether to automatically renew the yearly/monthly subscription.

Table 15 tags_info

Parameter

Type

Description

tags

Array of tags objects

User tags. This parameter is left blank by default.

sys_tags

Array of sys_tags objects

System tags.

Table 16 tags

Parameter

Type

Description

key

String

Tag key.

value

String

Tag value.

Table 17 sys_tags

Parameter

Type

Description

key

String

Tag key.

value

String

Tag value.

Status code: 400

Table 18 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 500

Table 19 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Request

Creating a DB instance

POST https://{endpoint}/v3/23a50154cf494ec9ad6883979a12db0a/instances/40dc4c5729f14aad893e2dcd5baf6a15in07/starrocks

{
  "name" : "htap-ff64",
  "engine" : {
    "type" : "star-rocks",
    "version" : "3.1"
  },
  "ha" : {
    "mode" : "Single"
  },
  "fe_flavor_id" : "afef3bfd-ac7c-32e1-ba44-c388acbb196a",
  "be_flavor_id" : "de565db8-0a96-37ea-9388-61167624712c",
  "db_root_pwd" : "Test@123!",
  "fe_count" : 1,
  "be_count" : 1,
  "az_mode" : "single",
  "fe_volume" : {
    "io_type" : "SSD",
    "capacity_in_gb" : 50
  },
  "be_volume" : {
    "io_type" : "SSD",
    "capacity_in_gb" : 50
  },
  "az_code" : "az",
  "time_zone" : "UTC+08:00",
  "tags_info" : {
    "sys_tags" : [ {
      "key" : "_sys_enterprise_project_id",
      "value" : "0"
    } ]
  }
}

Example Response

Status code: 201

Success.

{
  "instance" : {
    "id" : "590031445ef845bb912d7fc8243db80cin17",
    "az_code" : "az1",
    "az_mode" : "single",
    "name" : "htap-ff64",
    "engine" : {
      "type" : "star-rocks",
      "version" : "3.1"
    },
    "vpc_id" : "d5a1a29b-1476-490f-9682-c1a59593e7b0",
    "security_group_id" : "967a0ac2-3cae-4e57-a49a-d0f6ff07dcc1",
    "sub_net_id" : "2ce0bc80-bfc5-4d5e-9b78-a7f91572e03b",
    "db_user" : "root",
    "port" : 3306,
    "ha_mode" : "Single",
    "pay_info" : {
      "pay_model" : "0",
      "order_id" : null,
      "period" : null,
      "period_type" : null,
      "is_auto_renew" : null
    },
    "enable_ssl" : false,
    "status" : "creating",
    "region" : "az",
    "tags_info" : {
      "tags" : [ ],
      "sys_tags" : [ {
        "key" : "_sys_enterprise_project_id",
        "value" : "0"
      } ]
    }
  },
  "job_id" : "cf0b7506-1505-450f-9d95-ce9d93b6b5c3"
}

Status Code

For details, see Status Codes.

Error Code

For details, see Error Codes.