# How to Configure NetworkTopologyStrategy for Multi-Datacenter Replication in Apache Cassandra

> Configure NetworkTopologyStrategy for multi-datacenter replication in Apache Cassandra. Specify independent replication factors for each data center, ensuring rack aware replica placement.

- Repository: [The Apache Software Foundation/cassandra](https://github.com/apache/cassandra)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Use `NetworkTopologyStrategy` in your keyspace definition to specify independent replication factors for each data-center, ensuring rack-aware replica placement across geographic regions.**

Apache Cassandra distributes data across multiple nodes using configurable replication strategies. For production deployments spanning multiple data-centers, the `NetworkTopologyStrategy` class provides granular control over replication factors per DC, as implemented in the `apache/cassandra` repository.

## Understanding NetworkTopologyStrategy Configuration

### Core Constructor and Validation Logic

When you create a keyspace with NetworkTopologyStrategy, the constructor at [`src/java/org/apache/cassandra/locator/NetworkTopologyStrategy.java`](https://github.com/apache/cassandra/blob/main/src/java/org/apache/cassandra/locator/NetworkTopologyStrategy.java) (lines 81-105) receives a map of options and builds an immutable map of per-DC `ReplicationFactor` objects. The `validateExpectedOptions` method (lines 50-63) ensures at least one data-center is present and validates system keyspace requirements to guarantee all active DCs are covered.

### Automatic Option Expansion

If you provide a generic `replication_factor` without specifying individual DCs, the static `prepareOptions` method (lines 315-345) automatically expands that value across all known data-centers. This preserves any existing explicit DC entries while ensuring backward compatibility.

## Configuring Per-DataCenter Replication Factors

### CQL Syntax for CREATE and ALTER KEYSPACE

Specify NetworkTopologyStrategy using the `class` parameter with data-center specific replication factors:

```sql
CREATE KEYSPACE myks
WITH REPLICATION = {
  'class' : 'NetworkTopologyStrategy',
  'DC1'   : 3,
  'DC2'   : 2,
  'DC3'   : 1
};

```

The same syntax applies to `ALTER KEYSPACE` operations. As demonstrated in [`test/unit/org/apache/cassandra/locator/NetworkTopologyStrategyTest.java`](https://github.com/apache/cassandra/blob/main/test/unit/org/apache/cassandra/locator/NetworkTopologyStrategyTest.java) (lines 95-100), you can programmatically create keyspaces using:

```java
ClusterMetadataTestHelper.createKeyspace(
    "CREATE KEYSPACE ks1 WITH REPLICATION = {"
  + "   'class' : 'NetworkTopologyStrategy',"
  + "   'DC1': 3,"
  + "   'DC2': 2,"
  + "   'DC3': 1"
  + "};");

```

## How NetworkTopologyStrategy Selects Replicas

The `calculateNaturalReplicas` method (lines 124-170) implements the core replica placement logic. For each token lookup, the algorithm iterates **once around the token ring**, maintaining a `DatacenterEndpoints` helper per DC. It first attempts to place replicas on distinct racks; if a data-center lacks enough racks, it tolerates rack repeats up to the `acceptableRackRepeats` limit. The first endpoint added becomes the primary replica, with subsequent endpoints filling the per-DC replication factor requirement.

## Step-by-Step Deployment Configuration

1. **Define data-center topology** – Configure `conf/cassandra-rackdc.properties` to set `dc` and `rack` values so each node reports its location correctly.

2. **Select compatible snitch** – Ensure [`cassandra.yaml`](https://github.com/apache/cassandra/blob/main/cassandra.yaml) specifies an endpoint snitch compatible with NetworkTopologyStrategy, such as `GossipingPropertyFileSnitch`.

3. **Create the keyspace** – Execute `CREATE KEYSPACE` with the NetworkTopologyStrategy class and explicit per-DC replication factors.

4. **Verify configuration** – Query `system_schema.keyspaces` or run `nodetool describecluster` to confirm replication options are stored correctly in `org.apache.cassandra.schema.KeyspaceMetadata`.

5. **Monitor warnings** – The `maybeWarnOnOptions` method (lines 85-102) emits warnings when configured replication factors exceed the number of live nodes in a data-center.

## Validation and Safety Mechanisms

The `validateExpectedOptions` method enforces that at least one data-center is present in the configuration and performs additional validation for system keyspaces. When replication factors exceed available nodes, `maybeWarnOnOptions` generates alerts through the Cassandra logging system and `ClientWarn` mechanism, helping operators identify potentially unsafe configurations before they impact availability.

## Summary

- **NetworkTopologyStrategy** enables independent replication factors per data-center through a simple map configuration in CQL.
- The constructor at [`NetworkTopologyStrategy.java`](https://github.com/apache/cassandra/blob/main/NetworkTopologyStrategy.java) (lines 81-105) validates and builds immutable per-DC `ReplicationFactor` objects.
- Use `prepareOptions` (lines 315-345) to automatically apply a default replication factor across all DCs when individual mappings are not specified.
- The replica selection algorithm in `calculateNaturalReplicas` (lines 124-170) ensures rack diversity while respecting per-DC counts and tolerating rack repeats when necessary.
- Validation methods prevent misconfigurations and warn when replication factors exceed available nodes in any data-center.

## Frequently Asked Questions

### What happens if I set a replication factor higher than the number of nodes in a data-center?

The `maybeWarnOnOptions` method detects this condition and emits a warning through the Cassandra logging system and `ClientWarn` mechanism. While the configuration is accepted, you will see alerts indicating that the replication factor exceeds the available node count in that specific data-center, which could impact write consistency and fault tolerance.

### Can I change replication factors after creating a keyspace?

Yes, use `ALTER KEYSPACE` with the same NetworkTopologyStrategy syntax. The `prepareOptions` helper processes the new map and can automatically expand a generic `replication_factor` value across all current data-centers while preserving existing explicit DC entries, making it easy to adjust replication as your cluster grows.

### Which snitch should I use with NetworkTopologyStrategy?

You must use a snitch that exposes data-center and rack information, such as `GossipingPropertyFileSnitch` or `PropertyFileSnitch`. These read from `conf/cassandra-rackdc.properties` to provide the topology awareness required by NetworkTopologyStrategy's replica placement algorithm in `calculateNaturalReplicas`.

### How does Cassandra handle rack awareness when selecting replicas?

The `calculateNaturalReplicas` method prioritizes distinct racks within each data-center to maximize fault isolation. If the replication factor exceeds the number of available racks, the algorithm permits rack repeats up to the `acceptableRackRepeats` threshold, ensuring the requested replication factor is met while maintaining the best possible distribution across failure domains.