Índices de metadados

Por que isso importa

Toda entidade no Midaz aceita metadados: pares personalizados de chave-valor que estendem o modelo de dados padrão. Consultas que filtram uma coleção grande por um campo de metadados podem ficar lentas sem um índice. Um índice de metadados é um índice do MongoDB em uma chave de metadados específica. Ele transforma uma varredura cara da coleção em uma busca rápida por índice. Isso importa mais em produção, onde os volumes de transações são altos e você filtra ou ordena por valores de metadados.

Como funciona

Quando você cria um índice de metadados, o Midaz cria um índice do MongoDB no campo metadata.<key> da coleção da entidade. Depois disso, qualquer consulta que filtra pela chave de metadados usa o índice. O MongoDB encontra os documentos diretamente, sem uma varredura completa da coleção. Os índices são:

Por entidade: cada índice tem como alvo um tipo de entidade específico (por exemplo, transaction, operation).
Por chave: cada índice cobre uma única chave de metadados.
Unicidade opcional: você pode exigir que nenhum documento compartilhe o mesmo valor para a chave de metadados indexada.
Esparso por padrão: o índice inclui apenas os documentos que têm a chave de metadados. Isso economiza armazenamento e acelera as escritas.

Tipos de entidade compatíveis

O Midaz oferece suporte a índices de metadados 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 metadados

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 metadados a indexar. Deve começar com uma letra e conter apenas caracteres alfanuméricos e underscores. Máximo de 100 caracteres.
`unique`	boolean	Não	Se o índice aplica unicidade entre documentos. Padrão: `false`.
`sparse`	boolean	Não	Se o índice inclui apenas os documentos que têm a chave de metadados. Padrão: `true`.

Resposta:

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

Listando índices de metadados

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 o início da coleta de estatísticas. Use-o para encontrar índices não utilizados que você pode excluir com segurança.

Excluindo um índice de metadados

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 o desempenho de consultas de qualquer operação que usava o índice. Antes de excluir um índice, confirme que nenhuma consulta crítica depende dele.

Considerações de desempenho

Quando criar índices:

Você filtra transações ou operações com frequência por uma chave de metadados específica (por exemplo, tier, channel, partner_id).
Consultas de listagem em uma coleção grande ficam lentas quando filtram por metadados.
Você precisa aplicar unicidade em um campo de metadados (por exemplo, IDs de referência externa).

Quando NÃO criar índices:

Você raramente consulta pela chave de metadados. O índice apenas consome armazenamento e deixa as escritas mais lentas.
A coleção é pequena o suficiente para que varreduras completas sejam rápidas.
Você quer adicionar um índice de forma especulativa, “só por precaução”.

Limites: O Midaz não aplica um limite próprio para o número de índices de metadados por entidade. Em vez disso, 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 contagem de índices deliberada: liste os índices e exclua qualquer um com accesses baixo ou zero.

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

Páginas relacionadas

Metadados: como os metadados funcionam em todas as entidades do Midaz.
Create a Metadata Index: referência da API.
List Metadata Indexes: referência da API.
Delete a Metadata Index: referência da API.

Midaz Core

CRM

Fees

Índices de metadados

Por que isso importa

Como funciona

Tipos de entidade compatíveis

Criando um índice de metadados

Listando índices de metadados

Excluindo um índice de metadados

Considerações de desempenho

Páginas relacionadas

​Por que isso importa

​Como funciona

​Tipos de entidade compatíveis

​Criando um índice de metadados

​Listando índices de metadados

​Excluindo um índice de metadados

​Considerações de desempenho

​Páginas relacionadas

Por que isso importa

Como funciona

Tipos de entidade compatíveis

Criando um índice de metadados

Listando índices de metadados

Excluindo um índice de metadados

Considerações de desempenho

Páginas relacionadas