Create 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.

Creates a user-defined type (UDT) to use in a table.

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

Creates a user-defined type with the specified definition.

Does not return anything.

Creates a user-defined type with the specified definition.

Returns a promise that resolves once the operation completes.

Creates a user-defined type with the specified definition.

Does not return anything.

Creates a user-defined type with the specified definition.

If the command succeeds, the response indicates the success.

Example response:

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

Parameters

  • Python

  • TypeScript

  • Java

  • curl

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

Method signature
create_type(
  name: str,
  *,
  definition: CreateTypeDefinition | dict[str, Any],
  keyspace: str,
  if_not_exists: bool,
  table_admin_timeout_ms: int,
  request_timeout_ms: int,
  timeout_ms: int,
) -> None
Name Type Summary

name

str

The name of the new user-defined type.

The name must be unique within the keyspace.

definition

CreateTypeDefinition | dict[str, Any]

The definition for the new user-defined type. The definition describes the name and data type of each field in the user-defined type. You can use any supported data type, except for maps, lists, sets, or other user-defined types.

See Examples for usage.

keyspace

str

Optional. The keyspace in which to create the user-defined type.

Default: The database’s working keyspace.

if_not_exists

bool

Optional. Whether the command should silently succeed even if a user-defined type with the given name already exists in the keyspace and no new type was created.

This option only checks type names. It does not check type definitions.

Default: false

table_admin_timeout_ms

int | None

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 createType method, which belongs to the Db class.

Method signature
async createType(
  name: string,
  options: {
    definition: CreateTypeDefinition,
    ifNotExists?: boolean,
    keyspace?: string,
    timeout?: number | TimeoutDescriptor,
  }
): void
Name Type Summary

name

string

The name of the new user-defined type.

The name must be unique within the keyspace.

options

CreateTypeOptions

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

Properties of options
Name Type Summary

definition

CreateTypeDefinition

The definition for the new user-defined type. The definition describes the name and data type of each field in the user-defined type. You can use any supported data type, except for maps, lists, sets, or other user-defined types.

See Examples for usage.

ifNotExists

boolean

Optional. Whether the command should silently succeed even if a user-defined type with the given name already exists in the keyspace and no new type was created.

This option only checks type names. It does not check type definitions.

Default: false

keyspace

string

Optional. The keyspace in which to create the user-defined type.

Default: The database’s working keyspace.

timeout

number | TimeoutDescriptor

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

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

Method signature
void createType(
  String name,
  TableUserDefinedTypeDefinition typeDefinition
)
void createType(
  String name,
  TableUserDefinedTypeDefinition typeDefinition,
  CreateTypeOptions options
)
Name Type Summary

name

String

The name of the new user-defined type.

The name must be unique within the keyspace.

definition

TableUserDefinedTypeDefinition

The definition for the new user-defined type. The definition describes the name and data type of each field in the user-defined type. You can use any supported data type, except for maps, lists, sets, or other user-defined types.

See Examples for usage.

options

CreateTypeOptions

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

Methods of the CreateTypeOptions class
Method Parameters Summary

ifNotExists()

boolean

Optional. Whether the command should silently succeed even if a user-defined type with the given name already exists in the keyspace and no new type was created.

This option only checks type names. It does not check type definitions.

Default: false

keyspace()

String

Optional. The keyspace in which to create the user-defined type.

Default: The database’s working keyspace.

Use the createType 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 '{
  "createType": {
    "name": STRING,
    "definition": {
      "fields": {
          FIELD_NAME: FIELD_TYPE,
          FIELD_NAME: FIELD_TYPE
      }
    },
    "options": {
      "ifNotExists": BOOLEAN
    }
  }
}'
Name Type Summary

name

string

The name of the new user-defined type.

The name must be unique within the keyspace.

definition

object

Optional. The definition for the new user-defined type. See Properties of definition for more details.

See Examples for usage.

options

object

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

Properties of definition
Name Type Summary

fields

object

A JSON object that defines the fields of 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.

Properties of options
Name Type Summary

ifNotExists

boolean

Optional. Whether the command should silently succeed even if a user-defined type with the given name already exists in the keyspace and no new type was created.

This option only checks type names. It does not check type definitions.

Default: false

Examples

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

Create a user-defined type

  • Python

  • TypeScript

  • Java

  • curl

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

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

# Create a user-defined type
type_definition = CreateTypeDefinition(
    fields={
        "name": TableScalarColumnTypeDescriptor(ColumnType.TEXT),
        "is_active": TableScalarColumnTypeDescriptor(ColumnType.BOOLEAN),
        "date_joined": TableScalarColumnTypeDescriptor(ColumnType.DATE),
    },
)
database.create_type("member", definition=type_definition)
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.createType("member", {
    definition: {
      fields: {
        name: "text",
        is_active: "boolean",
        date_joined: "date",
      },
    },
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.definition.types.TableUserDefinedTypeDefinition;

public class Example {

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

    // Create a user-defined type
    TableUserDefinedTypeDefinition typeDefinition =
        new TableUserDefinedTypeDefinition()
            .addFieldText("name")
            .addFieldBoolean("is_active")
            .addFieldDate("date_joined");
    database.createType("member", typeDefinition);
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createType": {
    "name": "member",
    "definition": {
      "fields": {
          "name": "text",
          "is_active": "boolean",
          "date_joined": "date"
      }
    }
  }
}'

Create a user-defined type only if the type does not exist

Use this option to silently do nothing if a user-defined type with the specified name already exists.

This option only checks type names. It doesn’t check the definition of any existing types.

  • Python

  • TypeScript

  • Java

  • curl

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

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

# Create a user-defined type
type_definition = CreateTypeDefinition(
    fields={
        "name": TableScalarColumnTypeDescriptor(ColumnType.TEXT),
        "is_active": TableScalarColumnTypeDescriptor(ColumnType.BOOLEAN),
        "date_joined": TableScalarColumnTypeDescriptor(ColumnType.DATE),
    },
)
database.create_type("member", definition=type_definition, if_not_exists=True)
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.createType("member", {
    definition: {
      fields: {
        name: "text",
        is_active: "boolean",
        date_joined: "date",
      },
    },
    ifNotExists: true,
  });
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.commands.options.CreateTypeOptions;
import com.datastax.astra.client.tables.definition.types.TableUserDefinedTypeDefinition;

public class Example {

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

    // Create a user-defined type
    TableUserDefinedTypeDefinition typeDefinition =
        new TableUserDefinedTypeDefinition()
            .addFieldText("name")
            .addFieldBoolean("is_active")
            .addFieldDate("date_joined");
    database.createType("member", typeDefinition, new CreateTypeOptions().ifNotExists(true));
  }
}
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "createType": {
    "name": "member",
    "definition": {
      "fields": {
          "name": "text",
          "is_active": "boolean",
          "date_joined": "date"
      }
    },
    "options": {
      "ifNotExists": true
    }
  }
}'

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