dsmiley commented on code in PR #4716: URL: https://github.com/apache/solr/pull/4716#discussion_r3752338059
########## solr/solr-ref-guide/modules/deployment-guide/pages/solrcloud-update-consistency.adoc: ########## @@ -0,0 +1,94 @@ += SolrCloud Update Consistency Model +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +This page states the consistency model of SolrCloud update requests (`/update`): what a successful response guarantees, and what it deliberately does not. +Several of these guarantees are intentionally weaker than those of a transactional database; the trade-offs favor indexing throughput and availability. + +Developers interested in how these guarantees are implemented should read the companion document https://github.com/apache/solr/blob/main/dev-docs/distributed-update-internals.adoc[Distributed Update Internals] in the source repository. + +== What a Successful Update Means + +An update request may be sent to any node in the cluster. +Each document is routed to the leader replica of its shard, which assigns the document a version, applies the update locally, and forwards it to the other in-sync NRT and TLOG replicas of the shard. +PULL replicas never receive individual updates; they periodically copy index segments from the leader. + +A successful (HTTP 200) response guarantees that every document in the request was applied and written to the xref:configuration-guide:commits-transaction-logs.adoc#transaction-log[transaction log] on its shard leader, and that Solr attempted to replicate it to the shard's other in-sync replicas. + +It does *not* guarantee that any replica other than the leader applied the update. +By design, a replica that fails to acknowledge an update does not fail the request; instead the leader marks that replica as out-of-date, and the replica must recover (catch up from the leader) before serving queries or becoming a leader. +Clients that need to know how widely an update was replicated can inspect the achieved replication factor (`rf`) in the response header; it is informational only and is never enforced. +See xref:solrcloud-recoveries-and-write-tolerance.adoc[] for details. + +== Durability + +Every update is written to the leader's transaction log before the response is returned, and replayed on startup if the node was stopped before a hard commit. +With the default transaction log `syncLevel` of `flush`, this survives a JVM crash or process kill but not necessarily an operating system crash or power loss; configure `syncLevel` to `fsync` to close that gap at some cost to throughput. +Index files themselves are durable once a hard commit completes. +See xref:configuration-guide:commits-transaction-logs.adoc[] for configuration details. + +An acknowledged update that has reached only the leader can still be lost if the leader is permanently destroyed before any replica receives it. +The durability floor of an acknowledged update is therefore one node, unless the client verifies `rf`. + +== Ordering + +Updates to the *same document* are strictly ordered. +The shard leader serializes concurrent updates to a given document id and assigns each a monotonically increasing `\_version_`; replicas ignore any update older than the version they already have. +The last write accepted by the leader wins. + +There is no ordering guarantee *across different documents*. +Documents sent in one batch may be applied on replicas, and become searchable, in a different order than submitted — especially across shards. + +== Atomicity + +The unit of atomicity is a single document. +A document update fully replaces the previous version of that document (xref:indexing-guide:partial-document-updates.adoc#atomic-updates[atomic updates] are read-modify-write operations performed on the leader, producing a full replacement document). +Queries never observe a partially updated document. + +There are no multi-document transactions. +A batch of documents is processed as independent operations: some may succeed while others fail, and there is no rollback of the documents that succeeded. +Similarly, a delete-by-query spanning multiple shards is not atomic across those shards. + +== Visibility + +An update is not searchable until a commit opens a new searcher; durability (via the transaction log and hard commits) and searchability are independent. Review Comment: Would be worth a note on routing requests by the same user/client to the same replica to combat strange visibility issues. ########## solr/solr-ref-guide/modules/deployment-guide/pages/solrcloud-update-consistency.adoc: ########## @@ -0,0 +1,94 @@ += SolrCloud Update Consistency Model +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +This page states the consistency model of SolrCloud update requests (`/update`): what a successful response guarantees, and what it deliberately does not. +Several of these guarantees are intentionally weaker than those of a transactional database; the trade-offs favor indexing throughput and availability. + +Developers interested in how these guarantees are implemented should read the companion document https://github.com/apache/solr/blob/main/dev-docs/distributed-update-internals.adoc[Distributed Update Internals] in the source repository. + +== What a Successful Update Means + +An update request may be sent to any node in the cluster. +Each document is routed to the leader replica of its shard, which assigns the document a version, applies the update locally, and forwards it to the other in-sync NRT and TLOG replicas of the shard. +PULL replicas never receive individual updates; they periodically copy index segments from the leader. + +A successful (HTTP 200) response guarantees that every document in the request was applied and written to the xref:configuration-guide:commits-transaction-logs.adoc#transaction-log[transaction log] on its shard leader, and that Solr attempted to replicate it to the shard's other in-sync replicas. + +It does *not* guarantee that any replica other than the leader applied the update. +By design, a replica that fails to acknowledge an update does not fail the request; instead the leader marks that replica as out-of-date, and the replica must recover (catch up from the leader) before serving queries or becoming a leader. +Clients that need to know how widely an update was replicated can inspect the achieved replication factor (`rf`) in the response header; it is informational only and is never enforced. +See xref:solrcloud-recoveries-and-write-tolerance.adoc[] for details. + +== Durability + +Every update is written to the leader's transaction log before the response is returned, and replayed on startup if the node was stopped before a hard commit. +With the default transaction log `syncLevel` of `flush`, this survives a JVM crash or process kill but not necessarily an operating system crash or power loss; configure `syncLevel` to `fsync` to close that gap at some cost to throughput. +Index files themselves are durable once a hard commit completes. +See xref:configuration-guide:commits-transaction-logs.adoc[] for configuration details. + +An acknowledged update that has reached only the leader can still be lost if the leader is permanently destroyed before any replica receives it. +The durability floor of an acknowledged update is therefore one node, unless the client verifies `rf`. + +== Ordering + +Updates to the *same document* are strictly ordered. +The shard leader serializes concurrent updates to a given document id and assigns each a monotonically increasing `\_version_`; replicas ignore any update older than the version they already have. +The last write accepted by the leader wins. + +There is no ordering guarantee *across different documents*. +Documents sent in one batch may be applied on replicas, and become searchable, in a different order than submitted — especially across shards. + +== Atomicity Review Comment: Needs more wording around nested documents. And maybe for in-place updates. Should reference the TolerantUpdateProcessor. Should reference the rollback command. ########## dev-docs/distributed-update-internals.adoc: ########## @@ -0,0 +1,232 @@ += Distributed Update Internals (SolrCloud) +:toc: macro +:toclevels: 3 + +toc::[] + +== Why this doc + +The Solr Reference Guide states the user-facing consistency model of SolrCloud updates in +https://github.com/apache/solr/blob/main/solr/solr-ref-guide/modules/deployment-guide/pages/solrcloud-update-consistency.adoc[SolrCloud Update Consistency Model]. +This document explains *how* those guarantees are implemented: the distributed update path from the receiving node through the shard leader to the replicas, and the versioning scheme that everything else leans on. +A particular aim is to give enough precision to reason about idempotency and retry-ability of updates. + +It was written from reading the source of the `main` branch in August 2026. +Things might be off or drift out of date — trust the code over this document, and please fix what you find wrong. + +Class names below are under `solr/core/src/java/org/apache/solr/` unless otherwise noted. + +== Request lifecycle + +An `/update` request is parsed by a loader into a stream of `AddUpdateCommand` / `DeleteUpdateCommand` / `CommitUpdateCommand` objects, each fed through the update request processor (URP) chain. +Everything discussed here happens inside two processors near the end of that chain: `update.processor.DistributedZkUpdateProcessor` (subclass of `DistributedUpdateProcessor`; "DUP" below) and `update.processor.RunUpdateProcessor`. +URPs configured *before* the DUP run only on the node that received the client request; URPs *after* it (and `RunUpdateProcessor`) run on the leader and again on every replica. + +[source,mermaid] +---- +sequenceDiagram + participant C as Client + participant N as Receiving node + participant L as Shard leader + participant R as NRT/TLOG replicas + + C->>N: /update (batch of docs) + N->>L: forward each doc (DistribPhase=TOLEADER) + L->>L: per-doc lock; OCC check; assign _version_ Review Comment: this diagram isn't being rendered by GitHub. And IntelliJ complained on this line "<signal type> or ID expected, got ';'" (GitHub complained likewise) ########## solr/solr-ref-guide/modules/deployment-guide/pages/solrcloud-update-consistency.adoc: ########## @@ -0,0 +1,94 @@ += SolrCloud Update Consistency Model +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +This page states the consistency model of SolrCloud update requests (`/update`): what a successful response guarantees, and what it deliberately does not. +Several of these guarantees are intentionally weaker than those of a transactional database; the trade-offs favor indexing throughput and availability. + +Developers interested in how these guarantees are implemented should read the companion document https://github.com/apache/solr/blob/main/dev-docs/distributed-update-internals.adoc[Distributed Update Internals] in the source repository. + +== What a Successful Update Means Review Comment: "Replication" might be a better heading for the content ########## solr/solr-ref-guide/modules/deployment-guide/pages/solrcloud-update-consistency.adoc: ########## @@ -0,0 +1,94 @@ += SolrCloud Update Consistency Model +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +This page states the consistency model of SolrCloud update requests (`/update`): what a successful response guarantees, and what it deliberately does not. +Several of these guarantees are intentionally weaker than those of a transactional database; the trade-offs favor indexing throughput and availability. + +Developers interested in how these guarantees are implemented should read the companion document https://github.com/apache/solr/blob/main/dev-docs/distributed-update-internals.adoc[Distributed Update Internals] in the source repository. + +== What a Successful Update Means + +An update request may be sent to any node in the cluster. +Each document is routed to the leader replica of its shard, which assigns the document a version, applies the update locally, and forwards it to the other in-sync NRT and TLOG replicas of the shard. +PULL replicas never receive individual updates; they periodically copy index segments from the leader. + +A successful (HTTP 200) response guarantees that every document in the request was applied and written to the xref:configuration-guide:commits-transaction-logs.adoc#transaction-log[transaction log] on its shard leader, and that Solr attempted to replicate it to the shard's other in-sync replicas. + +It does *not* guarantee that any replica other than the leader applied the update. +By design, a replica that fails to acknowledge an update does not fail the request; instead the leader marks that replica as out-of-date, and the replica must recover (catch up from the leader) before serving queries or becoming a leader. +Clients that need to know how widely an update was replicated can inspect the achieved replication factor (`rf`) in the response header; it is informational only and is never enforced. +See xref:solrcloud-recoveries-and-write-tolerance.adoc[] for details. + +== Durability + +Every update is written to the leader's transaction log before the response is returned, and replayed on startup if the node was stopped before a hard commit. +With the default transaction log `syncLevel` of `flush`, this survives a JVM crash or process kill but not necessarily an operating system crash or power loss; configure `syncLevel` to `fsync` to close that gap at some cost to throughput. +Index files themselves are durable once a hard commit completes. +See xref:configuration-guide:commits-transaction-logs.adoc[] for configuration details. + +An acknowledged update that has reached only the leader can still be lost if the leader is permanently destroyed before any replica receives it. +The durability floor of an acknowledged update is therefore one node, unless the client verifies `rf`. + +== Ordering + +Updates to the *same document* are strictly ordered. +The shard leader serializes concurrent updates to a given document id and assigns each a monotonically increasing `\_version_`; replicas ignore any update older than the version they already have. +The last write accepted by the leader wins. + +There is no ordering guarantee *across different documents*. +Documents sent in one batch may be applied on replicas, and become searchable, in a different order than submitted — especially across shards. + +== Atomicity + +The unit of atomicity is a single document. +A document update fully replaces the previous version of that document (xref:indexing-guide:partial-document-updates.adoc#atomic-updates[atomic updates] are read-modify-write operations performed on the leader, producing a full replacement document). +Queries never observe a partially updated document. + +There are no multi-document transactions. +A batch of documents is processed as independent operations: some may succeed while others fail, and there is no rollback of the documents that succeeded. +Similarly, a delete-by-query spanning multiple shards is not atomic across those shards. + +== Visibility + +An update is not searchable until a commit opens a new searcher; durability (via the transaction log and hard commits) and searchability are independent. +Each replica opens its searcher independently, so a document may briefly be searchable on one replica but not another; applications using `autoSoftCommit` or `commitWithin` must embrace this eventual consistency, as described in xref:solrcloud-shards-indexing.adoc#ignoring-commits-from-client-applications-in-solrcloud[Ignoring Commits from Client Applications in SolrCloud]. + +The exception is xref:configuration-guide:realtime-get.adoc[RealTime Get], which retrieves the latest version of a document by id — including uncommitted updates — directly from the transaction log. + +== Optimistic Concurrency Review Comment: should reference DocBasedVersionConstraintsProcessor -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
