O Guia Definitivo para Gerenciar Índices do Elasticsearch via Comandos de API

Gerenciar índices do Elasticsearch através da API é um trabalho comum, mas também é onde muitos erros caros acontecem. Um mapeamento ruim pode forçar uma reindexação. Uma exclusão com caractere curinga pode remover mais do que você pretendia. Uma configuração de réplica que fazia sentido no desenvolvimento pode deixar a produção amarela após uma implantação.

Um índice do Elasticsearch não é apenas um balde de documentos JSON. Ele possui mapeamentos, configurações, aliases, contagens de shards, contagens de réplicas, analisadores e comportamento de ciclo de vida. Você não precisa memorizar todas as APIs para gerenciá-lo bem, mas precisa de uma rotina cuidadosa: criar índices intencionalmente, inspecionar o que o Elasticsearch realmente criou, atualizar apenas as configurações que podem ser alteradas com segurança e excluir com proteções.

Os exemplos abaixo usam requisições no estilo Kibana Dev Tools. Se preferir curl, os mesmos caminhos e corpos JSON se aplicam contra http://host:9200.

O que um índice contém

Um índice é um namespace lógico para documentos. Nos bastidores, os shards primários armazenam os dados, e os shards de réplica copiam esses dados para redundância e capacidade de pesquisa. O comportamento exato padrão de shard e réplica pode variar de acordo com a versão do Elasticsearch e o modo de implantação, portanto, não confie na memória. Verifique as configurações no seu próprio cluster.

As três partes que você inspecionará com mais frequência são:

• settings, como number_of_shards, number_of_replicas, refresh_interval e configuração de análise.
• mappings, que definem tipos de campo como keyword, text, date, long, double, boolean, ip e campos aninhados/de objeto.
• aliases, que permitem que os aplicativos usem um nome estável enquanto você troca o índice real subjacente.

Um bom fluxo de trabalho de API de índice começa antes do primeiro documento ser indexado. O mapeamento dinâmico é útil para exploração, mas índices de produção merecem mapeamentos explícitos para campos importantes. Se user_id for acidentalmente mapeado como text, agregações e filtros exatos se tornam complicados. Se um timestamp for mapeado como text, as consultas de intervalo de tempo não se comportarão como consultas de data. Esses erros são corrigíveis, mas geralmente criando um novo índice e reindexando.

Criar um índice simples

A requisição de criação mais simples é:

PUT /my_first_index

O Elasticsearch retorna um reconhecimento se o índice foi criado:

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "my_first_index"
}

Isso é bom para um índice de teste. Para dados reais, crie o índice com as configurações e mapeamentos que você espera, em vez de deixar os primeiros documentos definirem a forma.

Criar um índice com mapeamentos e configurações

Aqui está um índice products prático. Ele suporta pesquisa de texto completo em nomes e descrições, filtragem exata em IDs e categorias, ordenação por data, filtros de intervalo numérico e verificações simples de disponibilidade.

PUT /products-v1
{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1,
    "refresh_interval": "5s"
  },
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "product_id": { "type": "keyword" },
      "sku": { "type": "keyword" },
      "name": {
        "type": "text",
        "fields": {
          "raw": { "type": "keyword", "ignore_above": 256 }
        }
      },
      "description": { "type": "text" },
      "category": { "type": "keyword" },
      "price": { "type": "scaled_float", "scaling_factor": 100 },
      "stock": { "type": "integer" },
      "available": { "type": "boolean" },
      "created_at": { "type": "date" },
      "updated_at": { "type": "date" }
    }
  }
}

Algumas escolhas aqui são deliberadas. product_id, sku e category são keyword porque você normalmente filtra, agrega ou une o comportamento do aplicativo em torno de valores exatos. name é text para pesquisa, com um subcampo name.raw keyword para ordenação e correspondência exata. price usa scaled_float para que os preços possam ser armazenados como valores escalados em centavos, em vez de aproximações de ponto flutuante binário. dynamic: strict rejeita campos desconhecidos, o que é útil quando dados de produtor ruins devem falhar ruidosamente.

