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
-
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.
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
-
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 |
|---|---|---|
|
|
The name of the new user-defined type. The name must be unique within the keyspace. |
|
|
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. |
|
|
Optional if you specified a keyspace when instantiating the Default: The database’s working keyspace. |
|
|
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 |
|
|
A timeout, in milliseconds, to impose on the underlying API request.
If not provided, the Table defaults apply.
This parameter is aliased as |
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 |
|---|---|---|
|
|
The name of the new user-defined type. The name must be unique within the keyspace. |
|
|
The options for this operation.
See Properties of |
| Name | Type | Summary |
|---|---|---|
|
|
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. |
|
|
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 |
|
|
Optional if you specified a keyspace when instantiating the Default: The database’s working keyspace. |
|
|
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 |
|---|---|---|
|
|
The name of the new user-defined type. The name must be unique within the keyspace. |
|
|
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. |
|
|
Optional.
The options for this operation. See Methods of the |
| Method | Parameters | Summary |
|---|---|---|
|
|
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 |
|
|
Optional if you specified a keyspace when instantiating the 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 |
|---|---|---|
|
|
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 |
|
|
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. |
|
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 |
| Name | Type | Summary |
|---|---|---|
|
|
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 |
|---|---|---|
|
|
The name of the new user-defined type. The name must be unique within the keyspace. |
|
|
Optional.
The definition for the new user-defined type. See Properties of See the examples for usage. |
|
|
Optional.
The options for this operation. See Properties of |
| Name | Type | Summary |
|---|---|---|
|
|
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. |
| Name | Type | Summary |
|---|---|---|
|
|
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
-
C#
-
curl
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import (
ColumnType,
CreateTypeDefinition,
TableScalarColumnTypeDescriptor,
)
# Get a database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
# 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, keyspace="KEYSPACE_NAME"
)import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get a database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
// Drop a user-defined type
(async function () {
await database.createType("member", {
definition: {
fields: {
name: "text",
is_active: "boolean",
date_joined: "date",
},
},
keyspace: "KEYSPACE_NAME",
});
})();import com.datastax.astra.client.DataAPIClients;
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 =
DataAPIClients.clientHCD("USERNAME", "PASSWORD")
.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
// 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.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(
new CommandOptions() { Destination = DataAPIDestination.HCD }
);
var database = client.GetDatabase(
"API_ENDPOINT",
DataAPIClient.UsernamePasswordTokenProvider(
"USERNAME",
"PASSWORD"
),
"KEYSPACE_NAME"
);
// Create a user-defined type
await database.CreateTypeAsync<Member>();
}
}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(
new CommandOptions() { Destination = DataAPIDestination.HCD }
);
var database = client.GetDatabase(
"API_ENDPOINT",
DataAPIClient.UsernamePasswordTokenProvider(
"USERNAME",
"PASSWORD"
),
"KEYSPACE_NAME"
);
// 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/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
-
C#
-
curl
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import (
ColumnType,
CreateTypeDefinition,
TableScalarColumnTypeDescriptor,
)
# Get a database
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
# 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,
keyspace="KEYSPACE_NAME",
)import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get a database
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
// Drop a user-defined type
(async function () {
await database.createType("member", {
definition: {
fields: {
name: "text",
is_active: "boolean",
date_joined: "date",
},
},
ifNotExists: true,
keyspace: "KEYSPACE_NAME",
});
})();import com.datastax.astra.client.DataAPIClients;
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 =
DataAPIClients.clientHCD("USERNAME", "PASSWORD")
.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
// 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(
new CommandOptions() { Destination = DataAPIDestination.HCD }
);
var database = client.GetDatabase(
"API_ENDPOINT",
DataAPIClient.UsernamePasswordTokenProvider(
"USERNAME",
"PASSWORD"
),
"KEYSPACE_NAME"
);
// 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(
new CommandOptions() { Destination = DataAPIDestination.HCD }
);
var database = client.GetDatabase(
"API_ENDPOINT",
DataAPIClient.UsernamePasswordTokenProvider(
"USERNAME",
"PASSWORD"
),
"KEYSPACE_NAME"
);
// 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/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
-
C#
-
curl
For more information, see the client reference.
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.
