Alter a table
Tables with the Data API are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Hyper-Converged Database (HCD), and the use of such, is subject to the DataStax Preview Terms. |
Alters a table by doing one of the following:
-
Adding one or more columns to a table
-
Dropping one or more columns from a table
You cannot change a column’s type. Instead, you must drop the column and add a new column.
After you add a column, you should index the column if you want to filter or sort on the column. All indexed column names must use snake case, not camel case. For more information, see Create an index and Create a vector index.
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 drops columns.
Returns a new Table
instance that represents the table after the modification.
Although the Table
instance that you used to perform the alteration will still work, it will not reflect the updated typing if you added or dropped columns.
To reflect the new typing, use the row_type
parameter.
Adds or drops columns.
Returns a promise that resolves to a Table
instance that represents the table after the modification.
Although the Table
instance that you used to perform the alteration will still work, it will not reflect the updated typing if you added or dropped columns.
To reflect the new typing, provide the new type of the table to the alter
method.
For example:
const newTable = await table.alter<NewSchema>({
operation: {
add: {
columns: {
venue: 'text',
},
},
},
});
Adds or drops columns.
Returns a Table<T>
instance that represents the table after the schema change.
Although the Table
instance that you used to perform the alteration will still work, it will not reflect the updated typing if you added or dropped columns.
To reflect the new typing, use the rowClass
parameter.
Adds or drops columns.
If the command succeeds, the response indicates the success.
Example response:
{
"status": {
"ok": 1
}
}
Parameters
-
Python
-
TypeScript
-
Java
-
curl
Use the alter
method, which belongs to the astrapy.Table
class.
Method signature
alter(
operation: AlterTableOperation | dict[str, Any],
*,
row_type: type[Any] = DefaultRowType,
table_admin_timeout_ms: int,
request_timeout_ms: int,
timeout_ms: int,
) -> Table[NEW_ROW]
Name | Type | Summary |
---|---|---|
|
|
The alter operation to perform. Can be one of the following:
|
|
|
This parameter acts a formal specifier for the type checker.
If omitted, the resulting |
|
|
A timeout, in milliseconds, to impose on the underlying API request.
If not provided, the |
Use the alter
method, which belongs to the Table
class.
Method signature
async alter(
options: AlterTableOptions<Schema>
): Table<Schema, PKey>
Name | Type | Summary |
---|---|---|
|
|
The alter operation to perform. Can be one of the following:
|
|
|
The client-side timeout for this operation. |
Options (AddColumnOperation
):
Name | Type | Summary |
---|---|---|
|
|
The column names, data types, and other settings (if required) for the new columns. Column are defined in the same way as they are in |
Options (DropColumnOperation
):
Name | Type | Summary |
---|---|---|
|
|
The names of the columns to drop from the table. |
Use the alter
method, which belongs to the com.datastax.astra.client.tables.Table
class.
Method signature
Table<T> alter(AlterTableOperation operation)
Table<T> alter(
AlterTableOperation operation,
AlterTableOptions options
)
<R> Table<R> alter(
AlterTableOperation operation,
AlterTableOptions options,
Class<R> clazz
)
Name | Type | Summary |
---|---|---|
|
|
The alter operation to perform. Can be one of the following:
|
|
Specialization of the operation, including |
|
|
|
An optional new type for the row object.
If not provided, the default is |
Use the alterTable
command.
Command signature
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"alterTable": {
"operation": {
"add": {
"columns": {
"NEW_COLUMN_NAME": "DATA_TYPE",
"NEW_COLUMN_NAME": "DATA_TYPE"
}
}
}
}
}'
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"alterTable": {
"operation": {
"drop": {
"columns": [ "COLUMN_NAME", "COLUMN_NAME" ]
}
}
}
}'
Name | Type | Summary |
---|---|---|
|
|
The Data API command to modify the configuration of a table in a database. It acts as a container for all the attributes and settings required to modify the table. |
|
|
The alter operation to perform. Can be one of the following:
|
|
|
Define columns to add to the table. The format is the same as when you define |
|
|
The names of the columns to remove from the table. |
Examples
The following examples demonstrate how to alter a table.
Add columns to a table
When you add columns, the columns are defined in the same way as they are when you create a table.
After you add a column, you should index the column if you want to filter or sort on the column. For more information, see Create an index and Create a vector index.
-
Python
-
TypeScript
-
Java
-
curl
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import (
AlterTableAddColumns,
ColumnType,
TableScalarColumnTypeDescriptor,
)
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
table = database.get_table("TABLE_NAME", keyspace="KEYSPACE_NAME")
# Add columns
table.alter(
AlterTableAddColumns(
columns={
"is_summer_reading": TableScalarColumnTypeDescriptor(
column_type=ColumnType.BOOLEAN,
),
"library_branch": TableScalarColumnTypeDescriptor(
column_type=ColumnType.TEXT,
),
},
),
)
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const table = database.table("TABLE_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Add columns
(async function () {
await table.alter({
operation: {
add: {
columns: {
is_summer_reading: "boolean",
library_branch: "text",
},
},
},
});
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.AlterTableAddColumns;
import com.datastax.astra.client.tables.definition.rows.Row;
public class Example {
public static void main(String[] args) {
// Get an existing table
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
Table<Row> table = database.getTable("TABLE_NAME");
// Add columns
AlterTableAddColumns alterOperation =
new AlterTableAddColumns()
.addColumnBoolean("is_summer_reading")
.addColumnText("library_branch");
table.alter(alterOperation);
}
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"alterTable": {
"operation": {
"add": {
"columns": {
"is_summer_reading": "boolean",
"library_branch": "text"
}
}
}
}
}'
Drop columns from a table
-
Python
-
TypeScript
-
Java
-
curl
from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment
from astrapy.info import AlterTableDropColumns
# Get an existing table
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
"API_ENDPOINT",
token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
table = database.get_table("TABLE_NAME", keyspace="KEYSPACE_NAME")
# Drop columns
table.alter(
AlterTableDropColumns(
columns=["is_summer_reading", "library_branch"],
),
)
import {
DataAPIClient,
UsernamePasswordTokenProvider,
} from "@datastax/astra-db-ts";
// Get an existing table
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const table = database.table("TABLE_NAME", {
keyspace: "KEYSPACE_NAME",
});
// Drop columns
(async function () {
await table.alter({
operation: {
drop: {
columns: ["is_summer_reading", "library_branch"],
},
},
});
})();
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.databases.Database;
import com.datastax.astra.client.tables.Table;
import com.datastax.astra.client.tables.commands.AlterTableDropColumns;
import com.datastax.astra.client.tables.definition.rows.Row;
public class Example {
public static void main(String[] args) {
// Get an existing table
DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
Table<Row> table = database.getTable("TABLE_NAME");
// Drop columns
AlterTableDropColumns alterOperation =
new AlterTableDropColumns("is_summer_reading", "library_branch");
table.alter(alterOperation);
}
}
curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/TABLE_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"alterTable": {
"operation": {
"drop": {
"columns": ["is_summer_reading", "library_branch"]
}
}
}
}'
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.