Create PCU groups in Astra DB

The Astra DB PCU management features are available only for public preview to qualified participants. Development is ongoing, and the features and functionality are subject to change. This preview is governed by your Agreement and the DataStax Preview Terms.

This preview covers two sets of features:

Core PCU management: Create PCU groups, edit PCU groups, and view PCU group usage
Flexible capacity workloads: Select a workload type in the Astra Portal, park PCU groups, and delete PCU groups

DataStax grants access to each set of features separately. To inquire about access to these features, contact your DataStax account representative.

When you create Provisioned Capacity Unit (PCU) groups, you create PCU subscriptions that define the number of reserved and hourly units that are available to the databases that you assign to each group. Each PCU group represents a separate PCU subscription.

Prerequisites

Before you create PCU groups, review the following requirement and considerations.

To create a PCU group, your Astra DB organization must be on an Enterprise plan, and you must have the Organization Administrator role, Billing Administrator role, or a similar custom role.

Billing implications and subscription terms

PCU groups have long-term billing implications, and they can have immediate performance impacts on your Astra DB Serverless databases if configured improperly. DataStax strongly recommends that you plan your PCU groups before you create any PCU groups in Astra DB.

These instructions assume you understand PCU group options and key terms, such as workload type, reserved capacity, minimum capacity, maximum capacity, and provision type.

To determine how many PCU groups you need, the configuration for each group, and the billing implications of each group, plan your PCU groups before you create them.

Immutable settings

You cannot edit the following settings after you create a PCU group:

Cloud provider
Region
Provision type
Cache optimization
Workload type
Reserved capacity, depending on the workload type:
- For committed capacity PCU groups, you cannot decrease the reserved capacity after creating the group. You can increase the reserved capacity at any time, but you cannot decrease the reserved capacity until subscription renewal.
- For flexible capacity PCU groups, you cannot change the reserved capacity. If you want to change a flexible capacity PCU group to a committed capacity PCU group, you must create a new committed capacity PCU group, move your databases to that group, and then delete the flexible capacity PCU group.

The cloud provider, region, provision type, and cache optimization settings apply to all of the group’s allocated capacity (reserved, minimum, and maximum). For example, if you enable cache optimization, then the group’s reserved, minimum, and maximum capacity is all cache optimized.

If you want to change an immutable setting, you must create a new PCU group with the desired settings, and then move your databases to that group.

You can delete flexible capacity PCU groups at any time, but you cannot delete committed capacity PCU groups until the subscription renewal period.

Before you create or edit a PCU group, DataStax recommends that you learn about PCU group options and plan your PCU groups.

Create a committed capacity PCU group

Committed capacity PCU groups include a long-term commitment to a specified amount of reserved capacity, which is billed at the Reserved Capacity Unit (RCU) rate. Optionally, the group can include additional capacity that is billed at the Hourly Capacity Unit (HCU) rate, if desired. For more information, see Capacity allocation and Committed and flexible workloads.

Astra Portal
DevOps API

In the Astra Portal header, click Settings.
In the Settings navigation menu, click the name of the current organization, and then select the organization where you want to create a PCU group.
In the Settings navigation menu, click Billing.
In the Provisioned Capacity Unit groups section, click Create PCU group.
Enter a name and optional description for the PCU group.
Select the cloud provider and region for the PCU group.

Each PCU group is associated with a specific cloud provider and region, and databases that you assign to this group must have the same cloud provider and region as the group.

You must create separate PCU groups for each cloud provider and region where you require provisioned capacity.

For multi-region databases, you must create a PCU group for each region where the databases are deployed.
Add databases to the group.

PCU groups can include either Serverless (Vector) or Serverless (Non-Vector) databases. All databases in a group share the group’s allocated capacity. If you put multiple databases in the same group, make sure the group’s allocated capacity can support those databases. For more information, see Plan your PCU groups in Astra DB.

You can also add and remove databases when you edit PCU groups.
For Workload type, select Committed capacity workload.
For Provision type, select Shared tenant environment or Dedicated tenant environment.

