Índices de metadata

Mejora el rendimiento de las consultas sobre campos de metadata en Midaz creando índices personalizados en MongoDB para búsquedas rápidas y consistentes.

​

Por qué esto es importante

---

Cada entidad en Midaz admite metadata — pares clave-valor personalizados que extienden el modelo de datos estándar. Las consultas que filtran una colección grande por un campo de metadata pueden volverse lentas sin un índice.

Un índice de metadata es un índice de MongoDB sobre una clave específica de metadata. Transforma un escaneo costoso de colección en una búsqueda rápida por índice. Esto importa sobre todo en producción, donde los volúmenes de transacciones son altos y filtras u ordenas por valores de metadata.

​

Cómo funciona

---

Cuando creas un índice de metadata, Midaz construye un índice de MongoDB sobre el campo metadata.<key> de la colección de la entidad. Después de eso, cualquier consulta que filtre por la clave de metadata usa el índice. MongoDB encuentra los documentos directamente, sin un escaneo completo de la colección.

Los índices son:

• Por entidad: cada índice apunta a un tipo específico de entidad (por ejemplo, transaction, operation).
• Por clave: cada índice cubre una única clave de metadata.
• Unicidad opcional: puedes requerir que dos documentos no compartan el mismo valor para la clave de metadata indexada.
• Sparse por defecto: el índice incluye solo los documentos que tienen la clave de metadata. Esto ahorra almacenamiento y acelera las escrituras.

​

Tipos de entidades soportadas

---

Midaz admite índices de metadata para estas entidades:

Entidad	Colección	Módulo
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

​

Crear un índice de metadata

---

Usa el endpoint Create a Metadata Index:

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

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

Parámetros:

Campo	Tipo	Requerido	Descripción
metadataKey	string	Sí	La clave de metadata a indexar. Debe comenzar con una letra y contener solo caracteres alfanuméricos y guiones bajos. Máximo 100 caracteres.
unique	boolean	No	Si el índice aplica unicidad entre documentos. Predeterminado: false.
sparse	boolean	No	Si el índice solo incluye documentos que tienen la clave de metadata. Predeterminado: true.

Respuesta:

JSON

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

​

Listar índices de metadata

---

Usa el endpoint List Metadata Indexes. Devuelve todos los índices de todos los tipos de entidad con sus estadísticas de uso:

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"
    }
  }
]

El campo stats.accesses muestra cuántas consultas usaron el índice desde que comenzó la recolección de estadísticas. Úsalo para encontrar índices sin uso que puedes eliminar de forma segura.

​

Eliminar un índice de metadata

---

Usa el endpoint Delete a Metadata Index:

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

La eliminación surte efecto de inmediato. Afecta el rendimiento de las consultas de cualquier operación que usó el índice. Antes de eliminar un índice, asegúrate de que ninguna consulta crítica dependa de él.

​

Consideraciones de rendimiento

---

Cuándo crear índices:

• Filtras con frecuencia transacciones u operaciones por una clave de metadata específica (por ejemplo, tier, channel, partner_id).
• Las consultas de listado sobre una colección grande son lentas cuando filtran por metadata.
• Necesitas aplicar unicidad sobre un campo de metadata (por ejemplo, IDs de referencia externos).

Cuándo NO crear índices:

• Rara vez consultas por la clave de metadata — el índice solo cuesta almacenamiento y ralentiza las escrituras.
• La colección es lo suficientemente pequeña como para que los escaneos completos sean rápidos.
• Quieres agregar un índice de forma especulativa, “por si acaso”.

Límites:

Midaz no impone su propio límite de índices de metadata por entidad — se aplica el límite de índices por colección de MongoDB. Crear un índice sobre una clave que ya tiene uno devuelve el error 0132 (Metadata Index Already Exists). Mantén deliberado el número de índices: lista los índices y elimina los que tengan accesses bajos o en cero.

Empieza con índices sobre las claves de metadata que consultas en producción. Usa el campo stats.accesses del endpoint de listado para asegurarte de que las consultas usan cada índice. Elimina los índices que ninguna consulta usa.

​

Páginas relacionadas

---

• Metadata — Cómo funciona la metadata en todas las entidades de Midaz.
• Create a Metadata Index — Referencia de API.
• List Metadata Indexes — Referencia de API.
• Delete a Metadata Index — Referencia de API.