Introduction

With Spring Data Cassandra, you usually do not "create a table" the same way you would in a relational ORM and forget about it. Cassandra schema design is part of the data model itself: partition keys, clustering columns, and query patterns matter from the start.

Spring Data helps map Java classes to Cassandra tables, but you still need a real schema strategy. For development that may mean startup creation. In production, many teams prefer explicit CQL migrations.

Start With the Table Design, Not Just the Java Class

A Cassandra table is driven by how you query it. For example, if you fetch orders by customer and then by creation time, the partition key and clustering key should reflect that access pattern.

A simple entity might look like this:

1import java.time.Instant;
2import java.util.UUID;
3
4import org.springframework.data.cassandra.core.mapping.Column;
5import org.springframework.data.cassandra.core.mapping.PrimaryKeyColumn;
6import org.springframework.data.cassandra.core.mapping.Table;
7import org.springframework.data.cassandra.core.cql.PrimaryKeyType;
8import org.springframework.data.cassandra.core.cql.Ordering;
9
10@Table("orders")
11public class OrderEntity {
12
13    @PrimaryKeyColumn(name = "customer_id", type = PrimaryKeyType.PARTITIONED)
14    private UUID customerId;
15
16    @PrimaryKeyColumn(
17        name = "created_at",
18        type = PrimaryKeyType.CLUSTERED,
19        ordering = Ordering.DESCENDING
20    )
21    private Instant createdAt;
22
23    @Column("status")
24    private String status;
25
26    public UUID getCustomerId() { return customerId; }
27    public void setCustomerId(UUID customerId) { this.customerId = customerId; }
28
29    public Instant getCreatedAt() { return createdAt; }
30    public void setCreatedAt(Instant createdAt) { this.createdAt = createdAt; }
31
32    public String getStatus() { return status; }
33    public void setStatus(String status) { this.status = status; }
34}

This mapping is more meaningful than a table with one arbitrary id column, because it matches an actual Cassandra access pattern.

Explicit CQL Table Creation Is Often the Clearest

If you want startup creation in development, issuing CQL directly is explicit and version-stable:

1import com.datastax.oss.driver.api.core.CqlSession;
2import org.springframework.boot.ApplicationRunner;
3import org.springframework.context.annotation.Bean;
4import org.springframework.context.annotation.Configuration;
5
6@Configuration
7class CassandraSchemaConfig {
8
9    @Bean
10    ApplicationRunner createSchema(CqlSession session) {
11        return args -> {
12            session.execute("""
13                CREATE TABLE IF NOT EXISTS orders (
14                    customer_id uuid,
15                    created_at timestamp,
16                    status text,
17                    PRIMARY KEY ((customer_id), created_at)
18                ) WITH CLUSTERING ORDER BY (created_at DESC)
19                """);
20        };
21    }
22}

This works well for demos, local development, or tests because the actual CQL is visible and reviewable.

Then Let Spring Data Use the Table

Once the table exists, a repository is straightforward:

1import java.time.Instant;
2import java.util.List;
3import java.util.UUID;
4
5import org.springframework.data.cassandra.repository.CassandraRepository;
6
7public interface OrderRepository
8        extends CassandraRepository<OrderEntity, UUID> {
9
10    List<OrderEntity> findByCustomerId(UUID customerId);
11
12    List<OrderEntity> findByCustomerIdAndCreatedAtAfter(
13        UUID customerId,
14        Instant createdAt
15    );
16}

Spring Data now handles the mapping and query generation, but the underlying table shape is still the Cassandra design you chose earlier.

Automatic Schema Creation Exists, but Use It Carefully

Spring Data Cassandra can participate in schema creation depending on your configuration, but that convenience comes with tradeoffs:

• it is easy for local development
• it hides some of the actual CQL being created
• it is often too implicit for production schema management

For production, many teams prefer migrations or explicit CQL scripts so schema changes are reviewed and repeatable.

Also remember that the keyspace usually needs to exist before your table creation strategy runs, unless you are also managing keyspace creation explicitly.

Cassandra Is Not a Relational ORM Story

A frequent mistake is approaching Cassandra as if @Table plus a repository should behave like JPA. Cassandra has different rules:

• table design is query-driven
• joins are not the normal model
• primary key design determines what queries are efficient or even legal

So "create table with Spring Data Cassandra" is really two tasks:

1. design the table for your access pattern
2. map it cleanly in Spring Data

Common Pitfalls

The biggest pitfall is designing the Java class first and the Cassandra primary key second. In Cassandra, primary-key design is the table.

Another common issue is expecting Spring Data to create the keyspace for you in all environments. Often the keyspace lifecycle is managed separately.

Developers also underestimate how explicit Cassandra schema should be. Startup auto-creation is convenient for local work, but explicit CQL or migrations are often safer for serious deployments.

Finally, avoid a repository method set that encourages query patterns the table cannot support efficiently. Spring Data can generate methods, but it cannot fix a poor partitioning design.

Summary

• In Spring Data Cassandra, table creation starts with access-pattern design, not just annotations.
• Use explicit CQL for clear and predictable startup schema creation.
• Map the table with @Table and primary-key annotations that reflect Cassandra query design.
• Repositories work well once the schema shape is correct.
• For production, explicit migrations are often better than implicit auto-creation.