La Guía Definitiva para Gestionar Índices de Elasticsearch mediante Comandos API

Gestionar índices de Elasticsearch a través de la API es un trabajo común, pero también es donde ocurren muchos errores costosos. Un mapeo incorrecto puede forzar un reindexado. Una eliminación con comodín puede eliminar más de lo que pretendías. Una configuración de réplicas que tenía sentido en desarrollo puede dejar la producción en amarillo después de un despliegue.

Un índice de Elasticsearch no es solo un cubo de documentos JSON. Tiene mapeos, configuraciones, alias, recuentos de fragmentos, recuentos de réplicas, analizadores y comportamiento del ciclo de vida. No necesitas memorizar cada API para gestionarlo bien, pero sí necesitas una rutina cuidadosa: crear índices intencionalmente, inspeccionar lo que Elasticsearch realmente creó, actualizar solo las configuraciones que se pueden cambiar de forma segura y eliminar con protecciones.

Los ejemplos a continuación utilizan solicitudes de estilo Kibana Dev Tools. Si prefieres curl, las mismas rutas y cuerpos JSON se aplican contra http://host:9200.

Qué contiene un índice

Un índice es un espacio de nombres lógico para documentos. Internamente, los fragmentos primarios contienen los datos, y los fragmentos réplica copian esos datos para redundancia y capacidad de búsqueda. El comportamiento exacto predeterminado de fragmentos y réplicas puede variar según la versión de Elasticsearch y el modo de implementación, así que no confíes en la memoria. Verifica la configuración en tu propio clúster.

Las tres piezas que inspeccionarás con más frecuencia son:

• settings, como number_of_shards, number_of_replicas, refresh_interval y la configuración de análisis.
• mappings, que definen tipos de campo como keyword, text, date, long, double, boolean, ip y campos anidados/de objeto.
• aliases, que permiten a las aplicaciones usar un nombre estable mientras intercambias el índice real subyacente.

Un buen flujo de trabajo de la API de índices comienza antes de que se indexe el primer documento. El mapeo dinámico es útil para la exploración, pero los índices de producción merecen mapeos explícitos para campos importantes. Si user_id se mapea accidentalmente como text, las agregaciones y los filtros exactos se vuelven complicados. Si una marca de tiempo se mapea como text, las consultas de rango de tiempo no se comportarán como consultas de fecha. Esos errores se pueden solucionar, pero generalmente creando un nuevo índice y reindexando.

Crear un índice simple

La solicitud de creación más pequeña es:

PUT /my_first_index

Elasticsearch devuelve un acuse de recibo si el índice se creó:

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

Eso está bien para un índice de prueba. Para datos reales, crea el índice con la configuración y los mapeos que esperas, en lugar de dejar que los primeros documentos definan la forma.

Crear un índice con mapeos y configuraciones

Aquí hay un índice products práctico. Soporta búsqueda de texto completo en nombres y descripciones, filtrado exacto por IDs y categorías, ordenación por fecha, filtros de rango numérico y comprobaciones simples de disponibilidad.

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" }
    }
  }
}

Algunas elecciones aquí son deliberadas. product_id, sku y category son keyword porque normalmente filtras, agregas o unes el comportamiento de la aplicación en torno a valores exactos. name es text para búsqueda, con un subcampo name.raw de tipo keyword para ordenación y coincidencia exacta. price usa scaled_float para que los precios puedan almacenarse como valores escalados similares a céntimos en lugar de aproximaciones de punto flotante binarias. dynamic: strict rechaza campos desconocidos, lo cual es útil cuando los datos de un productor defectuoso deben fallar de forma ruidosa.

No copies el número de fragmentos a ciegas. Tres fragmentos primarios pueden ser demasiados para un índice pequeño y demasiado pocos para uno grande. El número de fragmentos es difícil de cambiar después de la creación sin una migración de reducción, división o reindexación, así que ajústalo según el volumen de datos esperado, la retención y el número de nodos.

Inspeccionar un índice después de la creación

Siempre verifica lo que Elasticsearch aceptó:

GET /products-v1

Eso devuelve configuraciones, mapeos y alias. Para comprobaciones más específicas, usa endpoints más reducidos:

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

Para una vista compacta desde la línea de comandos de muchos índices:

GET /_cat/indices/products-*?v

Las columnas útiles incluyen salud, estado, recuento de fragmentos primarios, recuento de réplicas, recuento de documentos, recuento de documentos eliminados y tamaño de almacenamiento. Las APIs _cat están pensadas para humanos. Usa APIs JSON para scripts.

