SolrCloud architecture

The vocabulary is unchanged from Cores vs. collections: a collection is the logical, named index your application queries; it is split into shards, each shard holds a distinct slice of the documents, and each shard is served by one or more replicas. Every replica — leader or not — is physically an ordinary core, auto-named like books_shard1_replica_n1, living inside some Solr node’s data directory. What SolrCloud adds on top of that vocabulary is everything below: a ZooKeeper-backed registry of which cores exist and where, and an election protocol that picks which replica of each shard is currently allowed to accept writes.

Every SolrCloud node connects to the same ZooKeeper ensemble and keeps a local, continuously-updated watch on its znodes rather than polling. Broadly:

Because configsets live in ZooKeeper rather than on each node’s local disk, adding a node or replacing a dead one needs no manual file copy: the new replica simply reads its collection’s configset out of ZooKeeper on startup. Collections API, configsets & replica placement covers configset reuse, versioning, and the CREATE/RELOAD collection actions that read from it.

A production ensemble should run an odd number of ZooKeeper servers — 3 tolerates one failure, 5 tolerates two — because it needs a strict majority (quorum) alive to keep serving writes; running only 1 or 2 gives up either redundancy or availability for no benefit. bin/solr start -e cloud launches a disposable, embedded single-node ZooKeeper for local trials only — point at a real external ensemble for anything that must survive a ZooKeeper node failing.

Upload a configset before creating any collection that references it, using either the bin/solr zk subcommand or the lower-level zkcli.sh it wraps:

Collection-management operations — creating a collection, adding or deleting a replica, splitting a shard — are not applied directly by whichever node receives the API call. They are queued as messages in /overseer/queue, and exactly one node in the cluster, the Overseer, dequeues and applies them one at a time, writing the result into each collection’s state.json. Serializing every such change through one node is what keeps two concurrent ADDREPLICA calls from racing each other into an inconsistent cluster state.

The Overseer itself is just another elected role, using the same ZooKeeper ephemeral-node election mechanism as shard-leader election below — if the Overseer node dies, a new one is elected automatically and resumes from the queue. Since Solr 9.7, a node’s willingness to hold that role is controlled with -Dsolr.node.roles at startup:

Within one shard, exactly one replica is the leader at any moment; it is the one Solr routes writes to first, and it forwards each update to every other replica of that shard before acknowledging it. Election runs per shard, independently of the cluster-wide Overseer election, using the same ZooKeeper primitive: replicas race to create an ephemeral sequential znode under that shard’s election path, and the lowest-numbered live entry wins. In practice this means the first replica to come up for a brand-new shard wins by default, and afterwards a new election runs — among whichever replicas are both live and eligible — the moment the current leader’s node session expires (crash, network partition, restart).

Only NRT and TLOG replicas are ever eligible; a PULL replica can never win, for the reason covered next.

Losing a leader is invisible to a well-behaved client: a write sent to the old leader’s URL fails over, the CloudSolrClient (or a load balancer reading /live_nodes and state.json) discovers the new leader from the refreshed cluster state, and retries against it. Distributed indexing & search covers how a write actually gets routed to the correct shard’s leader in the first place, and how a scatter-gather query reaches every shard once leaders and replicas are settled.

Every replica added to a shard is created as one of three types, set once at ADDREPLICA/create time via type=:

The trade-off is indexing cost versus read capacity: an NRT replica pays the full cost of applying every update itself (so it can also lead), a TLOG replica pays only for the transaction log and gets its index for free from the leader (cheaper per-replica indexing load, still election-eligible as a durability fallback), and a PULL replica pays nothing at index time at all — pure read scale-out that can never take over writes. Solr’s own guidance is to keep a shard’s replicas uniform — all NRT, all TLOG, or TLOG leaders backed by PULL read replicas — and to avoid mixing all three types on one shard, since PULL’s lag then interacts unpredictably with which of the other two is currently leading.

Reach for TLOG+PULL once indexing throughput and query fan-out start competing for the same nodes' CPU; until then, all-NRT is the simplest correct default. Indexing internals & performance covers the segment-merge and commit costs each replica type is actually paying for.

Putting the pieces together, standing up a new SolrCloud collection from nothing is: start every node against the ensemble, upload the configset once, then create the collection.

From here, Collections API, configsets & replica placement covers reconfiguring and reloading a live collection’s configset, adding shards and replicas after creation, and shard splitting; Distributed indexing & search covers how document routing picks a shard and how a query fans out across the topology this page just built.