Dedicated tenancy has billing implications. For more information, see Provision type (tenancy).

Allocate PCUs to the group by setting the reserved, minimum, and maximum capacity.

These values can have long-term billing implications and immediate performance impacts on your Astra DB Serverless databases:

Undercommitment can increase latency and cause other performance issues for your databases.
Overcommitment can be cost inefficient because PCU groups incur billed charges even if the PCU group has no databases or the databases don’t use all of the minimum capacity.

For more information, see Capacity allocation and Plan your PCU groups in Astra DB.

Reserved PCUs: Set the amount of reserved capacity for the group. This must be 1 or more.
Minimum PCUs: The minimum number of PCUs that you want available at all times for this group. This must be equal to or greater than the reserved capacity.
Maximum PCUs: The maximum number of PCUs that this group can scale up to as needed. To disable autoscaling, set the maximum equal to the minimum.

Optional: Enable Cache optimized, if applicable.

DataStax recommends this option for databases that support vector search or have large working datasets.

Cache optimization has billing implications. For more information, see Cache optimization.
Select Authorization to acknowledge the PCU service agreement and agree to create the PCU subscription.
Click Create PCU group.

Get the list of PCU groups in your organization:

curl -sS -L -X POST "https://api.astra.datastax.com/v2/pcus/actions/get" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{}'

Replace APPLICATION_TOKEN with an application token that has the Organization Administrator or Billing Administrator role.

Response

A successful response returns an array of objects representing PCU groups. If there are no groups, the array is empty.

[
  {
    "uuid": "PCU_GROUP_ID",
    "orgId": "ORGANIZATION_ID",
    "title": "group name string",
    "cloudProvider": [ "AWS" ],
    "region": "us-east-2",
    "instanceType": "standard",
    "provisionType": "shared",
    "min": 1,
    "max": 1,
    "reserved": 1,
    "description": "group description string",
    "createdAt": "2021-06-01T12:00:00.000Z",
    "updatedAt": "2021-06-01T12:00:00.000Z",
    "createdBy": "user",
    "updatedBy": "user"
  }
]

For more information, see POST /v2/pcus/actions/get.

To inspect a single group, you can pass pcuGroupUUIDs in the body of POST /v2/pcus/actions/get or use GET /v2/pcus/association/PCU_GROUP_ID.

To create a PCU group, use POST /v2/pcus:

curl -sS -L -X POST "https://api.astra.datastax.com/v2/pcus" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "orgId": "ORGANIZATION_ID",
  "title": "PCU_GROUP_NAME",
  "description": "PCU_GROUP_DESCRIPTION",
  "cloudProvider": [ "CLOUD_PROVIDER" ],
  "region": "REGION_NAME",
  "provisionType": "PROVISION_TYPE",
  "reserved": RESERVED,
  "min": MINIMUM,
  "max": MAXIMUM,
  "instanceType": "INSTANCE_TYPE"
}'

Replace the following:

APPLICATION_TOKEN: Provide an application token with the Organization Administrator or Billing Administrator role.
ORGANIZATION_ID: Provide your Astra DB organization ID.
PCU_GROUP_NAME and PCU_GROUP_DESCRIPTION: Provide a name and optional description for the PCU group.
CLOUD_PROVIDER and REGION_NAME: Specify the cloud provider (one of AWS, GCP, or AZURE) and region (such as us-east-2) for the PCU group.

Each PCU group is associated with a specific cloud provider and region, and databases that you assign to this group must have the same cloud provider and region as the group.

You must create separate PCU groups for each cloud provider and region where you require provisioned capacity.

For multi-region databases, you must create a PCU group for each region where the databases are deployed.
PROVISION_TYPE: Set to shared for shared tenancy, or set to dedicated for dedicated tenancy.

Dedicated tenancy has billing implications. For more information, see Provision type (tenancy).
INSTANCE_TYPE: Set to standard for default cache storage, or set to storageOptimized to enable cache optimized storage.

