= ALTER TABLE
:description: Modifies the columns and properties of a table.

{description}

Add new columns, drop existing columns, renames columns, and modify table properties.
The command returns no results.

[NOTE]
==== 
`ALTER COLUMNFAMILY` is deprecated.
====

*See also:* xref:cassandra:reference/cql-commands/create-table.adoc[CREATE TABLE],
xref:cassandra:reference/cql-commands/drop-table.adoc[DROP TABLE],
xref:cassandra:reference/cql-commands/create-custom-index.adoc[CREATE CUSTOM INDEX] for Storage-Attached Indexes (SAI), xref:cassandra:reference/cql-commands/create-index.adoc[CREATE INDEX] for secondary indexes (2i)

== Syntax

BNF definition:

[source,bnf]
----
include::cassandra:example$BNF/alter_table.bnf[]
----

// tag::syntax[]
----
ALTER TABLE [<keyspace_name>.]<table_name>
  [ ADD ( <column_definition> | <column_definition_list> ) [ , ... ] ]
  [ DROP <column_name> [ , ... ] ]
  [ [ RENAME <column_name> TO <column_name> ] ]
  [ WITH <table_properties> [ , ... ] ];
----
// end::syntax[]

.Syntax legend
[%collapsible]
====
include::cassandra:partial$cql-syntax-legend.adoc[]
====

== Required parameters

*table_name*::
Name of the table to alter.

*column_name*::
Name of the column to alter, drop, or add.

// Column Definitions

include::cassandra:partial$table-column-definitions.adoc[]

== Optional parameters

*keyspace_name*::
Name of the keyspace that contains the table to alter. 
If no name is specified, the current keyspace is used.

