Configuring a Cluster with CQL¶

Scopes¶

An option can be set at several scopes. A value set at a narrower scope takes precedence over a value set at a broader one:

• TABLE overrides KEYSPACE, which overrides CLUSTER.

• NODE overrides RACK, which overrides DATACENTER, which overrides CLUSTER.

Each option supports a fixed set of scopes. Options that describe a table (such as auto_repair_enabled) can be set at TABLE, KEYSPACE and CLUSTER scope. No option currently supports the DATACENTER, RACK or NODE scopes.

Each scope stores only the values that were explicitly set there. The effective value of an option for a table is the value stored at the narrowest scope that has one: the table’s own value if it has one, otherwise the keyspace’s, otherwise the cluster’s. If no scope stores a value, the option’s built-in default applies.

Setting an option¶

For a table or a keyspace, use the WITH clause of the usual statements. The option name is used directly as a property name:

CREATE TABLE ks.tbl (pk int PRIMARY KEY) WITH auto_repair_enabled = true;
ALTER TABLE ks.tbl WITH auto_repair_enabled = false;
ALTER KEYSPACE ks WITH auto_repair_enabled = true;

Cluster configuration options can be combined with other properties in the same statement, for example WITH comment = 'orders' AND auto_repair_enabled = true. The one exception is a tablets replication-factor change, which cannot be combined with a cluster configuration option in the same ALTER KEYSPACE statement. This is rejected:

ALTER KEYSPACE ks WITH replication = {'class': 'NetworkTopologyStrategy', 'dc1': 3} AND auto_repair_enabled = true;

Use separate statements instead:

ALTER KEYSPACE ks WITH replication = {'class': 'NetworkTopologyStrategy', 'dc1': 3};
ALTER KEYSPACE ks WITH auto_repair_enabled = true;

For the cluster as a whole, use ALTER CLUSTER:

ALTER CLUSTER WITH auto_repair_enabled = true;

The statements for the node-oriented scopes exist for options that will support them:

alter_cluster_statement:    ALTER CLUSTER WITH `option` '=' `value`
alter_datacenter_statement: ALTER DATACENTER `datacenter_name` WITH `option` '=' `value`
alter_rack_statement:       ALTER RACK `datacenter_name` `rack_name` WITH `option` '=' `value`
alter_node_statement:       ALTER NODE `host_id` WITH `option` '=' `value`

The datacenter, rack, or node named in the statement must exist in the cluster.

Values are validated against the option’s type before anything is stored: a boolean option accepts true and false (in any letter case), an integer option accepts a signed 64-bit integer, and so on, and a text option accepts at most 4096 bytes. An unknown option name, an option used at a scope it does not support, or a value of the wrong type is rejected and nothing changes.

Removing an option¶

Setting an option to NULL removes the value stored at that scope, so the option falls back to the next broader scope, or to its default:

ALTER TABLE ks.tbl WITH auto_repair_enabled = NULL;   -- ks.tbl now follows its keyspace
ALTER CLUSTER WITH auto_repair_enabled = NULL;        -- back to the built-in default

Only the bare NULL keyword removes a value. The string 'null' is an ordinary value and is validated like any other, so a boolean option rejects it.

Permissions¶

The permission required depends on the scope, not on the option:

• ALTER TABLE ... WITH requires ALTER permission on the table.

• ALTER KEYSPACE ... WITH requires ALTER permission on the keyspace.

• ALTER CLUSTER, ALTER DATACENTER, ALTER RACK and ALTER NODE require a superuser.

Inspecting effective values¶

DESCRIBE KEYSPACE and DESCRIBE TABLE show the cluster configuration options that are in force for the described object, in the WITH clause alongside the other properties. Each such line ends with a comment that says where the value comes from and what every scope stores (NULL means nothing is stored at that scope).

A value stored at the described object’s own scope is shown as a regular property:

... AND auto_repair_enabled = true  -- from table (table=true, keyspace=false, cluster=NULL)

A value inherited from a broader scope is shown as a commented-out property, so replaying the DESCRIBE output recreates exactly what was stored and nothing more:

... -- AND auto_repair_enabled = false  -- from keyspace (table=NULL, keyspace=false, cluster=NULL)

Removing the leading -- marker and running the statement pins the inherited value at that scope as an explicit setting. An option that no scope stores is not shown at all.

DESCRIBE SCHEMA lists the cluster-scope values first, before any keyspace, as ALTER CLUSTER WITH ... statements, so a schema dump carries them. Under DESCRIBE SCHEMA WITH INTERNALS the trailing comments are omitted and only stored values are emitted, which is the form used for backup and restore. See DESCRIBE SCHEMA.

Available options¶