DataStax recommends storageOptimized for databases that support vector search or have large working datasets.

Cache optimization has billing implications. For more information, see Cache optimization.

RESERVED, MINIMUM, and MAXIMUM: Allocate PCUs to the group by setting the reserved, minimum, and maximum capacity.

These values can have long-term billing implications and immediate performance impacts on your Astra DB Serverless databases:

Undercommitment can increase latency and cause other performance issues for your databases.
Overcommitment can be cost inefficient because PCU groups incur billed charges even if the PCU group has no databases or the databases don’t use all of the minimum capacity.

For more information, see Capacity allocation and Plan your PCU groups in Astra DB.

RESERVED: Set the amount of reserved capacity for the group. This must be 1 or more.
MINIMUM: The minimum number of PCUs that you want available at all times for this group. This must be equal to or greater than the reserved capacity.
MAXIMUM: The maximum number of PCUs that this group can scale up to as needed. To disable autoscaling, set the maximum equal to the minimum.

Get the PCU group’s uuid from the response:

[
  {
    "uuid": "PCU_GROUP_ID",
    "orgId": "ORGANIZATION_ID",
    "title": "group name string",
    "cloudProvider": [ "AWS" ],
    "region": "us-east-2",
    "instanceType": "standard",
    "provisionType": "shared",
    "min": 1,
    "max": 1,
    "reserved": 1,
    "description": "group description string",
    "createdAt": "2021-06-01T12:00:00.000Z",
    "updatedAt": "2021-06-01T12:00:00.000Z",
    "createdBy": "user",
    "updatedBy": "user"
  }
]

Upon creation, a PCU group has no databases associated with it. You need the uuid to add databases to the group.

To add a database to the group, use POST /v2/pcus/association/PCU_GROUP_ID/DATACENTER_ID.

PCU groups can include either Serverless (Vector) or Serverless (Non-Vector) databases. All databases in a group share the group’s allocated capacity. If you put multiple databases in the same group, make sure the group’s allocated capacity can support those databases. For more information, see Plan your PCU groups in Astra DB. To add multiple databases, you must send multiple POST requests.

You can also add and remove databases when you edit PCU groups.
```
curl -sS -L -X POST "https://api.astra.datastax.com/v2/pcus/association/PCU_GROUP_ID/DATACENTER_ID" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
```
Replace the following:
- APPLICATION_TOKEN: An application token with the Organization Administrator or Billing Administrator role.
- PCU_GROUP_ID: The PCU group’s uuid.
- DATACENTER_ID: The database’s datacenter ID to add to the group. This must correspond with the PCU group’s cloud provider and region.
To confirm the changes, use GET /v2/pcus/association/PCU_GROUP_ID:
```
curl -sS -L -X GET "https://api.astra.datastax.com/v2/pcus/association/PCU_GROUP_ID" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
```
Response

A successful response includes an array of objects representing the datacenters associated with the given PCU group. This request does not return usage details.

Create a flexible capacity PCU group

Flexible capacity PCU groups don’t require a long-term commitment to reserved capacity, and you can park or delete them at any time. However, the group’s minimum capacity is billed entirely at the Hourly Capacity Unit (HCU) rate. For more information, see Capacity allocation and Committed and flexible workloads.

Astra Portal
DevOps API

In the Astra Portal header, click Settings.
In the Settings navigation menu, click the name of the current organization, and then select the organization where you want to create a PCU group.
In the Settings navigation menu, click Billing.
In the Provisioned Capacity Unit groups section, click Create PCU group.
Enter a name and optional description for the PCU group.
Select the cloud provider and region for the PCU group.

Each PCU group is associated with a specific cloud provider and region, and databases that you assign to this group must have the same cloud provider and region as the group.

You must create separate PCU groups for each cloud provider and region where you require provisioned capacity.

For multi-region databases, you must create a PCU group for each region where the databases are deployed.

Add databases to the group.