Não copie a contagem de shards cegamente. Três shards primários podem ser muitos para um índice pequeno e poucos para um grande. A contagem de shards é difícil de alterar após a criação sem uma migração do tipo shrink, split ou reindex, portanto, dimensione-a com base no volume de dados esperado, retenção e número de nós.

Inspecionar um índice após a criação

Sempre verifique o que o Elasticsearch aceitou:

GET /products-v1

Isso retorna configurações, mapeamentos e aliases. Para verificações focadas, use endpoints mais restritos:

GET /products-v1/_mapping
GET /products-v1/_settings
GET /products-v1/_alias

Para uma visão compacta de linha de comando de muitos índices:

GET /_cat/indices/products-*?v

Colunas úteis incluem health, status, contagem de shards primários, contagem de réplicas, contagem de documentos, contagem de documentos excluídos e tamanho do armazenamento. As APIs _cat são feitas para humanos. Use APIs JSON para scripts.

Se você estiver verificando se um campo está mapeado corretamente, use:

GET /products-v1/_mapping/field/price
GET /products-v1/_mapping/field/name.raw

Isso é mais rápido de ler do que percorrer um mapeamento grande.

Atualizar configurações do índice com segurança

Algumas configurações são dinâmicas. A contagem de réplicas é a mais comum:

PUT /products-v1/_settings
{
  "index": {
    "number_of_replicas": 2
  }
}

Isso pode tornar um cluster verde amarelo se você não tiver nós de dados adequados suficientes. Por exemplo, um primário mais duas réplicas precisa de três lugares separados para colocar cópias. As regras de consciência de alocação podem tornar o requisito mais rigoroso.

refresh_interval é outra configuração que você pode alterar durante cargas em massa:

PUT /products-v1/_settings
{
  "index": {
    "refresh_interval": "30s"
  }
}

Um intervalo de atualização mais longo pode reduzir a sobrecarga de indexação, mas os documentos recém-indexados tornam-se visíveis para pesquisa menos rapidamente. Para um preenchimento em massa, as equipes geralmente aumentam ou desabilitam temporariamente as atualizações, carregam os dados e, em seguida, restauram o intervalo normal e atualizam uma vez:

POST /products-v1/_refresh

Algumas configurações são estáticas. number_of_shards não pode ser alterado em um índice existente aberto. Se você descobrir que a contagem de shards primários está errada, planeje um novo índice e migração.

Alterar mapeamentos sem enganar a si mesmo

Você pode adicionar novos campos a um mapeamento:

PUT /products-v1/_mapping
{
  "properties": {
    "brand": { "type": "keyword" }
  }
}

Geralmente, você não pode alterar o tipo de um campo existente no local. Se price já é text, isso não transformará valores antigos em um campo numérico útil. Crie um novo índice com o mapeamento correto e reindexe:

POST /_reindex
{
  "source": { "index": "products-v1" },
  "dest": { "index": "products-v2" }
}

Para migrações de produção, use aliases para que o aplicativo não precise saber a versão física do índice.

Usar aliases para acesso mais seguro do aplicativo

Aponte um alias para a primeira versão:

POST /_aliases
{
  "actions": [
    { "add": { "index": "products-v1", "alias": "products" } }
  ]
}

Seu aplicativo lê de products. Mais tarde, crie products-v2, reindexe os dados, teste e, em seguida, troque o alias atomicamente:

POST /_aliases
{
  "actions": [
    { "remove": { "index": "products-v1", "alias": "products" } },
    { "add": { "index": "products-v2", "alias": "products" } }
  ]
}

Para sistemas com muita gravação, use um alias de gravação e seja explícito sobre is_write_index:

POST /_aliases
{
  "actions": [
    { "add": { "index": "products-v2", "alias": "products-write", "is_write_index": true } }
  ]
}

