nodetool setconcurrentviewbuilders¶

Sets the number of concurrent threads used for building materialized views.

Synopsis¶

nodetool [connection_options] setconcurrentviewbuilders <value>

Description¶

nodetool setconcurrentviewbuilders controls how many threads are dedicated to building materialized views. When a materialized view is created or needs to be rebuilt, Cassandra populates it by reading data from the base table and writing corresponding entries to the view. This setting determines how many of these build operations can run in parallel.

What Are Materialized Views?¶

Materialized views are automatically maintained copies of base table data, organized by a different primary key to support different query patterns. When data is written to the base table, Cassandra automatically updates all associated materialized views.

-- Base table
CREATE TABLE users (
    user_id uuid PRIMARY KEY,
    email text,
    country text,
    created_at timestamp
);

-- Materialized view to query users by email
CREATE MATERIALIZED VIEW users_by_email AS
    SELECT * FROM users
    WHERE email IS NOT NULL AND user_id IS NOT NULL
    PRIMARY KEY (email, user_id);

-- Materialized view to query users by country
CREATE MATERIALIZED VIEW users_by_country AS
    SELECT * FROM users
    WHERE country IS NOT NULL AND user_id IS NOT NULL
    PRIMARY KEY (country, user_id);

When View Building Occurs¶

View building happens in these scenarios:

Scenario	Description
New view creation	When `CREATE MATERIALIZED VIEW` is executed, existing base table data must be copied to the view
Node bootstrap	When a new node joins, it builds local view data from streamed base table data
View rebuild	After corruption or manual truncation of view data
Repair	View data may be rebuilt during certain repair operations

How View Building Works¶

Each view builder thread:

Reads partitions from the base table
Transforms the data according to the view definition
Writes entries to the materialized view
Tracks progress for resumption if interrupted

Non-Persistent Setting

This setting is applied at runtime only and does not persist across node restarts. After a restart, the value reverts to the concurrent_materialized_view_builders setting in cassandra.yaml (default: 1).

To make the change permanent, update cassandra.yaml:

concurrent_materialized_view_builders: 2

Arguments¶

Argument	Description
`value`	Number of concurrent view builder threads (default: 1)

Examples¶

View Current Setting¶

nodetool getconcurrentviewbuilders

Set to 2 Concurrent Builders¶

nodetool setconcurrentviewbuilders 2

Set to 4 for Faster Building¶

nodetool setconcurrentviewbuilders 4

When to Adjust View Builders¶

Scenario 1: Creating a New Materialized View on Large Table¶

Situation: Creating a view on a table with billions of rows—initial build will take a long time.

Diagnosis:

# Check current view build status
nodetool viewbuildstatus

# Check current setting
nodetool getconcurrentviewbuilders

Action: Increase builders to speed up initial population:

# Increase during view creation
nodetool setconcurrentviewbuilders 4

# Monitor progress
watch -n 30 'nodetool viewbuildstatus'

# After completion, restore default to conserve resources
nodetool setconcurrentviewbuilders 1

Scenario 2: Multiple Views Being Built Simultaneously¶

Situation: Several materialized views are being created or rebuilt at the same time.

Diagnosis:

# Check how many views are building
nodetool viewbuildstatus

Example output:

Keyspace     View                  Status
myks         users_by_email        BUILDING (45%)
myks         users_by_country      BUILDING (23%)
myks         users_by_created      STARTED

Action: With multiple views building, more threads can help:

nodetool setconcurrentviewbuilders 4

Scenario 3: View Build Impacting Production Traffic¶

Situation: View building is consuming too many resources, causing latency spikes.

Diagnosis:

# Check disk I/O
iostat -x 1 5

# Check latencies
nodetool proxyhistograms

# Check if view building is active
nodetool viewbuildstatus

Action: Reduce builders to minimize impact:

# Slow down view building
nodetool setconcurrentviewbuilders 1

# Or pause entirely during peak hours by setting to 0 (if supported)

Scenario 4: Node Bootstrap Taking Too Long¶

Situation: New node is joining and building views is a bottleneck.

Diagnosis:

# On the new node
nodetool viewbuildstatus
nodetool netstats

Action: Increase builders to speed up bootstrap:

nodetool setconcurrentviewbuilders 4

Scenario 5: Off-Peak Maintenance Window¶

Situation: Want to complete view builds quickly during a maintenance window.

Action:

# During maintenance window - maximize throughput
nodetool setconcurrentviewbuilders 8

# Monitor progress
nodetool viewbuildstatus

# After completion or before peak hours
nodetool setconcurrentviewbuilders 1

Impact on Cluster Performance¶

Resource Consumption¶

Resource	Impact of More Builders
CPU	Higher utilization during builds
Disk I/O	More concurrent reads (base table) and writes (view)
Memory	More data buffered in memory
Network	Minimal (view building is local)

Trade-offs¶

Setting	Build Speed	Production Impact	Use Case
1 (default)	Slow	Minimal	Normal operations
2-4	Moderate	Noticeable	Off-peak view creation
4-8	Fast	Significant	Maintenance windows
8+	Very fast	High	Emergency rebuilds

Monitoring During View Building¶

#!/bin/bash
# monitor_view_build.sh - Watch view build progress and impact

while true; do
    clear
    echo "=== $(date) ==="
    echo ""

    echo "--- View Build Status ---"
    nodetool viewbuildstatus
    echo ""

    echo "--- Current View Builders ---"
    nodetool getconcurrentviewbuilders
    echo ""

    echo "--- Disk I/O ---"
    iostat -x 1 1 | grep -E "Device|sd|nvme" | tail -2
    echo ""

    echo "--- Latencies ---"
    nodetool proxyhistograms | head -10

    sleep 30
done

Metrics to Monitor¶

View Build Progress¶

# Check status of all view builds
nodetool viewbuildstatus

Example output:

Keyspace     View                  Status
myks         users_by_email        BUILDING (78%)
myks         users_by_country      SUCCESS
myks         users_by_created      BUILDING (12%)

Thread Pool Statistics¶

# View builder tasks appear in tpstats
nodetool tpstats | grep -i view

Key Metrics¶

Metric	How to Check	Concern Threshold
Build progress	`nodetool viewbuildstatus`	Stuck at same percentage
Disk I/O util	`iostat -x 1`	Sustained 100%
Read latency	`nodetool proxyhistograms`	P99 significantly elevated
Write latency	`nodetool proxyhistograms`	P99 significantly elevated

Recommended Values¶

General Guidelines¶

Scenario	Recommended Value	Notes
Normal operations	1	Minimize impact on production
Small table view creation	1-2	Quick enough, low impact
Large table view creation	2-4	Balance speed and impact
Maintenance window	4-8	Maximize throughput
Multiple simultaneous views	2-4	Parallel progress
HDD storage	1-2	Limited by disk I/O
SSD/NVMe storage	2-8	Can handle more parallelism

Hardware Considerations¶

Storage Type	CPU Cores	Suggested Max
HDD	Any	2
SATA SSD	4-8	2-4
SATA SSD	16+	4-6
NVMe SSD	16+	4-8

Materialized View Build Process Details¶

Build Phases¶

Initialization - View metadata created, build job scheduled
Scanning - Base table partitions read sequentially
Transformation - Data transformed to view schema
Writing - View entries written to local SSTables
Completion - Build marked complete, view becomes queryable

Progress Tracking¶

Build progress is tracked in system.view_builds_in_progress:

SELECT * FROM system.view_builds_in_progress;

Resumption After Failure¶

If a node crashes during view building:

Progress is checkpointed periodically
On restart, build resumes from last checkpoint
No need to restart from scratch

Interaction with Other Settings¶

Compaction¶

View building creates new SSTables, which may trigger compaction:

# If view builds cause compaction storms, consider
compaction_throughput: 64MiB/s

Concurrent Reads/Writes¶

View building uses the same read/write paths:

concurrent_reads: 32   # View building reads from base table
concurrent_writes: 32  # View building writes to view

High view builder count can compete with production traffic for these thread pools.

Memory¶

More builders mean more data in memory:

# Ensure adequate heap for concurrent builds
-Xmx8G

