Pular para o conteúdo principal

​
Por que isso importa

Toda entidade no Midaz suporta metadata — pares chave-valor customizados que estendem o modelo de dados padrão. Embora a metadata seja flexível e poderosa, consultar grandes coleções por campos de metadata pode ficar lento sem indexação adequada. Os índices de metadata resolvem isso criando índices no MongoDB sobre chaves específicas de metadata, transformando scans custosos de coleção em buscas rápidas por índice. Isso é especialmente importante em ambientes de produção com altos volumes de transação, onde você filtra ou ordena por valores de metadata.

​
Como funciona

Quando você cria um índice de metadata, o Midaz instrui o MongoDB a construir um índice sobre o campo metadata.<key> da coleção da entidade especificada. A partir desse ponto, qualquer consulta que filtre por essa chave de metadata se beneficia do índice — o MongoDB usa o índice para localizar os documentos correspondentes diretamente em vez de escanear cada documento. Os índices são:
  • Por entidade: cada índice aponta para um tipo específico de entidade (por exemplo, transaction, operation).
  • Por chave: cada índice cobre uma única chave de metadata.
  • Unicidade opcional: você pode garantir que dois documentos da coleção não compartilhem o mesmo valor para a chave de metadata indexada.
  • Sparse por padrão: apenas documentos que realmente têm a chave de metadata indexada são incluídos no índice, economizando armazenamento e melhorando a performance de escrita.

​
Tipos de entidade suportados

Atualmente, os índices de metadata estão disponíveis para as seguintes entidades:
EntidadeColeçãoMódulo
transactionTransactionsTransaction
operationOperationsTransaction
operation_routeOperation RoutesTransaction
transaction_routeTransaction RoutesTransaction
As entidades do módulo Onboarding (organizations, ledgers, accounts, assets, segments, portfolios, account types) suportam metadata, mas atualmente não suportam índices de metadata customizados.

​
Criando um índice de metadata

Use o endpoint Create a Metadata Index: 
{
  "metadataKey": "tier",
  "unique": false,
  "sparse": true
}
Parâmetros:
CampoTipoObrigatórioDescrição
metadataKeystringSimA chave de metadata a ser indexada. Deve começar com uma letra e conter apenas caracteres alfanuméricos e underscores. Máximo 100 caracteres.
uniquebooleanNãoSe o índice deve garantir unicidade entre documentos. Padrão: false.
sparsebooleanNãoSe o índice inclui apenas documentos que possuem a chave de metadata. Padrão: true.
Resposta: 
{
  "indexName": "metadata.tier_1",
  "entityName": "transaction",
  "metadataKey": "tier",
  "unique": false,
  "sparse": true
}

​
Listando índices de metadata

Use o endpoint List Metadata Indexes para ver todos os índices de todos os tipos de entidade, incluindo estatí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
}
O campo stats.accesses mostra quantas consultas usaram o índice desde que a coleta de estatísticas começou — útil para identificar índices não usados que podem ser removidos com segurança.

​
Excluindo um índice de metadata

Use o endpoint Delete a Metadata Index: 
DELETE /v1/settings/metadata-indexes/entities/{entity_name}/key/{index_key}
A exclusão de um índice é imediata e afeta a performance das consultas de qualquer operação que o estivesse usando. Certifique-se de que nenhuma consulta crítica dependa do índice antes de removê-lo.

​
Considerações de performance

Quando criar índices:
  • Você filtra transações ou operações com frequência por uma chave de metadata específica (por exemplo, tier, channel, partner_id).
  • Consultas de listagem em grandes coleções estão lentas ao filtrar por metadata.
  • Você precisa garantir unicidade em um campo de metadata (por exemplo, IDs de referência externos).
Quando NÃO criar índices:
  • A chave de metadata raramente é usada em consultas — índices consomem armazenamento e tornam as escritas mais lentas.
  • A coleção é pequena o suficiente para que full scans sejam rápidos.
  • Você está adicionando índices especulativamente “só por garantia”.
Limites: Existe um número máximo de índices de metadata por entidade. Exceder esse limite retorna o erro 0135 (Metadata Index Limit Exceeded). Se você atingir esse limite, revise os índices existentes usando o endpoint de listagem e remova qualquer um que mostre accesses baixos ou zerados.
Comece com índices nas chaves de metadata que você realmente consulta em produção. Use o campo stats.accesses do endpoint de listagem para validar que seus índices estão sendo usados — e remova os que não estão.

​
Páginas relacionadas