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
-
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 |
|---|---|---|
|
|
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 Examples for usage. |
|
|
Optional. The keyspace in which to create the user-defined type. 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 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. The keyspace in which to create the user-defined type. 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 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. 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 |
|---|---|---|
|
|
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 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
-
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.