Apache Cassandra 1.1 Documentation

Keyspace and Column Family Storage Configuration

This document corresponds to an earlier product version. Make sure you are using the version that corresponds to your version.

Latest Cassandra documentation | Earlier Cassandra documentation

Cassandra stores the storage configuration attributes listed in this section in the system keyspace. You set storage configuration attributes on a per-keyspace or per-column family basis programmatically or using a client application, such as CQL or CLI. The attribute names documented in this section are the names recognized by the Thrift API and the CLI. When using CQL, you need to use slightly different names in CQL for a few of the attributes.

Keyspace Attributes

A keyspace must have a user-defined name, a replica placement strategy, and a replication factor that specifies the number of replicas per data center or node.

Option Default Value
name N/A (A user-defined value is required)
placement_strategy org.apache.cassandra.locator.SimpleStrategy
strategy_options N/A (container attribute)
durable_writes True

name

Required. The name for the keyspace.

placement_strategy

Required. Determines how Cassandra distributes replicas for a keyspace among nodes in the ring.

Allowed values are:

  • org.apache.cassandra.locator.SimpleStrategy
  • SimpleStrategy
  • org.apache.cassandra.locator.NetworkTopologyStrategy
  • NetworkTopologyStrategy

NetworkTopologyStrategy requires a properly configured snitch to be able to determine rack and data center locations of a node. For more information about the replica placement strategy, see About Replication in Cassandra.

strategy_options

Specifies configuration options for the chosen replication strategy.

For examples and more information about configuring the replication placement strategy for a cluster and data centers, see About Replication in Cassandra.

durable_writes

(Default: true) When set to false, data written to the keyspace bypasses the commit log. Be careful using this option because you risk losing data. Change the durable_writes attribute using the CQL CREATE KEYSPACE or ALTER KEYSPACE statement.

Column Family Attributes

The following attributes can be declared per column family.

Option Default Value
bloom_filter_fp_chance 0.000744
caching keys_only
column_metadata n/a (container attribute)
column_type Standard
comment n/a
compaction_strategy SizeTieredCompactionStrategy
compaction_strategy_options n/a (container attribute)
comparator BytesType
compare_subcolumns_with BytesType
compression_options sstable_compression='SnappyCompressor'
default_validation_class n/a
dclocal_read_repair_chance 0.0
gc_grace_seconds 864000 (10 days)
key_validation_class n/a
max_compaction_threshold 32
min_compaction_threshold 4
memtable_flush_after_mins [1] n/a
memtable_operations_in_millions [1] n/a
memtable_throughput_in_mb [1] n/a
name n/a
read_repair_chance 0.1 or 1 (See description below.)
replicate_on_write true

bloom_filter_fp_chance

(Default: 0.000744) Desired false-positive probability for SSTable Bloom filters. When data is requested, the Bloom filter checks if the requested row exists in the SSTable before doing any disk I/O. Valid values are 0 to 1.0. A setting of 0 means that the unmodified (effectively the largest possible) Bloom filter is enabled. Setting the Bloom Filter at 1.0 disables it. The higher the setting, the less memory Cassandra uses. The maximum recommended setting is 0.1, as anything above this value yields diminishing returns. For information about how Cassandra uses Bloom filters and tuning Bloom filters, see Tuning Bloom Filters.

caching

(Default: keys_only) Optimizes the use of cache memory without manual tuning. Set caching to one of the following values: all, keys_only, rows_only, or none. Cassandra weights the cached data by size and access frequency. Using Cassandra 1.1 and later, you use this parameter to specify a key or row cache instead of a table cache, as in earlier versions.

column_metadata

(Default: N/A - container attribute) Column metadata defines attributes of a column. Values for name and validation_class are required, though the default_validation_class for the column family is used if no validation_class is specified. Note that index_type must be set to create a secondary index for a column. index_name is not valid unless index_type is also set.

Option Description
name Binds a validation_class and (optionally) an index to a column.
validation_class Type used to check the column value.
index_name Name for the secondary index.
index_type Type of index. Currently the only supported value is KEYS.

Setting and updating column metadata with the Cassandra CLI requires a slightly different command syntax than other attributes; note the brackets and curly braces in this example:

[default@demo] UPDATE COLUMN FAMILY users WITH comparator=UTF8Type
AND column_metadata=[{column_name: full_name, validation_class: UTF8Type, index_type: KEYS}];

column_type

(Default: Standard) Use Standard for regular column families and Super for super column families.

Note

Super columns are not recommended for any reason and may result in poor performance and OutOfMemory exceptions.

comment

(Default: N/A) A human readable comment describing the column family.

compaction_strategy

(Default: SizeTieredCompactionStrategy) Sets the compaction strategy for the column family. The available strategies are:

  • SizeTieredCompactionStrategy: This is the default compaction strategy and the only compaction strategy available in pre-1.0 releases. This strategy triggers a minor compaction whenever there are a number of similar sized SSTables on disk (as configured by min_compaction_threshold). This strategy causes bursts in I/O activity while a compaction is in process, followed by longer and longer lulls in compaction activity as SSTable files grow larger in size. These I/O bursts can negatively effect read-heavy workloads, but typically do not impact write performance. Watching disk capacity is also important when using this strategy, as compactions can temporarily double the size of SSTables for a column family while a compaction is in progress.
  • LeveledCompactionStrategy: The leveled compaction strategy creates SSTables of a fixed, relatively small size (5 MB by default) that are grouped into levels. Within each level, SSTables are guaranteed to be non-overlapping. Each level (L0, L1, L2 and so on) is 10 times as large as the previous. Disk I/O is more uniform and predictable as SSTables are continuously being compacted into progressively larger levels. At each level, row keys are merged into non-overlapping SSTables. This can improve performance for reads, because Cassandra can determine which SSTables in each level to check for the existence of row key data. This compaction strategy is modeled after Google's leveldb implementation.