While you can put multi-region databases in a flexible capacity PCU group, you can’t park a PCU group that has a multi-region database.

If you are intending to park the PCU group, you must remove the multi-region database from the group before you park it. Otherwise, consider using committed capacity PCU groups for your multi-region databases. For more information about PCU groups for multi-region databases, see Plan your PCU groups in Astra DB.

PCU groups can include either Serverless (Vector) or Serverless (Non-Vector) databases. All databases in a group share the group’s allocated capacity. If you put multiple databases in the same group, make sure the group’s allocated capacity can support those databases. For more information, see Plan your PCU groups in Astra DB.

You can also add and remove databases when you edit PCU groups.

For Workload type, select Flexible capacity workload.
For Provision type, select Shared tenant environment or Dedicated tenant environment.

Dedicated tenancy has billing implications. For more information, see Provision type (tenancy).

Allocate PCUs to the group by setting the reserved, minimum, and maximum capacity.

These values can have long-term billing implications and immediate performance impacts on your Astra DB Serverless databases:

Undercommitment can increase latency and cause other performance issues for your databases.
Overcommitment can be cost inefficient because PCU groups incur billed charges even if the PCU group has no databases or the databases don’t use all of the minimum capacity.

For more information, see Capacity allocation and Plan your PCU groups in Astra DB.

Reserved PCUs: For flexible capacity workloads, the reserved capacity is always 0.
Minimum PCUs: The minimum number of PCUs that you want available at all times for this group. For flexible capacity workloads, this must be 1 or more.
Maximum PCUs: The maximum number of PCUs that this group can scale up to as needed. To disable autoscaling, set the maximum equal to the minimum.

Optional: Enable Cache optimized, if applicable.

DataStax recommends this option for databases that support vector search or have large working datasets.

Cache optimization has billing implications. For more information, see Cache optimization.
Select Authorization to acknowledge the PCU service agreement and agree to create the PCU subscription.
Click Create PCU group.

Get the list of PCU groups in your organization:

curl -sS -L -X POST "https://api.astra.datastax.com/v2/pcus/actions/get" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{}'

Replace APPLICATION_TOKEN with an application token that has the Organization Administrator or Billing Administrator role.

Response

A successful response returns an array of objects representing PCU groups. If there are no groups, the array is empty.

[
  {
    "uuid": "PCU_GROUP_ID",
    "orgId": "ORGANIZATION_ID",
    "title": "group name string",
    "cloudProvider": [ "AWS" ],
    "region": "us-east-2",
    "instanceType": "standard",
    "provisionType": "shared",
    "min": 1,
    "max": 1,
    "reserved": 1,
    "description": "group description string",
    "createdAt": "2021-06-01T12:00:00.000Z",
    "updatedAt": "2021-06-01T12:00:00.000Z",
    "createdBy": "user",
    "updatedBy": "user"
  }
]

For more information, see POST /v2/pcus/actions/get.

To inspect a single group, you can pass pcuGroupUUIDs in the body of POST /v2/pcus/actions/get or use GET /v2/pcus/association/PCU_GROUP_ID.

To create a PCU group, use POST /v2/pcus:

curl -sS -L -X POST "https://api.astra.datastax.com/v2/pcus" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "orgId": "ORGANIZATION_ID",
  "title": "PCU_GROUP_NAME",
  "description": "PCU_GROUP_DESCRIPTION",
  "cloudProvider": [ "CLOUD_PROVIDER" ],
  "region": "REGION_NAME",
  "provisionType": "PROVISION_TYPE",
  "reserved": RESERVED,
  "min": MINIMUM,
  "max": MAXIMUM,
  "instanceType": "INSTANCE_TYPE"
}'

Replace the following:

APPLICATION_TOKEN: Provide an application token with the Organization Administrator or Billing Administrator role.
ORGANIZATION_ID: Provide your Astra DB organization ID.
PCU_GROUP_NAME and PCU_GROUP_DESCRIPTION: Provide a name and optional description for the PCU group.
CLOUD_PROVIDER and REGION_NAME: Specify the cloud provider (one of AWS, GCP, or AZURE) and region (such as us-east-2) for the PCU group.