Cluster-Wide Configuration¶

Apply to All Nodes¶

#!/bin/bash
# set_view_builders_cluster.sh

VALUE="${1:-1}"# Get list of node IPs from local nodetool status


nodes=$(nodetool status | grep "^UN" | awk '{print $2}')

echo "Setting concurrent view builders to $VALUE on all nodes..."

for node in $nodes; do
    echo -n "$node: "
    ssh "$node" "nodetool setconcurrentviewbuilders $VALUE \"
        && echo "set to $VALUE" \
        || echo "FAILED"
done

echo ""
echo "Verification:"
for node in $nodes; do
    echo -n "$node: "
    ssh "$node" "nodetool getconcurrentviewbuilders"
done

Making Changes Permanent¶

# cassandra.yaml
concurrent_materialized_view_builders: 2

Troubleshooting¶

View Build Stuck at Same Percentage¶

# Check if build is actually progressing
nodetool viewbuildstatus

# Check for errors in logs
grep -i "view\|materialized" /var/log/cassandra/system.log | tail -50

# Check for resource bottlenecks
iostat -x 1 3
nodetool tpstats

View Build Very Slow¶

# Check current setting
nodetool getconcurrentviewbuilders

# Increase if resources available
nodetool setconcurrentviewbuilders 4

# Check disk is not bottleneck
iostat -x 1 5

View Build Impacting Production¶

# Reduce builders immediately
nodetool setconcurrentviewbuilders 1

# Check latencies improving
nodetool proxyhistograms

# Consider scheduling builds during off-peak

Build Failed or View Inconsistent¶

# Check view status
nodetool viewbuildstatus

# If needed, rebuild the view
# Warning: This is disruptive
ALTER MATERIALIZED VIEW myks.my_view WITH rebuild = true;

Best Practices¶

View Builder Guidelines

Start with default (1) - Minimize production impact
Increase during off-peak - Use maintenance windows for faster builds
Monitor progress - Watch viewbuildstatus and disk I/O
Restore after completion - Return to default when builds finish
Consider storage type - SSDs can handle more parallelism than HDDs
Plan large view creations - Schedule during low-traffic periods
Make permanent if needed - Update cassandra.yaml for consistent behavior

Materialized View Caveats

Materialized views have significant operational overhead:

Every base table write triggers view updates
Views can become inconsistent and require repair
Large views take a long time to build
Views add latency to write operations

Consider alternatives like secondary indexes or application-side denormalization for simpler use cases.

Command	Relationship
getconcurrentviewbuilders	View current setting
viewbuildstatus	Check view build progress
tpstats	Thread pool statistics
compactionstats	Monitor compaction from view builds

nodetool setconcurrentviewbuilders¶

Synopsis¶

Description¶

What Are Materialized Views?¶

When View Building Occurs¶

How View Building Works¶

Arguments¶

Examples¶

View Current Setting¶

Set to 2 Concurrent Builders¶

Set to 4 for Faster Building¶

When to Adjust View Builders¶

Scenario 1: Creating a New Materialized View on Large Table¶

Scenario 2: Multiple Views Being Built Simultaneously¶

Scenario 3: View Build Impacting Production Traffic¶

Scenario 4: Node Bootstrap Taking Too Long¶

Scenario 5: Off-Peak Maintenance Window¶

Impact on Cluster Performance¶

Resource Consumption¶

Trade-offs¶

Monitoring During View Building¶

Metrics to Monitor¶

View Build Progress¶

Thread Pool Statistics¶

Key Metrics¶

Recommended Values¶

General Guidelines¶

Hardware Considerations¶

Materialized View Build Process Details¶

Build Phases¶

Progress Tracking¶

Resumption After Failure¶

Interaction with Other Settings¶

Compaction¶

Concurrent Reads/Writes¶

Memory¶

Cluster-Wide Configuration¶

Apply to All Nodes¶

Making Changes Permanent¶

Troubleshooting¶

View Build Stuck at Same Percentage¶

View Build Very Slow¶

View Build Impacting Production¶

Build Failed or View Inconsistent¶

Best Practices¶

Related Commands¶