> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Índices de metadata > Melhore a performance de consultas em campos de metadata criando índices customizados no MongoDB. ## Por que isso importa *** Toda entidade no Midaz suporta [metadata](/pt/reference/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.` 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: | Entidade | Coleção | Módulo | | :------------------ | :----------------- | :---------- | | `transaction` | Transactions | Transaction | | `operation` | Operations | Transaction | | `operation_route` | Operation Routes | Transaction | | `transaction_route` | Transaction Routes | Transaction | 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](/pt/reference/midaz/create-a-metadata-index): ```json POST /v1/settings/metadata-indexes/entities/{entity_name} theme={null} { "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:** ```json JSON theme={null} { "indexName": "metadata.tier_1", "entityName": "transaction", "metadataKey": "tier", "unique": false, "sparse": true } ``` ## Listando índices de metadata *** Use o endpoint [List Metadata Indexes](/pt/reference/midaz/list-metadata-indexes) para ver todos os índices de todos os tipos de entidade, incluindo estatísticas de uso: ```json GET /v1/settings/metadata-indexes theme={null} { "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](/pt/reference/midaz/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 *** * [Metadata](/pt/reference/metadata) — Como a metadata funciona em todas as entidades do Midaz. * [Create a Metadata Index](/pt/reference/midaz/create-a-metadata-index) — Referência de API. * [List Metadata Indexes](/pt/reference/midaz/list-metadata-indexes) — Referência de API. * [Delete a Metadata Index](/pt/reference/midaz/delete-a-metadata-index) — Referência de API.