[GitHub] [pulsar] BewareMyPower commented on a change in pull request #11720: [docs] [ISSUE 8357] Add description and examples for key-based batching for Key_Shared subscription mode

[GitBox <gi...@apache.org>]

BewareMyPower commented on a change in pull request #11720:
URL: https://github.com/apache/pulsar/pull/11720#discussion_r692610253



##########
File path: site2/docs/concepts-messaging.md
##########
@@ -345,15 +343,43 @@ In the diagram below, **Consumer-C-1** and **Consumer-C-2** are able to subscrib
 
 In *Key_Shared* mode, multiple consumers can attach to the same subscription. Messages are delivered in a distribution across consumers and message with same key or same ordering key are delivered to only one consumer. No matter how many times the message is re-delivered, it is delivered to the same consumer. When a consumer connected or disconnected will cause served consumer change for some key of message.
 
+![Key_Shared subscriptions](assets/pulsar-key-shared-subscriptions.png)
+
+Note that when the consumers are using the Key_Shared subscription mode, you need to **disable batching** or **use key-based batching** for the producers. There are two reasons why the key-based bathcing is necessary for Key_Shared subscription mode:
+1. The broker dispatches messages according to the keys of the messages, but the default batching approach might fail to pack the messages with the same key to the same batch. 
+2. Since it is the consumers instead of the broker who dispatch the messages from the batches, the key of the first message in one batch will be considered as the key of all messages in this batch, thereby leading to context errors. 
+
+The key-based batching aims at resolving the abovementioned issues. This batching method ensures that the producers pack the messages with the same key to the same batch. The messages without a key will be packed into one batch, using an empty string as the key. In addition, each consumer is associated with **only one** key and should receive **only one message batch** for the connected key. By default, you can limit batching by configuring the number of messages that producers are allowed to send. 

Review comment:
       > The messages without a key will be packed into one batch, using an empty string as the key.
   
   It's right that the messages without a key will be packed into one batch. But the batch is still treated as having no key, instead of an empty string as the key.
   
   BTW, When broker dispatches these messages (batches) without any key in `Key_shared` mode, broker treats its key as `NONE_KEY`.




-- 
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: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org