Cassandra Keyspaces

A keyspace in Cassandra is the outermost container for your data. It groups related tables together and defines how Cassandra replicates data across the cluster. If you are familiar with MySQL or PostgreSQL, a keyspace is similar to a database, but it also carries replication settings that a regular database does not.

The Warehouse Analogy

Imagine a large logistics company with multiple warehouses across the country. Each warehouse stores goods for a specific region. The company decides which regions get duplicate stock and how many backup copies sit in other warehouses. A Cassandra keyspace works the same way — it defines which tables live there and how many copies of their data exist across the cluster.

Cluster
├── Keyspace: ecommerce      (replication_factor = 3)
│     ├── Table: products
│     ├── Table: orders
│     └── Table: customers
└── Keyspace: analytics      (replication_factor = 2)
      ├── Table: page_views
      └── Table: events

Creating a Keyspace

Use the CREATE KEYSPACE statement. You must specify a replication strategy and its settings.

Syntax

CREATE KEYSPACE keyspace_name
  WITH replication = {
    'class': 'strategy_name',
    ...strategy options...
  };

Replication Strategies

1. SimpleStrategy

SimpleStrategy places replica copies on the next nodes in the ring, going clockwise. Use it only for single data center clusters or local development. It does not account for racks or data centers.

CREATE KEYSPACE school
  WITH replication = {
    'class': 'SimpleStrategy',
    'replication_factor': 3
  };

A replication factor of 3 means Cassandra stores 3 copies of every piece of data — one on the primary node and two more on the next two nodes in the ring.

Ring with replication_factor = 3:

Data written for key X ──▶ [Node A] (primary)
                       ──▶ [Node B] (replica 1)
                       ──▶ [Node C] (replica 2)

2. NetworkTopologyStrategy

NetworkTopologyStrategy is the right choice for production clusters, especially those spanning multiple data centers. You specify a replication factor per data center, so Cassandra places copies intelligently across racks and regions.

CREATE KEYSPACE ecommerce
  WITH replication = {
    'class': 'NetworkTopologyStrategy',
    'us_east': 3,
    'eu_west': 2
  };

This creates 3 replicas in the US East data center and 2 replicas in the EU West data center. Your application keeps working even if one entire data center goes offline.

NetworkTopologyStrategy with 2 data centers:

US-East (RF=3)              EU-West (RF=2)
┌────────────────┐          ┌──────────────┐
│ Node A copy    │          │ Node E copy  │
│ Node B copy    │          │ Node F copy  │
│ Node C copy    │          └──────────────┘
└────────────────┘

Choosing a Replication Factor

Replication Factor  Meaning                         When to Use
──────────────────────────────────────────────────────────────────
1                   1 copy only (no redundancy)     Local testing only
2                   2 copies                        Low-stakes dev
3                   3 copies                        Standard production
5+                  5+ copies                       Critical data across
                                                    many data centers

A replication factor of 3 means you can lose up to 2 nodes and still read and write data successfully. This is the most common production setting.

Listing Keyspaces

cqlsh> DESCRIBE KEYSPACES;

system_auth  system  system_distributed  system_traces  school  ecommerce

Switching to a Keyspace

cqlsh> USE school;
cqlsh:school>

Describing a Keyspace

cqlsh> DESCRIBE KEYSPACE school;

CREATE KEYSPACE school WITH replication = {
  'class': 'SimpleStrategy',
  'replication_factor': '3'
} AND durable_writes = true;

Altering a Keyspace

Change the replication settings of an existing keyspace using ALTER KEYSPACE. You might do this when promoting a development environment to production or adding a new data center.

ALTER KEYSPACE school
  WITH replication = {
    'class': 'NetworkTopologyStrategy',
    'us_east': 3
  };

After changing the replication factor, run a repair on the keyspace to redistribute data to the correct number of nodes.

nodetool repair school

Dropping a Keyspace

Dropping a keyspace permanently deletes it and all tables and data inside it. This action cannot be undone.

DROP KEYSPACE school;

Durable Writes

The durable_writes setting controls whether Cassandra writes to the commit log before the MemTable. It defaults to true, which means crash safety is on. Setting it to false speeds up writes slightly but risks data loss on a crash. Leave it as true unless you have a very specific reason to change it.

CREATE KEYSPACE analytics
  WITH replication = {
    'class': 'SimpleStrategy',
    'replication_factor': 1
  }
  AND durable_writes = false;

System Keyspaces

Cassandra creates several keyspaces for its own internal use. You should not modify these.

System Keyspace           Purpose
────────────────────────────────────────────────────────────
system                    Internal cluster metadata
system_auth               User credentials and permissions
system_distributed        Distributed system data (repair, etc.)
system_schema             Table and keyspace definitions
system_traces             Query trace data

Summary

Keyspaces are the top-level organizational unit in Cassandra. They hold tables and define replication behavior. SimpleStrategy suits local development; NetworkTopologyStrategy is the right choice for any production cluster. Always choose a replication factor of at least 3 in production to ensure your data survives node failures.