> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata indexes

> Create MongoDB metadata indexes on transactions, operations, and routes to speed up queries and filters on custom metadata keys in high-volume Midaz setups.

## Why this matters

***

Every entity in Midaz supports [metadata](/en/reference/metadata) — custom key-value pairs that extend the standard data model. Queries that filter a large collection by a metadata field can become slow without an index.

A metadata index is a MongoDB index on a specific metadata key. It turns an expensive collection scan into a fast indexed lookup. This matters most in production, where transaction volumes are high and you filter or sort by metadata values.

## How it works

***

When you create a metadata index, Midaz builds a MongoDB index on the `metadata.<key>` field of the entity collection. After that, any query that filters by the metadata key uses the index. MongoDB finds the documents directly, without a full collection scan.

Indexes are:

* **Per-entity**: Each index targets a specific entity type (e.g., `transaction`, `operation`).
* **Per-key**: Each index covers a single metadata key.
* **Optional uniqueness**: You can require that no two documents share the same value for the indexed metadata key.
* **Sparse by default**: The index includes only documents that have the metadata key. This saves storage and speeds up writes.

## Supported entity types

***

Midaz supports metadata indexes for these entities:

| Entity              | Collection         | Module      |
| :------------------ | :----------------- | :---------- |
| `transaction`       | Transactions       | Transaction |
| `operation`         | Operations         | Transaction |
| `operation_route`   | Operation Routes   | Transaction |
| `transaction_route` | Transaction Routes | Transaction |
| `organization`      | Organizations      | Onboarding  |
| `ledger`            | Ledgers            | Onboarding  |
| `account`           | Accounts           | Onboarding  |
| `asset`             | Assets             | Onboarding  |
| `segment`           | Segments           | Onboarding  |
| `portfolio`         | Portfolios         | Onboarding  |
| `account_type`      | Account Types      | Onboarding  |

## Creating a metadata index

***

Use the [Create a Metadata Index](/en/reference/midaz/create-a-metadata-index) endpoint:

<CodeGroup>
  ```json POST /v1/settings/metadata-indexes/entities/{entity_name} theme={null}
  {
    "metadataKey": "tier",
    "unique": false,
    "sparse": true
  }
  ```
</CodeGroup>

**Parameters:**

| Field         | Type    | Required | Description                                                                                                                       |
| :------------ | :------ | :------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `metadataKey` | string  | Yes      | The metadata key to index. Must start with a letter and contain only alphanumeric characters and underscores. Max 100 characters. |
| `unique`      | boolean | No       | Whether the index enforces uniqueness across documents. Default: `false`.                                                         |
| `sparse`      | boolean | No       | Whether the index only includes documents that have the metadata key. Default: `true`.                                            |

**Response:**

<CodeGroup>
  ```json JSON theme={null}
  {
    "indexName": "metadata.tier_1",
    "entityName": "transaction",
    "metadataKey": "tier",
    "unique": false,
    "sparse": true
  }
  ```
</CodeGroup>

## Listing metadata indexes

***

Use the [List Metadata Indexes](/en/reference/midaz/list-metadata-indexes) endpoint. It returns all indexes across all entity types with their usage statistics:

<CodeGroup>
  ```json GET /v1/settings/metadata-indexes theme={null}
  [
    {
      "indexName": "metadata.tier_1",
      "entityName": "transaction",
      "metadataKey": "tier",
      "unique": false,
      "sparse": true,
      "stats": {
        "accesses": 1523,
        "statsSince": "2024-12-01T10:30:00Z"
      }
    }
  ]
  ```
</CodeGroup>

The `stats.accesses` field shows how many queries used the index since statistics collection started. Use it to find unused indexes that you can safely delete.

## Deleting a metadata index

***

Use the [Delete a Metadata Index](/en/reference/midaz/delete-a-metadata-index) endpoint:

```
DELETE /v1/settings/metadata-indexes/entities/{entity_name}/key/{index_key}
```

<Danger>
  Deletion takes effect immediately. It affects query performance for any operation that used the index. Before you delete an index, make sure no critical query depends on it.
</Danger>

## Performance considerations

***

**When to create indexes:**

* You frequently filter transactions or operations by a specific metadata key (e.g., `tier`, `channel`, `partner_id`).
* List queries on a large collection are slow when they filter by metadata.
* You need to enforce uniqueness on a metadata field (e.g., external reference IDs).

**When NOT to create indexes:**

* You rarely query by the metadata key — the index only costs storage and slows writes.
* The collection is small enough that full scans are fast.
* You want to add an index speculatively, "just in case."

**Limits:**

Midaz does not enforce its own cap on the number of metadata indexes per entity — MongoDB's per-collection index limit applies instead. Creating an index on a key that already has one returns error `0132` (Metadata Index Already Exists). Keep the index count deliberate: list the indexes and delete any with low or zero `accesses`.

<Tip>
  Start with indexes on the metadata keys you query in production. Use the `stats.accesses` field from the list endpoint to make sure queries use each index. Delete the indexes that no query uses.
</Tip>

## Related pages

***

* [Metadata](/en/reference/metadata) — How metadata works across all Midaz entities.
* [Create a Metadata Index](/en/reference/midaz/create-a-metadata-index) — API reference.
* [List Metadata Indexes](/en/reference/midaz/list-metadata-indexes) — API reference.
* [Delete a Metadata Index](/en/reference/midaz/delete-a-metadata-index) — API reference.