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.

Similarly, you cannot rename a table. Instead, you must drop and recreate the table.

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

operation

AlterTableOperation | dict[str, Any]

The alter operation to perform.

Can be one of the following:

  • An AlterTableAddColumns object that specifies the columns to add

  • A dictionary in the form {"add": {"columns": …​}} that specifies the columns to add

  • An AlterTableDropColumns object that specifies the names of the columns to remove

  • A dictionary in the form {"drop": {"columns": …​}} that specifies the names of the columns to remove

row_type

type

This parameter acts a formal specifier for the type checker. If omitted, the resulting Table is implicitly a Table[dict[str, Any]]. If provided, it must match the type hint specified in the assignment. For more information, see Typing support.

table_admin_timeout_ms

int

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

Method signature
async alter(
  options: AlterTableOptions<Schema>
): Table<Schema, PKey>
Name Type Summary

operation

AlterTableOperations<Schema>

The alter operation to perform.

Can be one of the following:

  • An {add: AddColumnOperation} object that specifies the columns to add

  • A {drop: DropColumnOperation} object that specifies the names of the columns to remove

timeout?

number | TimeoutDescriptor

The client-side timeout for this operation.

Options (AddColumnOperation):

Name Type Summary

columns

CreateTableColumnDefinitions

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

Options (DropColumnOperation):

Name Type Summary

columns

Cols<Schema>[]

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

operation

AlterTableOperation

The alter operation to perform.

Can be one of the following:

options

AlterTableOptions

Specialization of the operation, including timeout.

rowClass

Class<?>

An optional new type for the row object. If not provided, the default is Row, which is like a Map object.

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

alterTable

command

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.

operation

object

The alter operation to perform.

Can be one of the following:

  • An object in the form {add: {columns: COLUMN_DEFINITIONS}} that specifies the columns to add

  • An object in the form {drop: {columns: COLUMN_NAMES}} that specifies the names of the columns to remove

operation.add.columns

object

Define columns to add to the table.

The format is the same as when you define columns in createTable.

operation.drop.columns

array

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.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2025 DataStax | 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