Skip to content

Commit f13834d

Browse files
authored
Call out caveats when using sendBatch() & createBatch() (Azure#20224)
### Packages impacted by this PR `@azure/event-hub` ### Issues associated with this PR Azure#14400 ### Describe the problem that is addressed by this PR Improving documentation around batching as mentioned in Azure#14400 ### What are the possible designs available to address the problem? If there are more than one possible design, why was the one in this PR chosen? We can further update the code snippet used to showcase batching, but I am trying to go with minimal changes in this PR for now ### Are there test cases added in this PR? _(If not, why?)_ No. Just doc changes
1 parent 6be3947 commit f13834d

File tree

1 file changed

+24
-2
lines changed

1 file changed

+24
-2
lines changed

sdk/eventhub/event-hubs/src/eventHubProducerClient.ts

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,14 @@ export class EventHubProducerClient {
172172
* Creates an instance of `EventDataBatch` to which one can add events until the maximum supported size is reached.
173173
* The batch can be passed to the {@link sendBatch} method of the `EventHubProducerClient` to be sent to Azure Event Hubs.
174174
*
175+
* Events with different values for partitionKey or partitionId will need to be put into different batches.
176+
* To simplify such batch management across partitions or to have the client automatically batch events
177+
* and send them in specific intervals, use `EventHubBufferedProducerClient` instead.
178+
*
179+
* The below example assumes you have an array of events at hand to be batched safely.
180+
* If you have events coming in one by one, `EventHubBufferedProducerClient` is recommended instead
181+
* for effecient management of batches.
182+
*
175183
* Example usage:
176184
* ```ts
177185
* const client = new EventHubProducerClient(connectionString);
@@ -291,7 +299,12 @@ export class EventHubProducerClient {
291299
}
292300

293301
/**
294-
* Sends an array of events to the associated Event Hub.
302+
* Sends an array of events as a batch to the associated Event Hub.
303+
*
304+
* Azure Event Hubs has a limit on the size of the batch that can be sent which if exceeded
305+
* will result in an error with code `MessageTooLargeError`.
306+
* To safely send within batch size limits, use `EventHubProducerClient.createBatch()` or
307+
* `EventHubBufferedProducerClient` instead.
295308
*
296309
* Example usage:
297310
* ```ts
@@ -307,6 +320,7 @@ export class EventHubProducerClient {
307320
* - `partitionKey` : A value that is hashed to produce a partition assignment. If set, `partitionId` can not be set.
308321
*
309322
* @returns Promise<void>
323+
* @throws MessageTooLargeError if all the events in the input array cannot be fit into a batch.
310324
* @throws AbortError if the operation is cancelled via the abortSignal.
311325
* @throws MessagingError if an error is encountered while sending a message.
312326
* @throws Error if the underlying connection or sender has been closed.
@@ -316,7 +330,15 @@ export class EventHubProducerClient {
316330
options?: SendBatchOptions
317331
): Promise<void>;
318332
/**
319-
* Sends a batch of events to the associated Event Hub.
333+
* Sends a batch of events created using `EventHubProducerClient.createBatch()` to the associated Event Hub.
334+
*
335+
* Events with different values for partitionKey or partitionId will need to be put into different batches.
336+
* To simplify such batch management across partitions or to have the client automatically batch events
337+
* and send them in specific intervals, use `EventHubBufferedProducerClient` instead.
338+
*
339+
* The below example assumes you have an array of events at hand to be batched safely.
340+
* If you have events coming in one by one, `EventHubBufferedProducerClient` is recommended instead
341+
* for effecient management of batches.
320342
*
321343
* Example usage:
322344
* ```ts

0 commit comments

Comments
 (0)