Manage On-Demand Cluster

Public Preview

This feature is available only with the Enterprise plan or higher.

This feature is currently available only in AWS us-west-2 and Azure East US regions. To use on-demand clusters in other regions, contact us.

This guide describes how to view, inspect, and drop on-demand clusters in Zilliz Cloud.

On-demand clusters provide compute for on-demand search workloads. They spin up when requests arrive and scale back to zero when idle, based on the auto-suspend timeout configured when the cluster is created.

To manage an on-demand cluster, you need to be a Project Admin in the target project. For details about the roles and permissions, see Manage Platform Users.

View all on-demand clusters

Use this operation to list the on-demand clusters in a project and region.

Via RESTful API

bash
curl --request GET \
     --url "${BASE_URL}/v2/clusters/onDemandClusters?projectId=proj-xxxxxxxxxxxxxxx&regionId=aws-us-west-2" \
     --header "Authorization: Bearer ${TOKEN}" \
     --header "Accept: application/json"

Example response:

bash
{
    "code": 0,
    "data": {
        "count": 2,
        "onDemandClusters": [
            {
                "projectId": "proj-xxxxxxxxxxxxxxx",
                "clusterId": "inxx-xxxxxxxxxxxxxxx",
                "clusterName": "Cluster-01",
                "regionId": "aws-us-west-2",
                "cuSize": 8,
                "status": "RUNNING",
                "endpoint": "https://proj-xxxxxxxxxxxxxxx.aws-us-west-2.api.zillizcloud.com",
                "privateLink": "",
                "createdBy": "john.doe@zilliz.com",
                "createTime": "2024-04-21T10:15:15Z",
                "autoSuspend": 60,
                "description": "An on-demand cluster for vector search workloads."
            },
            {
                "projectId": "proj-xxxxxxxxxxxxxxx",
                "clusterId": "inxx-xxxxxxxxxxxxxxx",
                "clusterName": "Cluster-02",
                "regionId": "aws-us-west-2",
                "status": "RUNNING",
                "cuSize": 8,
                "endpoint": "https://proj-xxxxxxxxxxxxxxx.aws-us-west-2.api.zillizcloud.com",
                "privateLink": "",
                "createdBy": "john.doe@zilliz.com",
                "createTime": "2024-04-21T10:15:16Z",
                "autoSuspend": 60,
                "description": "An on-demand cluster for vector search workloads."
            }
        ]
    }
}

Via web console

W3nYwPc0AhxRDWbjEsWceJGVnbh

In the Zilliz Cloud console, open the target project.

Go to On-Demand Compute > Clusters.

Review the on-demand cluster list, including cluster name, cluster ID, status, CU size, endpoint, creator, and creation time.

Check the details of an on-demand cluster

Use this operation to inspect one on-demand cluster by cluster ID.

Via RESTful API

bash
curl --request GET \
     --url "https://${BASE_URL}/v2/on-demand-compute?projectId=proj-09ee1f4b1151d5dd1edbc5&regionId=aws-us-west-2" \
     --header "Authorization: Bearer ${API_KEY}" \
     --header "Accept: application/json"

Example response:

bash
{
  "code": 0,
  "data": {
    "projectId": "proj-09ee1f4b1151d5dd1edbc5",
    "regionId": "aws-us-west-2",
    "status": "enabled"
  }
}

Via web console

XiWTwTJ3mhgjHBbS5dycYi4bn4c

In the Zilliz Cloud console, open the target project.

Go to On-Demand Compute > Clusters.

Click the target cluster to view its details.

Understand cluster status

An on-demand cluster automatically changes status based on request activity.

Status	Description
`RUNNING`	The cluster has active compute resources and can serve search or query requests.
`SUSPENDED`	The cluster has scaled to zero after the configured idle timeout. It stops incurring compute costs while suspended.
`DELETING`	The cluster is being dropped and cannot be used.

When a request arrives for a suspended on-demand cluster, Zilliz Cloud spins up compute resources for the workload. When no requests are received within the configured autoSuspend period, the cluster scales back to zero.

Rename an on-demand cluster

Via RESTful API

The following example modifies the cluster name. For details, see Update On-Demand Cluster.

bash
curl --request PATCH \
--url "${BASE_URL}/v2/clusters/onDemandClusters/${CLUSTER_ID}" \
--header "Authorization: Bearer ${TOKEN}" \
--header "OrgId: org-xxxxxxxxxxxxxxxxxxx" \
--header "Content-Type: application/json" \
-d '{
    "clusterName": "New Cluster Name"
}'

The following is an example output.

json
{
    "code": 0,
    "data": {
        "clusterId": "inxx-xxxxxxxxxxxxxxx",
        "prompt": "successfully submitted. Cluster is being upgraded, which is expected to take several minutes. You can access data about the creation progress and status of your cluster by DescribeCluster API. Once the cluster status is RUNNING, you may access your vector database using the SDK."
    }
}

Via Web console

1
Navigate to your target on-demand cluster.
2
Click on Actions and then select Rename.
3
Enter the new name of the cluster and click on Save.

Edit the description of an on-demand cluster

Via RESTful API

The following example modifies the cluster description. For details, see Update On-Demand Cluster.

