Alter a user-defined type (UDT)

Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

Adds and renames fields in a user-defined type (UDT).

This command can’t rename the user-defined type itself or drop fields from the user-defined type. Instead, you must drop the user-defined type and then re-create the user-defined type with the desired name and fields.

Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart.

Result

  • Python

  • TypeScript

  • Java

  • curl

Adds or renames fields in a user-defined type.

Does not return anything.

Adds or renames fields in a user-defined type.

Returns a promise that resolves once the operation completes.

Adds or renames fields in a user-defined type.

Does not return anything.

Adds and renames fields in a user-defined type.

If the command succeeds, the response indicates the success.

Example response:

{
  "status": {
    "ok": 1
  }
}

Parameters

  • Python

  • TypeScript

  • Java

  • curl

Use the alter_type method, which belongs to the astrapy.Database class.

Method signature
alter_type(
  name: str,
  *,
  operation: AlterTypeOperation,
  keyspace: str,
  table_admin_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> None
Name Type Summary

name

str

The name of the user-defined type to alter.

operation

AlterTypeOperation

The alter operation to perform.

Can be one of the following:

  • An AlterTypeAddFields object that defines the name and data type of each field to add to the user-defined type. You can use any supported data type, except for maps, lists, sets, or other user-defined types.

  • An AlterTypeRenameFields object that describes the fields to rename.

See Examples for usage.

keyspace

str

Optional. The keyspace where the user-defined type exists.

Default: The database’s working keyspace.

table_admin_timeout_ms

int

Optional. A timeout, in milliseconds, to impose on the underlying API request. If not provided, the Table defaults apply. This parameter is aliased as request_timeout_ms and timeout_ms for convenience.

Use the alterType method, which belongs to the Db class.

Method signature
async alterType(
  name: string,
  options: {
    operation: AlterTypeOperations,
    keyspace?: string,
    timeout?: number | TimeoutDescriptor,
  }
): void
Name Type Summary

name

string

The name of the user-defined type to alter.

options

AlterTypeOptions

The options for this operation. See Properties of options for more details.

Properties of options
Name Type Summary

operation

AlterTypeOperations

The alter operation to perform.

Can be one of the following:

  • An AddFieldOperation object that defines the name and data type of each field to add to the user-defined type. You can use any supported data type, except for maps, lists, sets, or other user-defined types.

  • A RenameFieldOperation object that describes the fields to rename.

See Examples for usage.

keyspace

string

Optional. The keyspace where the user-defined type exists.

Default: The database’s working keyspace.

timeout

number | TimeoutDescriptor

Optional. A timeout to impose on the underlying API request.

Use the alterType method, which belongs to the com.datastax.astra.client.databases.Database class.

Method signature
void alterType(String name, AlterTypeOperation operation)
void alterType(
  String name,
  AlterTypeOperation operation,
  AlterTypeOptions options
)
Name Type Summary

name

String

The name of the user-defined type to alter.

operation

AlterTypeOperation

The alter operation to perform.

Can be one of the following:

  • An AlterTypeAddFields object that defines the name and data type of each field to add to the user-defined type. You can use any supported data type, except for maps, lists, sets, or other user-defined types.

  • An AlterTypeRenameFields object that describes the fields to rename.

See Examples for usage.

options

AlterTypeOptions

Optional. The options for this operation. See Methods of the AlterTypeOptions class for more details.

Methods of the AlterTypeOptions class
Method Parameters Summary

keyspace()

String

Optional. The keyspace where the user-defined type exists.

Default: The database’s working keyspace.

Use the alterType command.

Command signature
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "alterType": {
    "name": STRING,
    "rename": {
      "fields": {
          OLD_FIELD_NAME: NEW_FIELD_NAME,
          OLD_FIELD_NAME: NEW_FIELD_NAME
      }
    },
    "add": {
      "fields": {
          FIELD_NAME: FIELD_TYPE,
          FIELD_NAME: FIELD_TYPE
      }
    },
  }
}'
Name Type Summary

