Azure-docs: The intro paragraphs about push and pull models are confusing.

[konrad-jamrozik]

These paragraphs are confusing:

_You can work with the Azure Cosmos DB change feed using either a push model or a pull model. With a push model, a client requests work from a server and has business logic for processing a change. However, the complexity in checking for changes and storing state for the last processed changes is handled on the server._

_With a pull model, a server requests work, often requesting it from a central work queue. The client, in this case, not only has business logic for processing changes but also storing state for the last processed change, handling load balancing across multiple clients processing changes in parallel, and handling errors._

Here is why they are confusing:

I am trying to understand how I am supposed to interact from my code with the change feed. While doing that, based on the paragraphs, I have problem trying to answer these questions:

• Who is doing the pushing? The change feed, or my code?
• Who is doing the pulling? The change feed, or my code?
• What does it mean "to request work from X"? Does it mean invoking some method on X (aka pushing a request for work to X) ?
• Does requesting work mean "please process this work for me and let me know when you are done" or does it mean "hey, I can do some work for you, please send it to me" ? These are opposite meanings, and it is not clear which one is it.
• Who plays the role of server or client here? My code, or the change feed? Or does it flip around depending on the context (perhaps on who is initiating the pull/push) ?
• For a moment I thought that the _client_ is _my code_ and _server_ is the change feed, but then it says that in the 2nd paragraph that the server requests work from some central work queue. So now we have three actors here: my code, the change feed, and... central work queue? Who is what?

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 3eeb8721-2a9d-3972-c431-359909a3c4f2
• Version Independent ID: 32f88bb1-00ee-fbf2-a285-b1ceb51e9340
• Content: Reading Azure Cosmos DB change feed
• Content Source: articles/cosmos-db/read-change-feed.md
• Service: cosmos-db
• GitHub Login: @timsander1
• Microsoft Alias: tisande

[NavtejSaini-MSFT]

@konrad-jamrozik We are checking this and we will get back to you.

[timsander1]

Hi @konrad-jamrozik. That paragraph is just intended to be a general introduction to push model vs pull architectures. Could you keep reading the doc and let me know if that covers your questions? I'm happy to cover any remaining questions here.

[konrad-jamrozik]

@timsander1 Here is my current best bet on the meaning:

The client is my code.
The server is the change feed.
In case of the push model (paragraph 1), the change feed _pushes_ the notification to my code there is work to be done. This is written as a client requests work from a server which appears to me to be false? I mean, the client is not requesting anything, the change feed is pushing the notification, isn't it?

In case of the client model (paragraph 2), the change feed _requests work_ from the central work queue, but this is internal implementation detail hidden from my client code. I can now query the change feed (or _pull_ from it) to process the change. Thus, in this paragraph _requesting work_ has different meaning.

Am I correct in my interpretation?

[konrad-jamrozik]

@timsander1 even if this is intended as very high level broad introduction, I would still say it would be good to have consistent meaning of the phrase _to request work_ and make sure it makes intuitive sense, that is, if X request work from Y it means that X invokes something on Y, and Y doesn't do anything actively, just receives the call and starts processing. If my thinking is correct, the meaning of requesting work is now opposite to that, causing my confusion.

[konrad-jamrozik]

How about a rewrite like this (diff in bold)

_You can work with the Azure Cosmos DB change feed using either a push model or a pull model. With a push model, a server pushes work to a client that has business logic for processing this work. However, the complexity in checking for work and storing state for the last processed work is handled on the server._

_With a pull model, the client has to pull the work from the server. The client, in this case, not only has business logic for processing work but also storing state for the last processed work, handling load balancing across multiple clients processing work in parallel, and handling errors._

[timsander1]

Ah, I see what you mean. I'll submit a docs update to reword that section tonight. I agree that the meaning of "request work" is a little different in paragraph 1 and paragraph 2 and that is unclear.

But yes, your assumptions are correct. For the second paragraph - "With a pull model, a server requests work, often requesting it from a central work queue." In this case, the "central work queue" is the change feed. With the pull model, you request changes from the change feed at your own pace, the changes aren't "pushed" to your code.

[konrad-jamrozik]

@timsander1 awesome, thx! :)

[timsander1]

I like your reword :). Mind if I use that? You're welcome to submit the PR yourself if you prefer

[konrad-jamrozik]

@timsander1 ok I'll submit a PR and refer to this discussion in it.

[SnehaGunda]

Thanks @konrad-jamrozik and @timsander1 it looks like the issue is resolved. Closing it now.

please-close