# ITopicMetadata

**Kind:** Interface

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

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

`ITopicMetadata` describes Kafka topic metadata returned or consumed by the microservices Kafka integration. It identifies a topic by name and provides metadata for each of its partitions, enabling clients to inspect topic topology and partition-level state.

## Properties

| Property | Type |
|---|---|
| `name` | `string` |
| `partitions` | `PartitionMetadata[]` |

## Diagram

```mermaid
graph LR
  TopicMetadata["ITopicMetadata"]
  Name["name: string"]
  Partitions["partitions: PartitionMetadata[]"]

  TopicMetadata --> Name
  TopicMetadata --> Partitions
  Partitions --> Partition1["PartitionMetadata"]
  Partitions --> PartitionN["PartitionMetadata"]
```

## Usage

```ts
import type { ITopicMetadata } from './kafka.interface';

const topicMetadata: ITopicMetadata = {
  name: 'orders.created',
  partitions: [
    {
      partitionId: 0,
      leader: 1,
      replicas: [1, 2, 3],
      isr: [1, 2, 3],
    },
  ],
};

console.log(
  `Topic "${topicMetadata.name}" has ${topicMetadata.partitions.length} partition(s).`,
);
```

## AI Coding Instructions

- Always provide a non-empty, valid Kafka topic name in `name`.
- Populate `partitions` with `PartitionMetadata` objects returned by or compatible with the Kafka metadata client.
- Treat partition metadata as a snapshot; refresh it when leader, replica, or partition assignments may have changed.
- Do not assume partition array indexes match partition IDs; use the partition identifier exposed by each `PartitionMetadata` entry.
- Keep this interface aligned with the Kafka adapter's metadata response shape when upgrading Kafka client dependencies.