*ADD ( <column_definition> | <column_definition_list> )* ::
Add one or more columns and set the column data types.
Specify the column names followed by the data types.
The column value is automatically set to null.
To add multiple columns, use a comma separated list of columns placed inside parentheses.
+
----
<column_name> <cql_type> [ , ] 
[ <column_name> <cql_type> [ , ... ]
----
*Restriction:* Adding columns to a primary key is not supported after a table has been created.

*DROP ( <column> | <column_list> )* ::
Drop one or more columns.
The values contained in the row are also dropped and not recoverable.
To drop multiple columns, use a comma separated list of columns placed inside parentheses.

*RENAME <column_name> TO <column_name>* ::
Changes the name of a primary key column and preserves the existing values.
+
*Restriction:* Not supported on materialized view base-tables, or tables with secondary indexes.

// Table Options

include::cassandra:partial$table-properties.adoc[]

*table_properties* ::
You can modify an existing table's properties.
Some properties are single options that are set to a value:
+
[source,no-highlight]
----
<option_name> = <value> [ AND ... ]
----
+
For example, `speculative_retry = '10ms'`.
Enclose the value for a string property in single quotation marks.
+
Other table properties are set using a JSON map: `+option_name = { <subproperty_name> : <value> [ , ... ] }+`
+
See xref:reference:cql-commands/create-table.adoc#table_options[table_options] for more details.

== Usage notes

*Restrictions:*

* Can only rename clustering columns in the primary key.
* Cannot change the data type of a column.
* For a table that has a materialized view, cannot drop a column from the table even if the column is not used in the materialized view.
* Cannot rename or drop columns that have dependent secondary indexes.
* Do not add a column with the same name as an existing column but with a different data type.
It will prevent commit log replays and corrupt existing SSTables with old data.

== Examples

This section uses the xref:cassandra:cyclist_races-table.adoc[cyclist_races] table.

=== Adding a column

To add a column, use the ADD instruction:

[source,language-cql]
----
include::cassandra:example$CQL/cyclist_races-table.cql[tag=add]
----

To add a column of a collection type:

[source,language-cql]
----
include::cassandra:example$CQL/cyclist_races-table.cql[tag=list]
----

This operation does not validate the existing data.

*Restriction:* You cannot use the `ADD` instruction to add:

* A column with the same name as an existing column
* A static column if the table has no clustering columns.

=== Dropping a column

To remove a column from the table, use the DROP instruction:

[source,language-cql]
----
include::cassandra:example$CQL/cyclist_races-table.cql[tag=drop]
----

`DROP` removes the column from the table definition.
The column becomes unavailable for queries immediately after it is dropped.
The database drops the column data during the next compaction.

*Restriction:*

* If you drop a column then re-add it, {product}
does not restore the values written before the column was dropped.
* Do not re-add a dropped column that contained timestamps generated by a client;
you can re-add columns with timestamps generated by the xref:developing/querying/use-write-time.adoc[write time] facility.

=== Renaming a column

To rename a column in the xref:cassandra:race_times-table.adoc[race_times] table:

[source,language-cql]
----
include::cassandra:example$CQL/race_times-table.cql[tag=rename]
----

*Restriction:* The following restrictions apply to `RENAME`:

* You can only rename clustering columns, which are part of the primary key.
* You cannot rename the partition key because the partition key determines the data storage location on a node.
If a different partition name is required, the table must be recreated and the data migrated.
+
[NOTE]
==== 
There are many restrictions when using `RENAME` because SSTables are immutable.
To change the state of the data on disk, everything must be rewritten.
====


* You can index a renamed column.
* You cannot rename a column if an index has been created on it.
* You cannot rename a static column.

=== Modifying table properties

To change an existing table's properties, use `ALTER TABLE` and `WITH`.
You can specify a:

* Single property name and value.
* Property map to set the names and values, as shown in the xref:cql-commands/alter-table.adoc#alter-compression[next section on compression and compaction].

For example, to add a comment to the xref:cassandra:cyclist_base-table.adoc[cyclist_base] table using WITH:

[source,language-cql]
----
include::cassandra:example$CQL/cyclist_base-table.cql[tag=alt]
----

Enclose a text property value in single quotation marks.

[[alter-compression]]
=== Modifying compression and compaction

Use a property map to alter the xref:cassandra:comments-table.adoc[comments] table's compression or compaction setting:

[source,language-cql]
----
include::cassandra:example$CQL/cyclist_base-table.cql[tag=alt]
----

Enclose the name of each key in single quotes.
If the value is a string, enclose the string in quotes as well.

[CAUTION]
====
If you change the compaction strategy of a table with existing data, the database rewrites all existing SSTables using the new strategy.
This can take hours, which can be a major problem for a production system.
For strategies to minimize this disruption, see http://blog.alteroot.org/articles/2015-04-20/change-cassandra-compaction-strategy-on-production-cluster.html[How to change the compaction strategy on a production cluster] and https://groups.google.com/forum/#!topic/nosql-databases/iYPoy-06Qvs[Impact of Changing Compaction Strategy].
====

=== Changing caching

Set the number of rows per partition to store in the row cache for the xref:cassandra:comments-table.adoc[comments] table to 10 rows:

[source,language-cql]
----
include::cassandra:example$CQL/comments-table.cql[tag=cache]
----

=== Change the speculative retries

Modify the `cyclist_base` table to 95th percentile for speculative retry:

[source,language-cql]
----
include::cassandra:example$CQL/cyclist_base-table.cql[tag=specr]
----

Modify the `cyclist_base` table to use 10 milliseconds for speculative retry:

[source,language-cql]
----
include::cassandra:example$CQL/cyclist_base-table.cql[tag=milli]
----

=== Enabling and disabling background compaction

The following example sets the `enabled` property to `false` to disable background compaction:

[source,language-cql]
----
include::cassandra:example$CQL/comments-table.cql[tag=nocompact]
----

[WARNING]
====
Disabling background compaction can be harmful: without it, the database does not regain disk space, and could allow https://docs.datastax.com/en/glossary/doc/glossary/gloss_zombie.html[zombies] to propagate.
Although compaction uses I/O, it is better to leave it enabled in most cases.
====

=== Reading extended compaction logs

Set the `log_all` subproperty to `true` to collect in-depth information about compaction activity on a node in a dedicated log file.

[IMPORTANT]
==== 
If you enable extended compaction logging for any table on any node, it is enabled for all tables on all nodes in the cluster.
====

When extended compaction is enabled, the database creates a file named compaction-%d.log (where `%d` is a sequential number) in home/logs.

The compaction logging service logs detailed information about the following types of compaction events:

* `type:enable`
+
Lists SSTables that have been flushed previously.
+
[source,no-highlight]
----
{"type":"enable","keyspace":"test","table":"t","time":1470071098866,"strategies":
  [    {"strategyId":"0","type":"LeveledCompactionStrategy","tables":[],"repaired":true,"folders":
      ["/home/carl/oss/cassandra/bin/../data/data"]},
    {"strategyId":"1","type":"LeveledCompactionStrategy","tables":[],"repaired":false,"folders":
      ["/home/carl/oss/cassandra/bin/../data/data"]
    }
 ]
}
----

* `type: flush`
+
Logs a flush event from a memtable to an SSTable on disk, including the CompactionStrategy for each table.
+
----
{"type":"flush","keyspace":"test","table":"t","time":1470083335639,"tables":
  [    {"strategyId":"1","table":
      {"generation":1,"version":"mb","size":106846362,"details":
        {"level":0,"min_token":"-9221834874718566760","max_token":"9221396997139245178"}
      }
    }
 ]
}
----

* `type: compaction`
+
Logs a compaction event.
+
----
{"type":"compaction","keyspace":"test","table":"t","time":1470083660267,
 "start":"1470083660188","end":"1470083660267","input":
  [    {"strategyId":"1","table":
      {"generation":1372,"version":"mb","size":1064979,"details":
        {"level":1,"min_token":"7199305267944662291","max_token":"7323434447996777057"}
      }
    }
 ],"output":
  [    {"strategyId":"1","table":
      {"generation":1404,"version":"mb","size":1064306,"details":
        {"level":2,"min_token":"7199305267944662291","max_token":"7323434447996777057"}
      }
    }
 ]
}
----

* `type: pending`
+
Lists the number of pending tasks for a compaction strategy.
+
----
{"type":"pending","keyspace":"test","table":"t",
 "time":1470083447967,"strategyId":"1","pending":200}
----

=== Reviewing the table definition

Use `DESCRIBE` or `DESC` to view the table definition.

[source,language-cql]
----
include::cassandra:example$CQLSH/comments-desc_table.cqlsh[]
----

The table details including the column names are returned.

[source,results]
----
include::cassandra:example$RESULTS/comments-desc_table.result[]
----