Si estás comprobando si un campo está mapeado correctamente, usa:

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

Eso es más rápido de leer que desplazarse por un mapeo grande.

Actualizar la configuración del índice de forma segura

Algunas configuraciones son dinámicas. El recuento de réplicas es el más común:

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

Esto puede volver un clúster verde amarillo si no tienes suficientes nodos de datos adecuados. Por ejemplo, un primario más dos réplicas necesita tres lugares separados para colocar las copias. Las reglas de conciencia de asignación pueden hacer que el requisito sea más estricto.

refresh_interval es otra configuración que puedes cambiar durante cargas masivas:

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

Un intervalo de actualización más largo puede reducir la sobrecarga de indexación, pero los documentos recién indexados se vuelven visibles para la búsqueda menos rápidamente. Para una carga masiva, los equipos a menudo aumentan o deshabilitan temporalmente las actualizaciones, cargan datos, luego restauran el intervalo normal y actualizan una vez:

POST /products-v1/_refresh

Algunas configuraciones son estáticas. number_of_shards no se puede cambiar en un índice existente abierto. Si descubres que el recuento de fragmentos primarios es incorrecto, planifica un nuevo índice y una migración.

Cambiar mapeos sin engañarte a ti mismo

Puedes agregar nuevos campos a un mapeo:

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

Generalmente no puedes cambiar el tipo de un campo existente en el lugar. Si price ya es text, esto no convertirá los valores antiguos en un campo numérico útil. Crea un nuevo índice con el mapeo correcto y reindexa:

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

Para migraciones de producción, usa alias para que la aplicación no necesite conocer la versión física del índice.

Usar alias para un acceso de aplicación más seguro

Apunta un alias a la primera versión:

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

Tu aplicación lee desde products. Más tarde, crea products-v2, reindexa los datos, pruébalos, luego intercambia el alias de forma atómica:

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

Para sistemas con mucha escritura, usa un alias de escritura y sé explícito con is_write_index:

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

Los alias son una de las formas más simples de evitar codificar versiones de índice en los servicios.

Listar y buscar nombres de índice con cuidado

Para inspeccionar múltiples índices:

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

