# ProducerRecord

**Kind:** Interface

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

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

`ProducerRecord` defines the payload and delivery options for publishing one or more messages to an Apache Kafka topic. It groups the target topic, message batch, acknowledgement behavior, request timeout, and compression strategy used by the Kafka producer.

## Properties

| Property | Type |
|---|---|
| `topic` | `string` |
| `messages` | `Message[]` |
| `acks` | `number` |
| `timeout` | `number` |
| `compression` | `CompressionTypes` |

## Diagram

```mermaid
graph LR
  ProducerRecord[ProducerRecord]
  Topic[topic: string]
  Messages[messages: Message[]]
  Acks[acks: number]
  Timeout[timeout: number]
  Compression[compression: CompressionTypes]

  ProducerRecord --> Topic
  ProducerRecord --> Messages
  ProducerRecord --> Acks
  ProducerRecord --> Timeout
  ProducerRecord --> Compression
  Messages --> Kafka[Kafka topic]
```

## Usage

```ts
import { CompressionTypes } from 'kafkajs';
import type { ProducerRecord } from '@nestjs/microservices';

const record: ProducerRecord = {
  topic: 'orders.created',
  messages: [
    {
      key: 'order-123',
      value: JSON.stringify({
        orderId: 'order-123',
        customerId: 'customer-456',
        total: 99.95,
      }),
      headers: {
        eventType: 'order.created',
      },
    },
  ],
  acks: -1,
  timeout: 30_000,
  compression: CompressionTypes.GZIP,
};

await producer.send(record);
```

## AI Coding Instructions

- Provide a valid Kafka topic name and include at least one item in `messages`.
- Serialize structured message values with `JSON.stringify()` unless the producer integration handles serialization.
- Use `acks: -1` when durability is important; lower acknowledgement settings can improve throughput but reduce delivery guarantees.
- Set `timeout` according to expected broker/network latency, especially for larger message batches.
- Select a `CompressionTypes` value supported by the configured Kafka client and cluster.

## How it works

`ProducerRecord` is an exported TypeScript interface in the KafkaJS type-only declaration surface; the file explicitly says it represents KafkaJS package types and should not contain NestJS logic. [packages/microservices/external/kafka.interface.ts:1-8](packages/microservices/external/kafka.interface.ts#L1-L8)

It describes the record object passed to a Kafka `Producer` or `Transaction` sender:

- `topic` is required and has type `string`. [packages/microservices/external/kafka.interface.ts:740-742](packages/microservices/external/kafka.interface.ts#L740-L742)
- `messages` is required and is an array of `Message` objects. [packages/microservices/external/kafka.interface.ts:740-742](packages/microservices/external/kafka.interface.ts#L740-L742) A `Message` requires a `value` of `Buffer | string | null`; it can also carry an optional `key`, `partition`, `headers`, and `timestamp`. [packages/microservices/external/kafka.interface.ts:121-127](packages/microservices/external/kafka.interface.ts#L121-L127)
- `acks`, `timeout`, and `compression` are optional record-level fields. `acks` and `timeout` are numbers; `compression` is typed as `CompressionTypes`. [packages/microservices/external/kafka.interface.ts:740-746](packages/microservices/external/kafka.interface.ts#L740-L746)

`ProducerRecord` is the argument to `Sender.send()`, which returns a `Promise<RecordMetadata[]>`. [packages/microservices/external/kafka.interface.ts:785-788](packages/microservices/external/kafka.interface.ts#L785-L788) `Producer` and `Transaction` both include that sender contract. [packages/microservices/external/kafka.interface.ts:798-829](packages/microservices/external/kafka.interface.ts#L798-L836) Each returned metadata entry includes a 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)

For Nest Kafka transport configuration, `KafkaOptions.options.send` accepts `ProducerRecord` fields except `topic` and `messages`. [packages/microservices/interfaces/microservice-configuration.interface.ts:333-355](packages/microservices/interfaces/microservice-configuration.interface.ts#L333-L355) The Kafka client constructs records with a normalized pattern as `topic` and serialized event data as `messages`, merges `options.send` into that object, then calls `producer.send()`. [packages/microservices/client/client-kafka.ts:339-360](packages/microservices/client/client-kafka.ts#L339-L360) The same construction occurs for individual events and request messages. [packages/microservices/client/client-kafka.ts:363-376](packages/microservices/client/client-kafka.ts#L363-L376) [packages/microservices/client/client-kafka.ts:407-424](packages/microservices/client/client-kafka.ts#L407-L424) Server replies likewise form a record from the reply topic and serialized message, merge `options.send`, and send it. [packages/microservices/server/server-kafka.ts:304-326](packages/microservices/server/server-kafka.ts#L304-L326)

This interface contains no runtime validation, error handling, or side-effecting implementation; it only declares the object shape. [packages/microservices/external/kafka.interface.ts:740-746](packages/microservices/external/kafka.interface.ts#L740-L746)