Saltar al contenido principal

​
Por qué esto es importante

Cada entidad en Midaz admite metadata — pares clave-valor personalizados que extienden el modelo de datos estándar. Aunque la metadata es flexible y poderosa, consultar colecciones grandes por campos de metadata puede volverse lento sin un indexado adecuado. Los índices de metadata resuelven esto creando índices en MongoDB sobre claves específicas de metadata, transformando escaneos costosos de colección en búsquedas rápidas por índice. Esto es especialmente importante en entornos de producción con altos volúmenes de transacciones donde filtras u ordenas por valores de metadata.

​
Cómo funciona

Cuando creas un índice de metadata, Midaz le indica a MongoDB que construya un índice sobre el campo metadata.<key> de la colección de la entidad especificada. A partir de ese momento, cualquier consulta que filtre por esa clave de metadata se beneficia del índice — MongoDB usa el índice para localizar directamente los documentos coincidentes en lugar de escanear cada documento. 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 aplicar que dos documentos de la colección no compartan el mismo valor para la clave de metadata indexada.
  • Sparse por defecto: solo los documentos que realmente tienen la clave de metadata indexada se incluyen en el índice, ahorrando almacenamiento y mejorando el rendimiento de escritura.

​
Tipos de entidades soportadas

Actualmente, los índices de metadata están disponibles para las siguientes entidades:
EntidadColecciónMódulo
transactionTransactionsTransaction
operationOperationsTransaction
operation_routeOperation RoutesTransaction
transaction_routeTransaction RoutesTransaction
Las entidades del módulo Onboarding (organizaciones, ledgers, cuentas, assets, segmentos, portafolios, tipos de cuenta) admiten metadata, pero actualmente no admiten índices de metadata personalizados.

​
Crear un índice de metadata

Usa el endpoint Create a Metadata Index: 
{
  "metadataKey": "tier",
  "unique": false,
  "sparse": true
}
Parámetros:
CampoTipoRequeridoDescripción
metadataKeystringSíLa clave de metadata a indexar. Debe comenzar con una letra y contener solo caracteres alfanuméricos y guiones bajos. Máximo 100 caracteres.
uniquebooleanNoSi el índice aplica unicidad entre documentos. Predeterminado: false.
sparsebooleanNoSi el índice solo incluye documentos que tienen la clave de metadata. Predeterminado: true.
Respuesta: 
{
  "indexName": "metadata.tier_1",
  "entityName": "transaction",
  "metadataKey": "tier",
  "unique": false,
  "sparse": true
}

​
Listar índices de metadata

Usa el endpoint List Metadata Indexes para ver todos los índices de todos los tipos de entidad, incluyendo estadísticas de uso: 
{
  "items": [
    {
      "indexName": "metadata.tier_1",
      "entityName": "transaction",
      "metadataKey": "tier",
      "unique": false,
      "sparse": true,
      "stats": {
        "accesses": 1523,
        "statsSince": "2024-12-01T10:30:00Z"
      }
    }
  ],
  "page": 1,
  "limit": 10
}
El campo stats.accesses muestra cuántas consultas han usado el índice desde que comenzó la recolección de estadísticas — útil para identificar índices sin uso que pueden eliminarse 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 de un índice es inmediata y afecta el rendimiento de las consultas de cualquier operación que lo estuviera usando. Asegúrate de que ninguna consulta crítica dependa del índice antes de eliminarlo.

​
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 colecciones grandes son lentas al filtrar por metadata.
  • Necesitas aplicar unicidad sobre un campo de metadata (por ejemplo, IDs de referencia externos).
Cuándo NO crear índices:
  • La clave de metadata se usa raramente en consultas — los índices consumen almacenamiento y ralentizan las escrituras.
  • La colección es lo suficientemente pequeña como para que los escaneos completos sean rápidos.
  • Estás agregando índices de forma especulativa “por si acaso”.
Límites: Existe un número máximo de índices de metadata por entidad. Al superar este límite se devuelve el error 0135 (Metadata Index Limit Exceeded). Si alcanzas este límite, revisa los índices existentes usando el endpoint de listado y elimina los que muestren accesses bajos o en cero.
Empieza con índices sobre las claves de metadata que realmente consultas en producción. Usa el campo stats.accesses del endpoint de listado para validar que tus índices se estén usando — y elimina los que no.

​
Páginas relacionadas