Ten cuidado con los comodines amplios en clústeres grandes. GET /* o GET /_all pueden producir una respuesta enorme y pueden incluir índices del sistema u ocultos dependiendo de la versión, la configuración y las opciones de solicitud. Prefiere un patrón estrecho como logs-prod-* o products-*.

Para comprobar si un índice existe desde un script, usa HEAD:

HEAD /products-v1

Un 200 significa que existe. Un 404 significa que no.

Eliminar índices con protecciones

Eliminar es simple:

DELETE /products-v1

El riesgo operativo no es la sintaxis. El riesgo es eliminar el índice incorrecto o eliminar antes de que se complete una instantánea.

Antes de eliminar, lista exactamente lo que coincide con el patrón:

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

Si la salida es correcta y los datos son recuperables o ya no son necesarios, elimina el mismo patrón:

DELETE /products-old-*

Muchos clústeres restringen las operaciones destructivas con comodín mediante action.destructive_requires_name. Esa es una buena configuración de seguridad porque bloquea eliminaciones amplias como DELETE /* a menos que se requieran nombres explícitos. Incluso con esa protección, trata las operaciones de eliminación como cambios de producción: confirma el patrón del índice, confirma las instantáneas y confirma que el llamante tiene los permisos correctos.

Preferir políticas de ciclo de vida para datos de series temporales

Las eliminaciones manuales son aceptables para limpiezas puntuales. Para registros, métricas, trazas y otros datos de series temporales, usa Index Lifecycle Management o flujos de datos cuando sea apropiado. Una política de ciclo de vida puede rotar un índice cuando alcanza un objetivo de antigüedad o tamaño, mover datos más antiguos a un nivel diferente y eliminarlos después de que expire la retención.

Eso importa porque la limpieza manual tiende a fallar en el peor momento. Alguien se olvida, el disco se llena, los marcadores de nivel de inundación hacen que los índices sean de solo lectura, y luego el equipo está limpiando bajo presión. Las políticas de ciclo de vida convierten la retención en configuración en lugar de un recordatorio de calendario.

Una rutina diaria simple

Para un clúster de producción, una rutina práctica de gestión de índices se ve así:

Verificar la salud:

GET /_cluster/health

Listar índices por patrón:

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

Inspeccionar configuraciones sospechosas:

GET /logs-prod-2026.05.24/_settings

Verificar mapeos antes de agregar nuevos campos desde un lanzamiento de aplicación:

GET /logs-prod-2026.05.24/_mapping

Confirmar alias antes y después de una migración:

GET /_cat/aliases/products*?v

Este no es un trabajo glamoroso, pero detecta muchos problemas temprano: recuentos de réplicas incorrectos, campos dinámicos accidentales, alias obsoletos e índices antiguos que deberían haber sido eliminados.

Errores comunes a evitar

No dejes que los valores predeterminados de desarrollo se conviertan en la arquitectura de producción. Un clúster de un solo nodo, cero réplicas y mapeos dinámicos pueden estar bien para una demostración. No son un plan de recuperación.

No cambies los mapeos en tu cabeza y asumas que Elasticsearch está de acuerdo. Inspecciona el mapeo real.

No uses eliminaciones con comodín sin listar primero los índices coincidentes.

No establezcas recuentos de réplicas altos sin suficientes nodos de datos y zonas para colocarlos.

No omitas los alias para los índices de los que dependen las aplicaciones. La primera migración será mucho más fácil si la aplicación ya habla con un alias.

Una buena gestión de índices es principalmente repetición disciplinada. Crear con intención, inspeccionar lo que existe, migrar con alias, automatizar la retención y hacer que las acciones destructivas sean aburridamente explícitas.

Las plantillas importan más que las creaciones únicas

Si creas el mismo tipo de índice repetidamente, no confíes en llamadas manuales PUT /nombre-del-indice. Usa una plantilla de índice o plantillas componibles para que los nuevos índices reciban automáticamente los mapeos, configuraciones, alias y políticas de ciclo de vida correctos.

Una plataforma de registros es el ejemplo clásico. Si logs-web-2026.05.24 tiene un mapeo @timestamp correcto, pero el índice de mañana se crea dinámicamente por el primer documento, un evento mal formado puede mapear un campo incorrectamente. El error puede no aparecer hasta que los paneles fallen o las agregaciones desaparezcan. Las plantillas evitan esa desviación.

Una plantilla simple podría definir un patrón, configuraciones y mapeos 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" }
      }
    }
  }
}

Las plantillas también son más fáciles de revisar en código. Ponlas en control de versiones, impleméntalas a través del mismo camino que los cambios de aplicación y pruébalas antes de que la rotación cree el siguiente índice subyacente.

Reindexar sin sorprender a la aplicación

La migración de índice más limpia suele ser: crear un nuevo índice versionado, reindexar datos, comparar recuentos y consultas de muestra, luego intercambiar un alias. No apuntes la aplicación directamente a products-v1 a menos que te gusten los cambios de configuración de emergencia.

Una migración cuidadosa se ve así:

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

Luego reindexa:

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

Usar wait_for_completion=false devuelve un ID de tarea para que puedas monitorear una reindexación larga. Después de que termine, compara los recuentos de documentos y ejecuta búsquedas representativas. Solo entonces intercambia los alias.

Para índices con mucha escritura, piensa en escrituras duales, ventanas de pausa o reproducción desde una fuente de verdad. Los comandos API son fáciles; el plan de consistencia es el trabajo real.

Seguridad y permisos

Las APIs de índices no deberían estar disponibles para todos los usuarios de la aplicación. Un servicio de búsqueda puede necesitar privilegios de lectura en un alias. Un ingestor de datos puede necesitar privilegios de creación, indexación y escritura en un alias de escritura. Muy pocas identidades deberían tener privilegios amplios de eliminación o gestión.

Esto importa porque las APIs de índices son poderosas. Una credencial de aplicación comprometida con privilegios de manage puede cambiar la configuración de réplicas, cerrar índices o eliminar datos. Mantén los privilegios destructivos separados y haz que la eliminación en producción requiera un flujo de trabajo del operador en lugar de una ruta de aplicación.

Las convenciones de nomenclatura reducen los errores

Usa nombres que codifiquen el propósito y el ciclo de vida: products-v3, logs-web-2026.05.24, metrics-api-000123 o nombres de flujos de datos que coincidan con la fuente de datos. Evita nombres vagos como newindex, test2 o prod-final. Durante la limpieza, los nombres vagos dificultan saber qué es seguro eliminar.

Para índices de series temporales, usa formatos de fecha consistentes y evita mezclar suposiciones de hora local y UTC. Para índices de negocio versionados, mantén el alias estable y deja que la versión física del índice cambie detrás de él. Una convención de nomenclatura aburrida es una característica de seguridad operativa.