# ProducerBatch

**Kind:** Interface

**Source:** [`packages/microservices/external/kafka.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/microservices/external/kafka.interface.ts#L764)

**Part of:** [Microservices](subsystem-packages-microservices)

`ProducerBatch` defines the configuration and payload for sending multiple Kafka topic messages in a single producer operation. It combines delivery guarantees (`acks`), request timing (`timeout`), compression settings, and one or more topic-specific message groups.

## Properties

| Property | Type |
|---|---|
| `acks` | `number` |
| `timeout` | `number` |
| `compression` | `CompressionTypes` |
| `topicMessages` | `TopicMessages[]` |

## Diagram

```mermaid
graph LR
  PB[ProducerBatch]
  PB --> A[acks: number]
  PB --> T[timeout: number]
  PB --> C[compression: CompressionTypes]
  PB --> TM[topicMessages: TopicMessages[]]

  TM --> Topic[Kafka topic]
  TM --> Messages[Messages to publish]
```

## Usage

```ts
import { CompressionTypes, ProducerBatch } from '@nestjs/microservices';

const batch: ProducerBatch = {
  acks: -1,
  timeout: 30_000,
  compression: CompressionTypes.GZIP,
  topicMessages: [
    {
      topic: 'orders.created',
      messages: [
        {
          key: 'order-123',
          value: JSON.stringify({ orderId: '123', status: 'created' }),
        },
      ],
    },
    {
      topic: 'audit.events',
      messages: [
        {
          value: JSON.stringify({ action: 'order.created', orderId: '123' }),
        },
      ],
    },
  ],
};

await producer.sendBatch(batch);
```

## AI Coding Instructions

- Use `topicMessages` to group messages by Kafka topic when publishing a batch.
- Set `acks` according to the required delivery guarantee; use `-1` when all in-sync replicas must acknowledge writes.
- Keep `timeout` appropriate for broker latency and retry expectations, especially for larger batches.
- Select a `CompressionTypes` value supported by the configured Kafka client and brokers.
- Ensure message keys and values are serialized consistently with consumers before adding them to `topicMessages`.

## How it works

`ProducerBatch` is an exported TypeScript interface representing the argument accepted by the Kafka producer batch-send API. It is part of a file intended to represent KafkaJS package types only, rather than NestJS logic. [packages/microservices/external/kafka.interface.ts:1-8](packages/microservices/external/kafka.interface.ts#L1-L8)

All of its properties are optional:

- `acks?: number`
- `timeout?: number`
- `compression?: CompressionTypes`
- `topicMessages?: TopicMessages[]`  
  [packages/microservices/external/kafka.interface.ts:764-769](packages/microservices/external/kafka.interface.ts#L764-L769)

`topicMessages`, when present, is an array of objects with a required `topic: string` and required `messages: Message[]`. [packages/microservices/external/kafka.interface.ts:759-762](packages/microservices/external/kafka.interface.ts#L759-L762) Each `Message` requires a `value` of `Buffer`, `string`, or `null`; it can also include a key, partition, headers, and timestamp. [packages/microservices/external/kafka.interface.ts:121-127](packages/microservices/external/kafka.interface.ts#L121-L127)

The `compression` field accepts the `CompressionTypes` enum: `None` (`0`), `GZIP` (`1`), `Snappy` (`2`), `LZ4` (`3`), or `ZSTD` (`4`). [packages/microservices/external/kafka.interface.ts:1129-1135](packages/microservices/external/kafka.interface.ts#L1129-L1135)

A `Producer` and a `Transaction` both inherit the `Sender` type, whose `sendBatch(batch: ProducerBatch)` method returns `Promise<RecordMetadata[]>`. [packages/microservices/external/kafka.interface.ts:785-788](packages/microservices/external/kafka.interface.ts#L785-L788) [packages/microservices/external/kafka.interface.ts:798-829](packages/microservices/external/kafka.interface.ts#L798-L829) [packages/microservices/external/kafka.interface.ts:831-836](packages/microservices/external/kafka.interface.ts#L831-L836) Each returned metadata entry includes the topic name, partition, and error code, with optional offset and timestamp-related fields. [packages/microservices/external/kafka.interface.ts:748-757](packages/microservices/external/kafka.interface.ts#L748-L757)

This interface declares no runtime validation, thrown errors, or direct side effects. Its members are type declarations only. [packages/microservices/external/kafka.interface.ts:764-769](packages/microservices/external/kafka.interface.ts#L764-L769)