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 — 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 endpoint:

POST /v1/settings/metadata-indexes/entities/{entity_name}

{
  "metadataKey": "tier",
  "unique": false,
  "sparse": true
}

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:

JSON

{
  "indexName": "metadata.tier_1",
  "entityName": "transaction",
  "metadataKey": "tier",
  "unique": false,
  "sparse": true
}

Listing metadata indexes

---

Use the List Metadata Indexes endpoint. It returns all indexes across all entity types with their usage statistics:

GET /v1/settings/metadata-indexes

[
  {
    "indexName": "metadata.tier_1",
    "entityName": "transaction",
    "metadataKey": "tier",
    "unique": false,
    "sparse": true,
    "stats": {
      "accesses": 1523,
      "statsSince": "2024-12-01T10:30:00Z"
    }
  }
]

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 endpoint:

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

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.

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.

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.

Related pages

---

• Metadata — How metadata works across all Midaz entities.
• Create a Metadata Index — API reference.
• List Metadata Indexes — API reference.
• Delete a Metadata Index — API reference.