Índices de metadata

Por que isso importa

Toda entidade no Midaz suporta metadata — pares chave-valor customizados que estendem o modelo de dados padrão. Consultas que filtram uma coleção grande por um campo de metadata podem ficar lentas sem um índice. Um índice de metadata é um índice do MongoDB sobre uma chave específica de metadata. Ele transforma um scan custoso de coleção em uma busca rápida por índice. Isso importa mais em produção, onde os volumes de transação são altos e você filtra ou ordena por valores de metadata.

Como funciona

Quando você cria um índice de metadata, o Midaz constrói um índice do MongoDB sobre o campo metadata.<key> da coleção da entidade. Depois disso, qualquer consulta que filtre pela chave de metadata usa o índice. O MongoDB encontra os documentos diretamente, sem um scan completo da coleção. 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 exigir que dois documentos não compartilhem o mesmo valor para a chave de metadata indexada.
Sparse por padrão: o índice inclui apenas os documentos que têm a chave de metadata. Isso economiza armazenamento e acelera as escritas.

Tipos de entidade suportados

O Midaz suporta índices de metadata para estas entidades:

Entidade	Coleção	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

Criando um índice de metadata

Use o endpoint Create a Metadata Index:

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

Parâmetros:

Campo	Tipo	Obrigatório	Descrição
`metadataKey`	string	Sim	A chave de metadata a ser indexada. Deve começar com uma letra e conter apenas caracteres alfanuméricos e underscores. Máximo 100 caracteres.
`unique`	boolean	Não	Se o índice deve garantir unicidade entre documentos. Padrão: `false`.
`sparse`	boolean	Não	Se 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. Ele retorna todos os índices de todos os tipos de entidade com suas estatísticas de uso:

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

O campo stats.accesses mostra quantas consultas usaram o índice desde que a coleta de estatísticas começou. Use-o para encontrar índices sem uso que você pode excluir 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 tem efeito imediato. Ela afeta a performance das consultas de qualquer operação que usou o índice. Antes de excluir um índice, certifique-se de que nenhuma consulta crítica dependa dele.

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 uma coleção grande são lentas quando filtram por metadata.
Você precisa garantir unicidade em um campo de metadata (por exemplo, IDs de referência externos).

Quando NÃO criar índices:

Você raramente consulta pela chave de metadata — o índice só custa armazenamento e torna as escritas mais lentas.
A coleção é pequena o suficiente para que full scans sejam rápidos.
Você quer adicionar um índice de forma especulativa, “só por garantia”.

Limites: O Midaz não impõe um limite próprio de índices de metadata por entidade — vale o limite de índices por coleção do MongoDB. Criar um índice em uma chave que já tem um retorna o erro 0132 (Metadata Index Already Exists). Mantenha a quantidade de índices deliberada: liste os índices e exclua os que tiverem accesses baixos ou zerados.

Comece com índices nas chaves de metadata que você consulta em produção. Use o campo stats.accesses do endpoint de listagem para se certificar de que as consultas usam cada índice. Exclua os índices que nenhuma consulta usa.

Páginas relacionadas

Metadata — Como a metadata funciona em todas as entidades do Midaz.
Create a Metadata Index — Referência de API.
List Metadata Indexes — Referência de API.
Delete a Metadata Index — Referência de API.

Midaz Core

CRM

Fees

Índices de metadata

Por que isso importa

Como funciona

Tipos de entidade suportados

Criando um índice de metadata

Listando índices de metadata

Excluindo um índice de metadata

Considerações de performance

Páginas relacionadas

​Por que isso importa

​Como funciona

​Tipos de entidade suportados

​Criando um índice de metadata

​Listando índices de metadata

​Excluindo um índice de metadata

​Considerações de performance

​Páginas relacionadas

Por que isso importa

Como funciona

Tipos de entidade suportados

Criando um índice de metadata

Listando índices de metadata

Excluindo um índice de metadata

Considerações de performance

Páginas relacionadas