compaction_strategy_options

(Default: N/A - container attribute) Sets options related to the chosen compaction_strategy. Currently only LeveledCompactionStrategy has options:

sstable_size_in_mb: (Default 5) A compaction runs whenever more data exists in Level N > 0 than desired (sstable_size_in_mb * 10level), or whenever there is anything in L0. In practice, this often means multiple tables are flushed to L0 while Cassandra is busy compacting higher levels, but in theory a single L0 SSTable can definitely be compacted with L1.

Setting and updating compaction options using CQL requires a slightly different command syntax than other attributes. For example:

ALTER TABLE users
   WITH compaction_strategy_class='SizeTieredCompactionStrategy'
   AND min_compaction_threshold = 6;

For more information, see Configuring Compaction.

comparator

(Default: BytesType) Defines the data types used to validate and sort column names. There are several built-in column comparators available. Note that the comparator cannot be changed after a column family is created.

compare_subcolumns_with

(Default: BytesType) Required when column_type is "Super" (not recommended). Same as comparator but for the sub-columns of a SuperColumn.

For attributes of columns, see column_metadata.

compression_options

(Default: sstable_compression='SnappyCompressor') This is a container attribute for setting compression options on a column family. It contains the following options:

Option Description
sstable_compression Specifies the compression algorithm to use when compressing SSTable files. Cassandra supports two built-in compression classes: SnappyCompressor (Snappy compression library) and DeflateCompressor (Java zip implementation). Snappy compression offers faster compression/decompression while the Java zip compression offers better compression ratios. Choosing the right one depends on your requirements for space savings over read performance. For read-heavy workloads, Snappy compression is recommended. Developers can also implement custom compression classes using the org.apache.cassandra.io.compress.ICompressor interface.
chunk_length_kb Sets the compression chunk size in kilobytes. The default value (64) is a good middle-ground for compressing column families with either wide rows or with skinny rows. With wide rows, it allows reading a 64kb slice of column data without decompressing the entire row. For skinny rows, although you may still end up decompressing more data than requested, it is a good trade-off between maximizing the compression ratio and minimizing the overhead of decompressing more data than is needed to access a requested row.The compression chunk size can be adjusted to account for read/write access patterns (how much data is typically requested at once) and the average size of rows in the column family.
crc_check_chance Specifies how often to perform the block checksum calculation.

Use CQL to configure compression. Using CQL, you disable, set, and update compression options. In CQL compression_options are called compression_parameters.

default_validation_class

(Default: N/A) Defines the data type used to validate column values. There are several built-in column validators available.

dclocal_read_repair_chance

(Default: 0.0) Specifies the probability with which read repairs are invoked over all replicas in the current data center. Contrast read_repair_chance.

gc_grace_seconds

(Default: 864000 [10 days]) Specifies the time to wait before garbage collecting tombstones (deletion markers). The default value allows a great deal of time for consistency to be achieved prior to deletion. In many deployments this interval can be reduced, and in a single-node cluster it can be safely set to zero.

Note

This property is called gc_grace in the cassandra-cli client.

key_validation_class

(Default: N/A) Defines the data type used to validate row key values. There are several built-in key validators available, however CounterColumnType (distributed counters) cannot be used as a row key validator.

max_compaction_threshold

(Default: 32) Ignored in LeveledCompactionStrategy. In SizeTieredCompactionStrategy, sets the maximum number of SSTables to allow in a minor compaction.

min_compaction_threshold

(Default: 4) Sets the minimum number of SSTables to trigger a minor compaction when compaction_strategy=sizeTieredCompactionStrategy. Raising this value causes minor compactions to start less frequently and be more I/O-intensive.

memtable_flush_after_mins

Deprecated as of Cassandra 1.0. Can still be declared (for backwards compatibility) but settings will be ignored. Use the cassandra.yaml parameter commitlog_total_space_in_mb instead.

memtable_operations_in_millions

Deprecated as of Cassandra 1.0. Can still be declared (for backwards compatibility) but settings will be ignored. Use the cassandra.yaml parameter commitlog_total_space_in_mb instead.

memtable_throughput_in_mb

Deprecated as of Cassandra 1.0. Can still be declared (for backwards compatibility) but settings will be ignored. Use the cassandra.yaml parameter commitlog_total_space_in_mb instead.

name

(Default: N/A) Required. The user-defined name of the column family.

read_repair_chance

(Default: 0.1 or 1) Specifies the probability with which read repairs should be invoked on non-quorum reads. The value must be between 0 and 1. For column families created in versions of Cassandra before 1.0, it defaults to 1. For column families created in versions of Cassandra 1.0 and higher, it defaults to 0.1. However, for Cassandra 1.0, the default is 1.0 if you use CLI or any Thrift client, such as Hector or pycassa, and is 0.1 if you use CQL.

replicate_on_write

(Default: true) Applies only to counter column families. When set to true, replicates writes to all affected replicas regardless of the consistency level specified by the client for a write request. It should always be set to true for counter column families.