Aliases são uma das maneiras mais simples de evitar codificar versões de índice nos serviços.

Listar e pesquisar nomes de índice com cuidado

Para inspecionar vários índices:

GET /products-v1,products-v2/_settings
GET /products-*/_mapping
GET /_cat/indices/products-*?v&s=index

Tenha cuidado com caracteres curinga amplos em clusters grandes. GET /* ou GET /_all pode produzir uma resposta enorme e pode incluir índices de sistema ou ocultos, dependendo da versão, configurações e opções de requisição. Prefira um padrão restrito como logs-prod-* ou products-*.

Para verificar se um índice existe a partir de um script, use HEAD:

HEAD /products-v1

Um 200 significa que existe. Um 404 significa que não existe.

Excluir índices com proteções

Excluir é simples:

DELETE /products-v1

O risco operacional não é a sintaxe. O risco é excluir o índice errado ou excluir antes que um snapshot seja concluído.

Antes de excluir, liste exatamente o que o padrão corresponde:

GET /_cat/indices/products-old-*?v&s=index

Se a saída estiver correta e os dados forem recuperáveis ou não forem mais necessários, exclua o mesmo padrão:

DELETE /products-old-*

Muitos clusters restringem operações destrutivas com caractere curinga com action.destructive_requires_name. Essa é uma boa configuração de segurança porque bloqueia exclusões amplas como DELETE /* a menos que nomes explícitos sejam exigidos. Mesmo com essa proteção, trate as operações de exclusão como alterações de produção: confirme o padrão do índice, confirme os snapshots e confirme que o chamador tem as permissões corretas.

Preferir políticas de ciclo de vida para dados de série temporal

Exclusões manuais são aceitáveis para limpeza pontual. Para logs, métricas, traces e outros dados de série temporal, use o Gerenciamento de Ciclo de Vida de Índices ou fluxos de dados, quando apropriado. Uma política de ciclo de vida pode alternar um índice quando ele atinge uma meta de idade ou tamanho, mover dados mais antigos para uma camada diferente e excluí-los após a expiração da retenção.

Isso é importante porque a limpeza manual tende a falhar no pior momento. Alguém esquece, o disco enche, as marcas d'água de nível de inundação tornam os índices somente leitura e, então, a equipe está limpando sob pressão. As políticas de ciclo de vida transformam a retenção em configuração, em vez de um lembrete de calendário.

Uma rotina diária simples

Para um cluster de produção, uma rotina prática de gerenciamento de índices se parece com isto:

Verificar a saúde:

GET /_cluster/health

Listar índices por padrão:

GET /_cat/indices/logs-*?v&s=store.size:desc

Inspecionar configurações suspeitas:

GET /logs-prod-2026.05.24/_settings

Verificar mapeamentos antes de adicionar novos campos de um lançamento de aplicativo:

GET /logs-prod-2026.05.24/_mapping

Confirmar aliases antes e depois de uma migração:

GET /_cat/aliases/products*?v

Este não é um trabalho glamoroso, mas detecta muitos problemas precocemente: contagens de réplicas erradas, campos dinâmicos acidentais, aliases obsoletos e índices antigos que já deveriam ter sido removidos.

Erros comuns a evitar

Não deixe que os padrões de desenvolvimento se tornem a arquitetura de produção. Um cluster de nó único, zero réplicas e mapeamentos dinâmicos podem ser bons para uma demonstração. Eles não são um plano de recuperação.

Não altere mapeamentos mentalmente e presuma que o Elasticsearch concorda. Inspecione o mapeamento real.

Não use exclusões com caractere curinga sem listar os índices correspondentes primeiro.

Não defina contagens altas de réplicas sem nós de dados e zonas suficientes para colocá-las.

Não pule aliases para índices dos quais os aplicativos dependem. A primeira migração será muito mais fácil se o aplicativo já falar com um alias.

Um bom gerenciamento de índices é principalmente repetição disciplinada. Crie com intenção, inspecione o que existe, migre com aliases, automatize a retenção e torne as ações destrutivas enfadonhamente explícitas.

Modelos são mais importantes do que criações únicas

Se você criar o mesmo tipo de índice repetidamente, não confie em chamadas manuais PUT /nome-do-indice. Use um modelo de índice ou modelos combináveis para que novos índices recebam automaticamente os mapeamentos, configurações, aliases e política de ciclo de vida corretos.

Uma plataforma de log é o exemplo clássico. Se logs-web-2026.05.24 tem um mapeamento @timestamp correto, mas o índice de amanhã é criado dinamicamente pelo primeiro documento, um evento malformado pode mapear um campo incorretamente. O erro pode não aparecer até que os dashboards falhem ou as agregações desapareçam. Os modelos evitam esse desvio.

Um modelo simples pode definir um padrão, configurações e mapeamentos para índices futuros:

PUT /_index_template/logs_web_template
{
  "index_patterns": ["logs-web-*"],
  "template": {
    "settings": {
      "number_of_shards": 3,
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "@timestamp": { "type": "date" },
        "service": { "type": "keyword" },
        "level": { "type": "keyword" },
        "message": { "type": "text" },
        "trace_id": { "type": "keyword" }
      }
    }
  }
}

Os modelos também são mais fáceis de revisar no código. Coloque-os no controle de versão, implante-os pelo mesmo caminho que as alterações do aplicativo e teste-os antes que a alternância crie o próximo índice subjacente.

Reindexar sem surpreender o aplicativo

A migração de índice mais limpa geralmente é: criar um novo índice versionado, reindexar os dados, comparar contagens e consultas de amostra e, em seguida, trocar um alias. Não aponte o aplicativo diretamente para products-v1 a menos que você goste de alterações de configuração de emergência.

Uma migração cuidadosa se parece com isto:

PUT /products-v2
{
  "mappings": {
    "properties": {
      "product_id": { "type": "keyword" },
      "name": { "type": "text" },
      "price": { "type": "scaled_float", "scaling_factor": 100 }
    }
  }
}

Em seguida, reindexe:

POST /_reindex?wait_for_completion=false
{
  "source": { "index": "products-v1" },
  "dest": { "index": "products-v2" }
}

Usar wait_for_completion=false retorna um ID de tarefa para que você possa monitorar uma reindexação longa. Depois que terminar, compare as contagens de documentos e execute pesquisas representativas. Só então troque os aliases.

Para índices com muita gravação, pense em gravações duplas, janelas de pausa ou reprodução a partir de uma fonte da verdade. Os comandos da API são fáceis; o plano de consistência é o trabalho real.

Segurança e permissões

As APIs de índice não devem estar disponíveis para todos os usuários do aplicativo. Um serviço de pesquisa pode precisar de privilégios de leitura em um alias. Um ingestor de dados pode precisar de privilégios de criação, indexação e gravação em um alias de gravação. Muito poucas identidades devem ter privilégios amplos de exclusão ou gerenciamento.

Isso é importante porque as APIs de índice são poderosas. Uma credencial de aplicativo comprometida com privilégios de manage pode alterar configurações de réplica, fechar índices ou excluir dados. Mantenha os privilégios destrutivos separados e torne a exclusão de produção dependente de um fluxo de trabalho do operador, em vez de um caminho do aplicativo.

Convenções de nomenclatura reduzem erros

Use nomes que codificam propósito e ciclo de vida: products-v3, logs-web-2026.05.24, metrics-api-000123 ou nomes de fluxo de dados que correspondam à fonte de dados. Evite nomes vagos como newindex, test2 ou prod-final. Durante a limpeza, nomes vagos dificultam saber o que é seguro excluir.

Para índices de série temporal, use formatos de data consistentes e evite misturar suposições de hora local e UTC. Para índices de negócios versionados, mantenha o alias estável e deixe a versão física do índice mudar por trás dele. Uma convenção de nomenclatura monótona é um recurso de segurança operacional.