Cassandra CREATE TABLE

The CREATE TABLE statement builds a new table inside a keyspace. Every CREATE TABLE statement defines the columns, their data types, and the primary key. The primary key is the most critical part of the definition because it controls how data distributes across the cluster and which queries the table can answer efficiently.

Basic Syntax

CREATE TABLE [keyspace_name.]table_name (
  column1 datatype,
  column2 datatype,
  column3 datatype,
  PRIMARY KEY (partition_key [, clustering_column ...])
) [WITH table_options];

Example 1: Simple Table

USE ecommerce;

CREATE TABLE customers (
  customer_id UUID PRIMARY KEY,
  first_name  TEXT,
  last_name   TEXT,
  email       TEXT,
  signup_date TIMESTAMP
);

customers table:

customer_id (PK) | first_name | last_name | email              | signup_date
─────────────────────────────────────────────────────────────────────────────
uuid-001         | Alice      | Smith     | alice@mail.com     | 2024-01-15
uuid-002         | Bob        | Jones     | bob@mail.com       | 2024-02-20

Example 2: Table with Composite Primary Key

CREATE TABLE orders_by_customer (
  customer_id UUID,
  order_date  TIMESTAMP,
  order_id    UUID,
  status      TEXT,
  total       DECIMAL,
  PRIMARY KEY (customer_id, order_date, order_id)
) WITH CLUSTERING ORDER BY (order_date DESC, order_id ASC);

This table returns a customer's most recent orders first, because order_date sorts in descending order within each partition.

Example 3: Compound Partition Key

CREATE TABLE logs_by_service_date (
  service_name TEXT,
  log_date     DATE,
  log_time     TIMEUUID,
  level        TEXT,
  message      TEXT,
  PRIMARY KEY ((service_name, log_date), log_time)
) WITH CLUSTERING ORDER BY (log_time ASC);

The partition key is (service_name, log_date). This keeps all logs for a given service on a given day together, preventing any one partition from growing indefinitely.

Table Options

The optional WITH clause sets storage and performance properties for the table.

gc_grace_seconds

Sets how long Cassandra keeps tombstones (deletion markers) before removing them. The default is 864000 seconds (10 days). Cassandra needs this window so that replica nodes that were offline during a deletion catch up and apply the deletion before tombstones disappear.

CREATE TABLE events (
  event_id UUID PRIMARY KEY,
  name     TEXT
) WITH gc_grace_seconds = 86400;  -- 1 day

compaction

Tells Cassandra which compaction strategy to use when merging SSTables.

CREATE TABLE time_series_data (
  sensor_id UUID,
  read_time TIMESTAMP,
  value     DOUBLE,
  PRIMARY KEY (sensor_id, read_time)
) WITH compaction = {
  'class': 'TimeWindowCompactionStrategy',
  'compaction_window_unit': 'DAYS',
  'compaction_window_size': 1
};

comment

Adds a human-readable description to the table. This helps other developers understand the table's purpose.

CREATE TABLE products (
  product_id UUID PRIMARY KEY,
  name       TEXT
) WITH comment = 'Product catalog for the ecommerce keyspace';

ttl (default_time_to_live)

Sets a default TTL in seconds. Every row inserted into this table automatically expires after the specified number of seconds unless a per-row TTL overrides it.

CREATE TABLE session_tokens (
  token       UUID PRIMARY KEY,
  user_id     UUID,
  created_at  TIMESTAMP
) WITH default_time_to_live = 3600;  -- rows expire after 1 hour

caching

Controls key and row caching behavior. By default Cassandra caches keys in memory. You can tune this per table.

CREATE TABLE hot_products (
  product_id UUID PRIMARY KEY,
  name       TEXT
) WITH caching = {
  'keys': 'ALL',
  'rows_per_partition': '100'
};

IF NOT EXISTS

Prevents an error if the table already exists. Cassandra silently skips creation if the table is found.

CREATE TABLE IF NOT EXISTS customers (
  customer_id UUID PRIMARY KEY,
  name        TEXT
);

Viewing a Table Definition

DESCRIBE TABLE customers;

CREATE TABLE ecommerce.customers (
  customer_id uuid PRIMARY KEY,
  email       text,
  first_name  text,
  last_name   text,
  signup_date timestamp
) WITH additional_write_policy = '99p'
  AND gc_grace_seconds = 864000
  ...

Adding Columns After Creation

ALTER TABLE customers ADD phone TEXT;
ALTER TABLE customers ADD loyalty_points INT;

Common Mistakes

Mistake                              Fix
──────────────────────────────────────────────────────────────────────
Forgetting PRIMARY KEY               Every table must have one
Using a low-cardinality partition key Use a UUID or high-cardinality field
Putting too many columns in PK       Keep partition key lean; use
                                     clustering columns for sorting
Using JOIN-style thinking            Model one table per query pattern
Storing large BLOBs in a collection  Move to a separate table or
                                     external object storage

Summary

CREATE TABLE defines the structure and primary key of a Cassandra table. Always think about your query patterns before writing the CREATE TABLE statement. The table options WITH clause lets you fine-tune compaction, TTL, caching, and garbage collection behavior. Use IF NOT EXISTS to make scripts idempotent so they run safely multiple times.