# FilterByMetadataKey

**Kind:** Interface

**Source:** [`packages/core/discovery/discovery-service.ts`](https://github.com/nestjs/nest/blob/master/packages/core/discovery/discovery-service.ts#L26)

**Part of:** [Core](subsystem-packages-core)

`FilterByMetadataKey` defines a discovery filter that targets entities containing a specific metadata key. It is used by the discovery service to narrow query results based on metadata structure rather than a metadata value.

## Properties

| Property | Type |
|---|---|
| `metadataKey` | `string` |

## Diagram

```mermaid
graph LR
  Client[Discovery Client] --> Filter[FilterByMetadataKey]
  Filter --> Key[metadataKey: string]
  Key --> DiscoveryService[Discovery Service]
  DiscoveryService --> Results[Matching Entities]
```

## Usage

```ts
import type { FilterByMetadataKey } from './discovery-service';

const filter: FilterByMetadataKey = {
  metadataKey: 'environment',
};

// Pass the filter to the discovery service API that accepts metadata filters.
const results = await discoveryService.discover({
  filters: [filter],
});
```

## AI Coding Instructions

- Provide a non-empty `metadataKey` that matches the metadata field name stored on discoverable entities.
- Use this interface when filtering by key presence; use a different filter type when matching specific metadata values.
- Keep filter objects serializable because they may be passed through discovery request boundaries.
- Ensure discovery service consumers handle empty result sets when no entities contain the requested key.