Each PCU group is associated with a specific cloud provider and region, and databases that you assign to this group must have the same cloud provider and region as the group.

You must create separate PCU groups for each cloud provider and region where you require provisioned capacity.

For multi-region databases, you must create a PCU group for each region where the databases are deployed.
PROVISION_TYPE: Set to shared for shared tenancy, or set to dedicated for dedicated tenancy.

Dedicated tenancy has billing implications. For more information, see Provision type (tenancy).
INSTANCE_TYPE: Set to standard for default cache storage, or set to storageOptimized to enable cache optimized storage.

DataStax recommends storageOptimized for databases that support vector search or have large working datasets.

Cache optimization has billing implications. For more information, see Cache optimization.

RESERVED, MINIMUM, and MAXIMUM: Allocate PCUs to the group by setting the reserved, minimum, and maximum capacity.

These values can have long-term billing implications and immediate performance impacts on your Astra DB Serverless databases:

Undercommitment can increase latency and cause other performance issues for your databases.
Overcommitment can be cost inefficient because PCU groups incur billed charges even if the PCU group has no databases or the databases don’t use all of the minimum capacity.

For more information, see Capacity allocation and Plan your PCU groups in Astra DB.

RESERVED: For flexible capacity workloads, set reserved to 0.
MINIMUM: The minimum number of PCUs that you want available at all times for this group. For flexible capacity workloads, this must be 1 or more.
MAXIMUM: The maximum number of PCUs that this group can scale up to as needed. To disable autoscaling, set the maximum equal to the minimum.

Get the PCU group’s uuid from the response:

[
  {
    "uuid": "PCU_GROUP_ID",
    "orgId": "ORGANIZATION_ID",
    "title": "group name string",
    "cloudProvider": [ "AWS" ],
    "region": "us-east-2",
    "instanceType": "standard",
    "provisionType": "shared",
    "min": 1,
    "max": 1,
    "reserved": 1,
    "description": "group description string",
    "createdAt": "2021-06-01T12:00:00.000Z",
    "updatedAt": "2021-06-01T12:00:00.000Z",
    "createdBy": "user",
    "updatedBy": "user"
  }
]

Upon creation, a PCU group has no databases associated with it. You need the uuid to add databases to the group.

To add a database to the group, use POST /v2/pcus/association/PCU_GROUP_ID/DATACENTER_ID.

PCU groups can include either Serverless (Vector) or Serverless (Non-Vector) databases. All databases in a group share the group’s allocated capacity. If you put multiple databases in the same group, make sure the group’s allocated capacity can support those databases. For more information, see Plan your PCU groups in Astra DB. To add multiple databases, you must send multiple POST requests.

You can also add and remove databases when you edit PCU groups.
```
curl -sS -L -X POST "https://api.astra.datastax.com/v2/pcus/association/PCU_GROUP_ID/DATACENTER_ID" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
```
Replace the following:
- APPLICATION_TOKEN: An application token with the Organization Administrator or Billing Administrator role.
- PCU_GROUP_ID: The PCU group’s uuid.
- DATACENTER_ID: The database’s datacenter ID to add to the group. This must correspond with the PCU group’s cloud provider and region.
To confirm the changes, use GET /v2/pcus/association/PCU_GROUP_ID:
```
curl -sS -L -X GET "https://api.astra.datastax.com/v2/pcus/association/PCU_GROUP_ID" \
--header "Authorization: Bearer APPLICATION_TOKEN" \
--header "Content-Type: application/json"
```
Response

A successful response includes an array of objects representing the datacenters associated with the given PCU group. This request does not return usage details.

Create PCU groups in Astra DB

Prerequisites

Billing implications and subscription terms

Immutable settings

Create a committed capacity PCU group

Create a flexible capacity PCU group

See also

Was this helpful?

Give Feedback