Indexación y Actualización de Documentos con la API REST de Elasticsearch

Elasticsearch es un potente motor de búsqueda y análisis distribuido que se basa en una ingesta de datos bien estructurada. La gestión de estos datos implica operaciones fundamentales de Crear, Leer, Actualizar y Eliminar (CRUD), ejecutadas principalmente a través de su versátil API REST. Comprender cómo indexar correctamente nuevos documentos y actualizar eficientemente los existentes es crucial para mantener un almacén de datos preciso y en tiempo real.

Esta guía le mostrará los métodos HTTP esenciales y los puntos finales de la API utilizados para indexar nuevos registros y modificar documentos existentes dentro de su clúster de Elasticsearch. Nos centraremos en la sintaxis, las cargas útiles JSON requeridas y la interpretación de los códigos de respuesta para garantizar una gestión de datos fluida.

---

Prerrequisitos

Antes de continuar, asegúrese de tener:

• Un clúster de Elasticsearch activo en funcionamiento.
• Una herramienta de línea de comandos capaz de realizar solicitudes HTTP (como curl) o un cliente HTTP (como Postman).
• Conocimiento del nombre de su índice de destino.

---

1. Indexación de Documentos Nuevos

La indexación es el proceso de almacenar un documento JSON en un índice de Elasticsearch. Elasticsearch asigna automáticamente una ID única al documento a menos que se proporcione una explícitamente. El método principal para la indexación es el método HTTP PUT o POST.

1.1 Indexación con una ID Automática (POST)

Cuando utiliza POST al punto final del índice, Elasticsearch genera una ID de documento única para usted. Este suele ser el método preferido para la ingesta inicial de datos cuando las ID se gestionan internamente.

Punto Final: POST /{index_name}/_doc/

Ejemplo de Solicitud (usando curl):

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

Fragmento de Respuesta Exitosa:

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

El campo result que muestra created confirma que se agregó un nuevo documento.

1.2 Indexación con una ID Específica (PUT)

Si su sistema de origen proporciona un identificador único para el documento, debe utilizar el método PUT dirigido a una ID específica. Si un documento con esa ID ya existe, PUT sobrescribirá el documento completo.

Punto Final: PUT /{index_name}/_doc/{document_id}

Ejemplo de Solicitud: Indexando un documento con la ID 1001.

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

Fragmento de Respuesta Exitosa:

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

Consejo sobre Sobrescritura: Si ejecuta exactamente la misma solicitud PUT nuevamente con la misma ID, el result cambiará a updated y el número de _version se incrementará.

---

2. Actualización de Documentos Existentes

Actualizar documentos es distinto de sobrescribir. Cuando solo desea cambiar campos específicos dentro de un documento existente sin afectar los campos que no se modificaron, utiliza el punto final _update, típicamente con el método POST.

2.1 Actualizaciones Parciales usando _update

La API _update es crucial para las Actualizaciones Atómicas. Requiere un bloque doc dentro de la carga útil, que contiene solo los campos que desea modificar. Elasticsearch recupera el documento, fusiona los cambios y lo reindexa.

Punto Final: POST /{index_name}/_update/{document_id}

Escenario de Ejemplo: Queremos actualizar el precio del producto ID 1001 de $129.99 a $119.99 y marcarlo como agotado.

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

Fragmento de Respuesta Exitosa:

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

Observe que _version se ha incrementado de 1 a 2, lo que refleja la modificación.

2.2 Uso de Actualizaciones mediante Scripts (Scripted Updates)

Para actualizaciones más complejas, condicionales o matemáticas, Elasticsearch admite la secuencias de comandos Painless dentro de la API _update. Esto le permite realizar operaciones como incrementar contadores o establecer campos basándose en sus valores actuales.

Escenario de Ejemplo: Incrementar el recuento de existencias en 5 para el 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
    }
  }
}
'

Concepto Clave de Scripting: ctx._source se refiere a la fuente del documento actual.

Advertencia sobre Scripts: Si bien son potentes, los scripts complejos pueden afectar el rendimiento. Utilice actualizaciones de campo simples (doc) siempre que sea posible, ya que generalmente son más rápidas y seguras.

---

3. Indexación y Actualizaciones Masivas (Bulk)

Para operaciones de datos de alto volumen, enviar solicitudes individuales por cada documento es ineficiente. Elasticsearch proporciona la API _bulk para manejar múltiples operaciones de indexación, actualización o eliminación en una sola solicitud.

3.1 Estructura de una Solicitud Bulk

Las solicitudes Bulk utilizan un formato específico JSON delimitado por saltos de línea (NDJSON). Cada operación se define mediante una línea de metadatos (especificando la acción, el índice y la ID opcional), seguida inmediatamente por la fuente del documento (si es necesaria).

Tipos de Acción para Bulk: index, create, update, delete.

Ejemplo de Solicitud Bulk (Combinando Indexación y Actualización):

curl -X POST "localhost:9200/products/_bulk" -H 'Content-Type: application/x-ndjson' -d'

{"index": {"_id": "2001"}}
{"name": "USB-C Hub", "price": 45.00, "in_stock": true}
{"update": {"_id": "1001"}}
{"doc": {"price": 115.00}}
{"delete": {"_id": "3003"}}

'

En este ejemplo:

1. El documento 2001 es indexado.
2. El documento 1001 es actualizado parcialmente (el precio se reduce).
3. El documento 3003 es eliminado.

Respuesta Bulk: La respuesta detallará el éxito o el fracaso de cada operación individual dentro del lote, lo que le permitirá identificar qué documentos tuvieron éxito y cuáles fallaron.

---

Resumen de Comandos Clave de la API

Operación	Método HTTP	Patrón de Punto Final	Efecto
Indexar (ID Automática)	POST	/{index}/_doc/	Crea un nuevo documento con ID autogenerada.
Indexar/Sobrescribir	PUT	/{index}/_doc/{id}	Crea o reemplaza completamente el documento en la ID especificada.
Actualización Parcial	POST	/{index}/_update/{id}	Fusiona los cambios especificados en el bloque doc.
Operaciones Bulk	POST	/{index}/_bulk	Ejecuta múltiples operaciones en una sola solicitud.

Dominar estas interacciones fundamentales de la API REST proporciona la base para la gestión dinámica de datos dentro de cualquier aplicación de Elasticsearch.