bash
curl --request PATCH \
--url "${BASE_URL}/v2/clusters/onDemandClusters/${CLUSTER_ID}" \
--header "Authorization: Bearer ${TOKEN}" \
--header "OrgId: org-xxxxxxxxxxxxxxxxxxx" \
--header "Content-Type: application/json" \
-d '{
    "description": ""
}'

The following is an example output.

json
{
    "code": 0,
    "data": {
        "clusterId": "inxx-xxxxxxxxxxxxxxx",
        "prompt": "successfully submitted. Cluster is being upgraded, which is expected to take several minutes. You can access data about the creation progress and status of your cluster by DescribeCluster API. Once the cluster status is RUNNING, you may access your vector database using the SDK."
    }
}

Via Web console

1
Navigate to your target on-demand cluster.
2
Hover on the description and click on the Edit description icon.
3
Enter the new description of the cluster and click on Save.

Modify an on-demand cluster

You can modify the settings, such as the name, description, and auto-suspend settings of an on-demand cluster.

Via RESTful API

You can modify the name, description, auto-suspend time, and the number of query CUs of an existing on-demand cluster. For details, see Update On-Demand Cluster.

bash
export TOKEN="YOUR_API_KEY"
export CLUSTER_ID="inxx-xxxxxxxxxxxxxxx"

curl --request PATCH \
     --url "https://${BASE_URL}/v2/clusters/onDemandClusters/in07-7d6ac8697204a6a" \
     --header "Authorization: Bearer ${API_KEY}" \
     --header "Accept: application/json" \
     --header "Content-Type: application/json" \
     --data-raw '{
        "autoSuspend": "5m",
        "clusterName": "my-on-demand-updated",
        "description": "Updated on-demand cluster description",
        "cuSize": 32
      }'

The following is an example output.

bash
{
  "code": 0,
  "data": {
    "clusterId": "inxx-xxxxxxxxxxxxxxx",
    "prompt": "Successfully submitted."
  }
}

Via web console

You can modify the cluster name, description, auto-suspend time, and number of query CUs of an existing on-demand cluster via the web console.

Drop an on-demand cluster

🚧Danger

Once you drop an on-demand cluster, it is removed immediately and cannot be recovered. This action cannot be undone.

Via RESTful API

bash
curl --request DELETE \
     --url "${BASE_URL}/v2/clusters/onDemandClusters/inxx-xxxxxxxxxxxxxxx" \
     --header "Authorization: Bearer ${TOKEN}" \
     --header "Accept: application/json"

Example response:

bash
{
  "code": 0,
  "data": {
    "clusterId": "inxx-xxxxxxxxxxxxxxx",
    "status": "DELETING"
  }
}

Manage On-Demand Cluster

View all on-demand clusters

Via RESTful API

Via web console

In the Zilliz Cloud console, open the target project.

Go to On-Demand Compute > Clusters.

Review the on-demand cluster list, including cluster name, cluster ID, status, CU size, endpoint, creator, and creation time.

Check the details of an on-demand cluster

Via RESTful API

Via web console

In the Zilliz Cloud console, open the target project.

Go to On-Demand Compute > Clusters.

Click the target cluster to view its details.

Understand cluster status

Rename an on-demand cluster

Navigate to your target on-demand cluster.

Click on Actions and then select Rename.

Enter the new name of the cluster and click on Save.

Edit the description of an on-demand cluster

Navigate to your target on-demand cluster.

Hover on the description and click on the Edit description icon.

Enter the new description of the cluster and click on Save.

Modify an on-demand cluster

Drop an on-demand cluster

Via RESTful API

Via web console

In the Zilliz Cloud console, open the target project.

Go to On-Demand Compute > Clusters.

Select the target on-demand cluster.

Drop the cluster and confirm the operation.

View all on-demand clusters​

Via RESTful API​

Via web console​

In the Zilliz Cloud console, open the target project.

Go to On-Demand Compute > Clusters.

Review the on-demand cluster list, including cluster name, cluster ID, status, CU size, endpoint, creator, and creation time.

Check the details of an on-demand cluster​

Via RESTful API​

Via web console​

In the Zilliz Cloud console, open the target project.

Go to On-Demand Compute > Clusters.

Click the target cluster to view its details.

Understand cluster status​

Rename an on-demand cluster​

Navigate to your target on-demand cluster.

Click on Actions and then select Rename.

Enter the new name of the cluster and click on Save.

Edit the description of an on-demand cluster​

Navigate to your target on-demand cluster.

Hover on the description and click on the Edit description icon.

Enter the new description of the cluster and click on Save.

Modify an on-demand cluster​

Drop an on-demand cluster​

Via RESTful API​

Via web console​

In the Zilliz Cloud console, open the target project.

Go to On-Demand Compute > Clusters.

Select the target on-demand cluster.

Drop the cluster and confirm the operation.

Related topics​

View all on-demand clusters

Via RESTful API

Via web console

Check the details of an on-demand cluster

Via RESTful API

Via web console

Understand cluster status

Rename an on-demand cluster

Edit the description of an on-demand cluster

Modify an on-demand cluster

Drop an on-demand cluster

Via RESTful API

Via web console

Related topics