Create a user-defined type (UDT)

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

  • Go

  • Java

  • C#

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

The Go client is in preview. For more information, see astra-db-go.

Creates a user-defined type with the specified definition.

A successful operation does not return anything.

Creates a user-defined type with the specified definition.

Does not return anything.

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

  • Go

  • Java

  • C#

  • 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 the 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 the 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.

The Go client is in preview. For more information, see astra-db-go.

Use the CreateType method, which belongs to the Db type.

Method signature 
func (d *Db) CreateType(
  ctx context.Context,
  name string,
  definition table.UDTDefinition,
  opts ...options.CreateTypeOption
) error
Name Type Summary

ctx

context.Context

The context for the operation.

name

string

The name of the new user-defined type.

The name must be unique within the keyspace.

definition

table.UDTDefinition

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 the examples for usage.

opts

…​options.CreateTypeOption

Optional. The options for this method.

See Methods of the CreateTypeOption builder for more details.
Methods of the CreateTypeOption builder
Method Summary

SetIfNotExists(v 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

SetKeyspace(v string)

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

Default: The database’s working keyspace.

UpdateAPIOptions(v …​APIOption)

Optional. General API options for this operation, including the timeout.

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 the 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 CreateTypeAsync method, which belongs to the Database class. You can also use CreateType, which is the synchronous version of the method.

Method signature 
public Task CreateTypeAsync<T>(CreateTypeOptions options = null);
public Task CreateTypeAsync<T>(
  string typeName, CreateTypeOptions options = null
);
public Task CreateTypeAsync(
  string typeName,
  UserDefinedTypeDefinition definition,
  CreateTypeOptions options = null
);
Name Type Summary

typeName

string

The name of the new user-defined type.

The name must be unique within the keyspace.

If you use a custom user-defined type class and do not specify this parameter, the client attempts to extract it from first from the [UserDefinedType("TYPE_NAME")] attribute, then from the name of the class. For more information and examples, see Custom typing for collections.

definition

UserDefinedTypeDefinition

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 the examples for usage.

options

CreateTypeOptions

Optional. Options for this operation. For more information and examples for general options such as timeout, see Customize API interaction. For options specific to this method, see Method-specific properties of the CreateTypeOptions class.
Method-specific properties of the CreateTypeOptions class
Name Type Summary

IfNotExists

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

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 the 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

  • Go

  • Java

  • C#

  • curl

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

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

# 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();
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});

// Drop a user-defined type
(async function () {
  await database.createType("member", {
    definition: {
      fields: {
        name: "text",
        is_active: "boolean",
        date_joined: "date",
      },
    },
  });
})();

The Go client is in preview. For more information, see astra-db-go.

 
package main

import (
	"context"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/table"
)

func main() {
	ctx := context.Background()

	// Get a database
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	// Create a user-defined type
	definition := table.UDTDefinition{
		Fields: table.Columns{
			{Name: "name", Column: table.Text()},
			{Name: "is_active", Column: table.Boolean()},
			{Name: "date_joined", Column: table.Date()},
		},
	}
	err := database.CreateType(ctx, "member", definition)
	if err != nil {
		log.Fatal(err)
	}
}
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);
  }
}

  • Typed

  • Untyped

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

// Define the user-defined type
[UserDefinedType("member")]
public class Member
{
  [ColumnName("name")]
  public string? Name { get; set; }

  [ColumnName("is_active")]
  public bool? IsActive { get; set; }

  [ColumnName("date_joined")]
  public DateOnly? DateJoined { get; set; }
};

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );

    // Create a user-defined type
    await database.CreateTypeAsync<Member>();
  }
}
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Tables;
using DataStax.AstraDB.DataApi.Utils;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );

    // Create a user-defined type
    await database.CreateTypeAsync(
      "member",
      new UserDefinedTypeDefinition
      {
        Fields = new Dictionary<string, DataAPIType>
        {
          ["name"] = DataAPIType.Text(),
          ["is_active"] = DataAPIType.Boolean(),
          ["date_joined"] = DataAPIType.Date(),
        },
      }
    );
  }
}
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

  • Go

  • Java

  • C#

  • curl

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

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

# 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();
const database = client.db("API_ENDPOINT", {
  token: "APPLICATION_TOKEN",
});

// Drop a user-defined type
(async function () {
  await database.createType("member", {
    definition: {
      fields: {
        name: "text",
        is_active: "boolean",
        date_joined: "date",
      },
    },
    ifNotExists: true,
  });
})();

The Go client is in preview. For more information, see astra-db-go.

 
package main

import (
	"context"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/table"
)

func main() {
	ctx := context.Background()

	// Get a database
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	// Create a user-defined type
	definition := table.UDTDefinition{
		Fields: table.Columns{
			{Name: "name", Column: table.Text()},
			{Name: "is_active", Column: table.Boolean()},
			{Name: "date_joined", Column: table.Date()},
		},
	}
	err := database.CreateType(
		ctx,
		"member",
		definition,
		options.CreateType().SetIfNotExists(true),
	)
	if err != nil {
		log.Fatal(err)
	}
}
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));
  }
}

  • Typed

  • Untyped

using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;

namespace Examples;

// Define the user-defined type
[UserDefinedType("member")]
public class Member
{
  [ColumnName("name")]
  public string? Name { get; set; }

  [ColumnName("is_active")]
  public bool? IsActive { get; set; }

  [ColumnName("date_joined")]
  public DateOnly? DateJoined { get; set; }
};

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );

    // Create a user-defined type
    await database.CreateTypeAsync<Member>(
      new CreateTypeOptions() { IfNotExists = true }
    );
  }
}
using DataStax.AstraDB.DataApi;
using DataStax.AstraDB.DataApi.Core;
using DataStax.AstraDB.DataApi.Tables;
using DataStax.AstraDB.DataApi.Utils;

namespace Examples;

public class Program
{
  static async Task Main()
  {
    // Get an existing table
    var client = new DataAPIClient();
    var database = client.GetDatabase(
      "API_ENDPOINT",
      "APPLICATION_TOKEN"
    );

    // Create a user-defined type
    await database.CreateTypeAsync(
      "member",
      new UserDefinedTypeDefinition
      {
        Fields = new Dictionary<string, DataAPIType>
        {
          ["name"] = DataAPIType.Text(),
          ["is_active"] = DataAPIType.Boolean(),
          ["date_joined"] = DataAPIType.Date(),
        },
      },
      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

  • Go

  • Java

  • C#

  • curl

For more information, see the client reference.

For more information, see the client reference.

The Go client is in preview. For more information, see astra-db-go.

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?

© Copyright IBM Corporation 2026 | 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: Contact IBM