name

string

The name of the user-defined type to alter.

rename.fields

object

A JSON object that describes the fields to rename. Each key is an existing field name and each value is the new name for the field.

See Examples for usage.

add.fields

object

A JSON object that defines the fields to add to the user-defined type. Each key is a field name and each value is the field’s data type. You can use any supported data type, except for maps, lists, sets, or other user-defined types.

See Examples for usage.

Examples

The following examples demonstrate how to alter a user-defined type.

Rename fields

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.info import (
    AlterTypeRenameFields,
)

# Get a database
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")

# Rename fields in a user-defined type
database.alter_type(
    "member",
    AlterTypeRenameFields(fields={"name": "first_name", "is_active": "is_member"}),
)
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get a database
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");

// Drop a user-defined type
(async function () {
  await database.alterType("UDT_NAME", {
    operation: {
      rename: {
        fields: {
          name: "first_name",
          is_active: "is_member",
        },
      },
    },
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.commands.AlterTypeRenameFields;

public class Example {

  public static void main(String[] args) {
    // Get a database
    Database database = new DataAPIClient("APPLICATION_TOKEN").getDatabase("API_ENDPOINT");

    // Rename fields in a user-defined type
    database.alterType(
        "member",
        new AlterTypeRenameFields()
            .addField("name", "first_name")
            .addField("is_active", "is_member"));
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "alterType": {
    "name": "member",
    "rename": {
      "fields": {
          "name": "first_name",
          "is_active": "is_member"
      }
    }
  }
}'

Add fields

  • Python

  • TypeScript

  • Java

  • curl

from astrapy import DataAPIClient
from astrapy.info import (
    AlterTypeAddFields,
    ColumnType,
    TableScalarColumnTypeDescriptor,
)

# Get a database
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")

# Add fields to a user-defined type
database.alter_type(
    "member",
    AlterTypeAddFields(
        fields={
            "email": TableScalarColumnTypeDescriptor(ColumnType.TEXT),
            "credits": TableScalarColumnTypeDescriptor(ColumnType.INT),
        }
    ),
)
import { DataAPIClient } from "@datastax/astra-db-ts";

// Get a database
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");

// Drop a user-defined type
(async function () {
  await database.alterType("UDT_NAME", {
    operation: {
      add: {
        fields: {
          email: "text",
          credits: "int",
        },
      },
    },
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.commands.AlterTypeAddFields;

public class Example {

  public static void main(String[] args) {
    // Get a database
    Database database = new DataAPIClient("APPLICATION_TOKEN").getDatabase("API_ENDPOINT");

    // Add fields to a user-defined type
    database.alterType(
        "member", new AlterTypeAddFields().addFieldText("email").addFieldInt("credits"));
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "alterType": {
    "name": "member",
    "add": {
      "fields": {
          "email": "text",
          "credits": "int"
      }
    }
  }
}'

Rename and add fields

  • Python

  • TypeScript

  • Java

  • curl

You cannot use the client to rename and add fields in the same call. Either make separate calls, or use HTTP directly as demonstrated in the curl tab.

You cannot use the client to rename and add fields in the same call. Either make separate calls, or use HTTP directly as demonstrated in the curl tab.

You cannot use the client to rename and add fields in the same call. Either make separate calls, or use HTTP directly as demonstrated in the curl tab.

You may rename and add fields in the same call.
However, if one alteration fails, all subsequent operations are aborted.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "alterType": {
    "name": "member",
    "rename": {
      "fields": {
          "name": "first_name",
          "is_active": "is_member"
      }
    },
    "add": {
      "fields": {
          "email": "text",
          "credits": "int"
      }
    }
  }
}'

Client reference

  • Python

  • TypeScript

  • Java

  • curl

For more information, see the client reference.

For more information, see the client reference.

For more information, see the client reference.

Client reference documentation is not applicable for HTTP.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax, an IBM Company | Privacy policy | Terms of use | Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com