nodetool getendpoints

Displays the replica nodes for a specific partition key.

---

Synopsis

nodetool [connection_options] getendpoints <keyspace> <table> <key>

See connection options for connection options.

Description

nodetool getendpoints shows which nodes store replicas for a given partition key. This is useful for debugging data placement, understanding query routing, and troubleshooting replication issues.

---

Arguments

Argument	Description
keyspace	The keyspace containing the table
table	The table to query
key	The partition key value

---

Output

192.168.1.101
192.168.1.102
192.168.1.103

Lists all replica endpoints that store data for the specified partition key.

---

Examples

Find Replicas for UUID Key

nodetool getendpoints my_keyspace users 550e8400-e29b-41d4-a716-446655440000

Find Replicas for String Key

nodetool getendpoints my_keyspace customers "customer_123"

Find Replicas for Integer Key

nodetool getendpoints my_keyspace orders 12345

Find Replicas for Composite Key

For composite partition keys, use colon-separated values:

nodetool getendpoints my_keyspace events "2024-01-15:sensor_001"

---

Use Cases

Debug Data Location

# Where is this user's data stored?
nodetool getendpoints my_app users "user@example.com"

Verify Replication

# Check if RF=3 is working
endpoints=$(nodetool getendpoints my_keyspace my_table "key123")
echo "$endpoints" | wc -l
# Should output: 3

Troubleshoot Missing Data

# Find replicas, then query each directly
REPLICAS=$(nodetool getendpoints my_keyspace my_table "problem_key")
for host in $REPLICAS; do
    echo "=== $host ==="
    cqlsh $host -e "SELECT * FROM my_keyspace.my_table WHERE pk = 'problem_key';"
done

Understand Query Routing

# See which nodes a driver will contact for this key
nodetool getendpoints my_keyspace my_table "hot_partition"

---

Understanding the Output

With RF=3 in Single DC

$ nodetool getendpoints my_keyspace my_table "key1"
192.168.1.101
192.168.1.102
192.168.1.103

The partition is stored on these 3 nodes.

With NetworkTopologyStrategy (Multi-DC)

$ nodetool getendpoints my_keyspace my_table "key1"
192.168.1.101  # DC1
192.168.1.102  # DC1
192.168.1.103  # DC1
192.168.2.101  # DC2
192.168.2.102  # DC2
192.168.2.103  # DC2

Shows replicas in both datacenters.

---

How It Works

1. Cassandra computes token = hash(partition_key)
2. Finds the node owning that token on the ring
3. Returns that node plus RF-1 subsequent nodes (or per-DC replicas)

partition_key → hash → token → primary replica → replica list

---

Key Format by Data Type

Key Type	Example Command
UUID	nodetool getendpoints ks tbl 550e8400-e29b-...
Text	nodetool getendpoints ks tbl "my_string"
Int	nodetool getendpoints ks tbl 12345
Composite	nodetool getendpoints ks tbl "part1:part2"

---

Scripting Examples

Check All Keys in a List

check_key_distribution.sh

#!/bin/bash
KS=$1
TBL=$2

while read key; do
    echo "Key: $key"
    nodetool getendpoints $KS $TBL "$key"
    echo "---"
done < keys.txt

Find Hot Partition Owners

#!/bin/bash
# Find which nodes own suspected hot partitions

for key in "hot_key_1" "hot_key_2" "hot_key_3"; do
    echo "=== $key ==="
    nodetool getendpoints my_keyspace my_table "$key"
done | sort | uniq -c | sort -rn

Verify Cross-DC Replication

#!/bin/bash
# Ensure key has replicas in both DCs

KEY=$1
ENDPOINTS=$(nodetool getendpoints my_keyspace my_table "$KEY")

DC1_COUNT=$(echo "$ENDPOINTS" | grep "192.168.1" | wc -l)
DC2_COUNT=$(echo "$ENDPOINTS" | grep "192.168.2" | wc -l)

echo "DC1 replicas: $DC1_COUNT"
echo "DC2 replicas: $DC2_COUNT"

---

Common Issues

Key Not Found Error

If the table doesn’t exist or keyspace is wrong:

Table 'my_keyspace.nonexistent' does not exist

Wrong Key Format

For composite partition keys, ensure correct format:

# Wrong (for composite key)
nodetool getendpoints ks tbl "value1" "value2"

# Correct (colon-separated)
nodetool getendpoints ks tbl "value1:value2"

---

Related Commands

Command	Relationship
ring	Token distribution overview
describering	Token ranges with replicas
status	Node status and load
gossipinfo	Detailed node information