Documentation is misleading regarding write consistency

[haizaar]

The guide says:

Here is the sequence of steps necessary to successfully create, index, or delete a document on both the primary and any replica shards:

1. The client sends a create, index, or delete request to Node 1.
2. The node uses the document’s _id to determine that the document belongs to shard 0. It forwards the request to Node 3, where the primary copy of shard 0 is currently allocated.
3. Node 3 executes the request on the primary shard. If it is successful, it forwards the request in parallel to the replica shards on Node 1 and Node 2. Once all of the replica shards report success, Node 3 reports success to the coordinating node, which reports success to the client.

However according to the latest resiliency talk from Elastic{ON} 2016, this is not the case, otherwise #7572 would not happen. According to the presenter (and the comment in the issue), the actual situation is as follows:

1. Primary shard receives indexing request
2. Primary shard checks that all/quorum replicas are online and fails request otherwise
3. Primary shard performs index operation on itself
4. Primary shard acks success to the client
5. Primary shard sends indexing request to replicas

The documentation is very misleading making a reader to believe that by the time he gets ack, its data already exists on all/quorum replicas, i.e. safe; and that's not the case.

I think that this behavior should be clearly outlined, until this issue is fixed in 5.x, both in the guide link above and in the reference.

[eskibars]

We're aware of a number of issues with the definitive guide, which wasn't updated for 2.x. Unfortunately, this is just one exampke of quite a number of pages in that book which are not accurate currently. So we're actively in the process of rewriting it, as noted at the top of all pages in that guide. Thanks for pointing this one out specifically.

[haizaar]

Will it help if I submit pull request that clarifies the issue?
On 25 Feb 2016 8:31 pm, "Shane Connelly" notifications@github.com wrote:

We're aware of a number of issues with the definitive guide, which wasn't
updated for 2.x. Unfortunately, this is just one exampke of quite a number
of pages in that book which are not accurate currently. So we're actively
in the process of rewriting it, as noted at the top of all pages in that
guide. Thanks for pointing this one out specifically.

—
Reply to this email directly or view it on GitHub
#16728 (comment)
.

[clintongormley]

Hi @haizaar

Actually, your list is not correct:

Primary shard receives indexing request
Primary shard checks that all/quorum replicas are online and fails request otherwise

It waits for the timeout period for the replica shards to become available before failing.

Primary shard performs index operation on itself
Primary shard acks success to the client

This only happens once all active shards have either successfully indexed the document or have been marked as failed shards by the primary.

Primary shard sends indexing request to replicas

You're welcome to submit a PR, but the repo for the guide is here: https://github.com/elastic/elasticsearch-definitive-guide/issues