mirror of https://github.com/apache/cassandra
354 lines
11 KiB
Plaintext
354 lines
11 KiB
Plaintext
= 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 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 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[]
|
|
----
|