Indexação e Atualização de Documentos com a API REST do Elasticsearch

O Elasticsearch é um motor de busca e análise distribuído e poderoso que depende de uma ingestão de dados bem estruturada. O gerenciamento desses dados envolve operações fundamentais de Criar, Ler, Atualizar e Excluir (CRUD), executadas principalmente através de sua versátil API REST. Compreender como indexar corretamente novos documentos e atualizar eficientemente os existentes é crucial para manter um armazenamento de dados preciso e em tempo real.

Este guia irá guiá-lo pelos métodos HTTP essenciais e endpoints da API usados para indexar novos registros e modificar documentos existentes em seu cluster Elasticsearch. Focaremos na sintaxe, nas cargas úteis (payloads) JSON necessárias e na interpretação dos códigos de resposta para garantir um gerenciamento de dados contínuo.

---

Pré-requisitos

Antes de prosseguir, certifique-se de ter:

• Um cluster Elasticsearch ativo em execução.
• Uma ferramenta de linha de comando capaz de fazer solicitações HTTP (como curl) ou um cliente HTTP (como Postman).
• Conhecimento do nome do seu índice de destino.

---

1. Indexação de Novos Documentos

A indexação é o processo de armazenar um documento JSON em um índice do Elasticsearch. O Elasticsearch atribui automaticamente um ID exclusivo ao documento, a menos que um seja fornecido explicitamente. O método principal para indexação é o método HTTP PUT ou POST.

1.1 Indexação com um ID Automático (POST)

Quando você usa POST para o endpoint do índice, o Elasticsearch gera um ID de documento exclusivo para você. Este é frequentemente o método preferido para ingestão inicial de dados quando os IDs são gerenciados internamente.

Endpoint: POST /{index_name}/_doc/

Exemplo de Requisição (usando curl):

curl -X POST "localhost:9200/products/_doc/" -H 'Content-Type: application/json' -d'
{
  "name": "Mouse Sem Fio X1",
  "price": 25.99,
  "in_stock": true
}
'

Fragmento de Resposta de Sucesso:

{
  "_index": "products",
  "_id": "c7BwJ3gBpV4wT-eH_aY1",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}

O campo result mostrando created confirma que um novo documento foi adicionado.

1.2 Indexação com um ID Específico (PUT)

Se o seu sistema de origem fornecer um identificador exclusivo para o documento, você deve usar o método PUT direcionado a um ID específico. Se um documento com esse ID já existir, PUT irá sobrescrever o documento inteiro.

Endpoint: PUT /{index_name}/_doc/{document_id}

Exemplo de Requisição: Indexando um documento com ID 1001.

curl -X PUT "localhost:9200/products/_doc/1001" -H 'Content-Type: application/json' -d'
{
  "name": "Teclado Mecânico K90",
  "price": 129.99,
  "in_stock": true
}
'

Fragmento de Resposta de Sucesso:

{
  "_index": "products",
  "_id": "1001",
  "_version": 1,
  "result": "created",
  "_shards": { ... }
}

Dica sobre Sobrescrita: Se você executar exatamente a mesma requisição PUT novamente com o mesmo ID, o result mudará para updated, e o número _version será incrementado.

---

2. Atualizando Documentos Existentes

A atualização de documentos é distinta da sobrescrita. Quando você deseja alterar apenas campos específicos dentro de um documento existente sem afetar os campos inalterados, você usa o endpoint _update, geralmente com o método POST.

2.1 Atualizações Parciais usando _update

A API _update é crucial para Atualizações Atômicas. Ela requer um bloco doc dentro do payload, que contém apenas os campos que você deseja modificar. O Elasticsearch recupera o documento, mescla as alterações e o reindexa.

Endpoint: POST /{index_name}/_update/{document_id}

Cenário de Exemplo: Queremos atualizar o preço do produto ID 1001 de $129.99 para $119.99 e marcá-lo como sem estoque.

curl -X POST "localhost:9200/products/_update/1001" -H 'Content-Type: application/json' -d'
{
  "doc": {
    "price": 119.99,
    "in_stock": false
  }
}
'

Fragmento de Resposta de Sucesso:

{
  "_index": "products",
  "_id": "1001",
  "_version": 2, 
  "result": "updated",
  "_shards": { ... }
}

Note que _version incrementou de 1 para 2, refletindo a modificação.

2.2 Usando Atualizações por Script

Para atualizações condicionais, matemáticas ou mais complexas, o Elasticsearch suporta a scripting Painless dentro da API _update. Isso permite que você execute operações como incrementar contadores ou definir campos com base em seus valores atuais.

Cenário de Exemplo: Incrementar a contagem de estoque em 5 para o documento ID 1001.

curl -X POST "localhost:9200/products/_update/1001" -H 'Content-Type: application/json' -d'
{
  "script": {
    "source": "ctx._source.stock += params.count",
    "params": {
      "count": 5
    }
  }
}
'

Conceito Chave de Script: ctx._source refere-se à fonte do documento atual.

Aviso sobre Scripts: Embora poderosos, scripts complexos podem afetar o desempenho. Use atualizações de campo simples (doc) sempre que possível, pois elas são geralmente mais rápidas e seguras.

---

3. Indexação e Atualizações em Massa (Bulk)

Para operações de dados de alto volume, enviar requisições individuais para cada documento é ineficiente. O Elasticsearch fornece a API _bulk para lidar com múltiplas operações de indexação, atualização ou exclusão em uma única requisição.

3.1 Estrutura de uma Requisição Bulk

Requisições Bulk usam um formato JSON específico, delimitado por nova linha (NDJSON). Cada operação é definida por uma linha de metadados (especificando a ação, índice e ID opcional) seguida imediatamente pela fonte do documento (se necessário).

Tipos de Ação para Bulk: index, create, update, delete.

Exemplo de Requisição Bulk (Misturando Indexação e Atualização):

curl -X POST "localhost:9200/products/_bulk" -H 'Content-Type: application/x-ndjson' -d'\n{"index": {"_id": "2001"}}\n{"name": "Hub USB-C", "price": 45.00, "in_stock": true}\n{"update": {"_id": "1001"}}\n{"doc": {"price": 115.00}}\n{"delete": {"_id": "3003"}}\n\n'

Neste exemplo:

1. O documento 2001 é indexado.
2. O documento 1001 é atualizado parcialmente (o preço é reduzido).
3. O documento 3003 é excluído.

Resposta Bulk: A resposta detalhará o sucesso ou falha de cada operação individual dentro do lote, permitindo que você identifique quais documentos tiveram sucesso e quais falharam.

---

Resumo dos Comandos Principais da API

Operação	Método HTTP	Padrão do Endpoint	Efeito
Indexar (ID Automático)	POST	/{index}/_doc/	Cria novo documento com ID gerado automaticamente.
Indexar/Sobrescrever	PUT	/{index}/_doc/{id}	Cria ou substitui completamente o documento no ID especificado.
Atualização Parcial	POST	/{index}/_update/{id}	Mescla as alterações especificadas no bloco doc.
Operações Bulk	POST	/{index}/_bulk	Executa múltiplas operações em uma única requisição.

Dominar essas interações fundamentais da API REST fornece a espinha dorsal para o gerenciamento dinâmico de dados em qualquer aplicação Elasticsearch.