Cómo Usar las APIs de Elasticsearch

En resumen

Las API de Elasticsearch potencian la búsqueda y el análisis a escala. Indexas documentos como JSON, consultas con un potente DSL y agregas resultados para análisis. La autenticación utiliza claves API o autenticación básica. Para las pruebas, usa Apidog para validar las asignaciones de índices, probar las consultas de búsqueda y depurar las agregaciones antes de desplegar en clústeres de producción.

Introducción

Elasticsearch es un motor de búsqueda y análisis distribuido. Maneja texto estructurado, registros, métricas y más. Las empresas lo utilizan para búsqueda de texto completo en aplicaciones, análisis de registros para depuración y paneles de control de análisis en tiempo real.

Elasticsearch es el corazón de la pila ELK (Elasticsearch, Logstash, Kibana). Pero puedes usarlo directamente a través de API sin Logstash.

💡

Si estás desarrollando funciones de búsqueda o análisis de registros, Apidog te ayuda a probar consultas, validar asignaciones y depurar agregaciones. Puedes guardar plantillas de búsqueda y compartirlas con tu equipo.

button

Prueba las API de Elasticsearch con Apidog - gratis

Al final de esta guía, podrás:

Indexar y gestionar documentos
Escribir consultas de búsqueda con el DSL de Elasticsearch
Usar agregaciones para análisis
Configurar asignaciones y analizadores
Monitorizar la salud del clúster

Primeros pasos

Ejecutar Elasticsearch localmente

# Docker
docker run -p 9200:9200 \
  -e "discovery.type=single-node" \
  elasticsearch:8.11.0

# O descargar desde elastic.co

Verificar instalación

curl -X GET "http://localhost:9200"

Respuesta:

{
  "name": "elasticsearch-1",
  "cluster_name": "elasticsearch",
  "cluster_uuid": "abc123",
  "version": {
    "number": "8.11.0",
    "build_flavor": "default"
  },
  "tagline": "You know, for search"
}

Autenticación

Elasticsearch 8.x requiere autenticación por defecto:

curl -X GET "http://localhost:9200/_cluster/health" \
  -u elastic:your_password

O usar claves API (creadas en Kibana o vía API).

Índices y documentos

Crear un índice

curl -X PUT "http://localhost:9200/products" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "name": { "type": "text" },
        "price": { "type": "float" },
        "category": { "type": "keyword" },
        "in_stock": { "type": "boolean" },
        "created_at": { "type": "date" }
      }
    }
  }'

Indexar un documento

curl -X POST "http://localhost:9200/products/_doc" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Headphones",
    "price": 79.99,
    "category": "electronics",
    "in_stock": true,
    "created_at": "2026-03-24T10:00:00Z"
  }'

Respuesta:

{
  "_index": "products",
  "_id": "abc123",
  "_version": 1,
  "result": "created",
  "_seq_no": 0,
  "_primary_term": 1
}

Obtener un documento

curl -X GET "http://localhost:9200/products/_doc/abc123" \
  -u elastic:your_password

Actualizar un documento

curl -X PUT "http://localhost:9200/products/_doc/abc123" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Headphones Pro",
    "price": 99.99,
    "category": "electronics",
    "in_stock": true,
    "created_at": "2026-03-24T10:00:00Z"
  }'

Eliminar un documento

curl -X DELETE "http://localhost:9200/products/_doc/abc123" \
  -u elastic:your_password

Operaciones masivas

Indexar múltiples documentos de manera eficiente:

curl -X POST "http://localhost:9200/products/_bulk" \
  -u elastic:your_password \
  -H "Content-Type: application/x-ndjson" \
  -d '{"index":{"_id":"1"}}
{"name":"Product A","price":10.99,"category":"books","in_stock":true}
{"index":{"_id":"2"}}
{"name":"Product B","price":20.99,"category":"electronics","in_stock":false}
'

Consultas de búsqueda

Búsqueda básica

curl -X GET "http://localhost:9200/products/_search" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "name": "headphones"
      }
    }
  }'

Consultas booleanas

Combinar múltiples condiciones:

{
  "query": {
    "bool": {
      "must": [
        { "match": { "name": "headphones" } }
      ],
      "filter": [
        { "term": { "category": "electronics" } },
        { "range": { "price": { "lte": 100 } } },
        { "term": { "in_stock": true } }
      ]
    }
  }
}

Búsqueda de texto completo con puntuación

{
  "query": {
    "multi_match": {
      "query": "wireless audio headphones",
      "fields": ["name^2", "description"],
      "type": "best_fields",
      "fuzziness": "AUTO"
    }
  }
}

Los nombres de campo con ^2 obtienen el doble de peso en la puntuación.

Búsqueda de frases

Encontrar frases exactas:

{
  "query": {
    "match_phrase": {
      "description": "noise canceling"
    }
  }
}

Comodín y expresiones regulares

{
  "query": {
    "wildcard": {
      "name": "*headphone*"
    }
  }
}

Ordenación

{
  "query": { "match_all": {} },
  "sort": [
    { "price": "asc" },
    { "_score": "desc" }
  ]
}

Paginación

{
  "from": 20,
  "size": 10,
  "query": { "match_all": {} }
}

Agregaciones

Las agregaciones calculan estadísticas resumidas sobre tus datos.

Precio promedio por categoría

curl -X GET "http://localhost:9200/products/_search" \
  -u elastic:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "size": 0,
    "aggs": {
      "by_category": {
        "terms": { "field": "category" },
        "aggs": {
          "avg_price": { "avg": { "field": "price" } },
          "min_price": { "min": { "field": "price" } },
          "max_price": { "max": { "field": "price" } }
        }
      }
    }
  }'

Histograma de precios

{
  "size": 0,
  "aggs": {
    "price_histogram": {
      "histogram": {
        "field": "price",
        "interval": 25
      }
    }
  }
}

Histogramas de fechas

{
  "size": 0,
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "created_at",
        "calendar_interval": "month"
      }
    }
  }
}

Cardinalidad (recuentos únicos)

{
  "size": 0,
  "aggs": {
    "unique_categories": {
      "cardinality": { "field": "category" }
    }
  }
}

Asignaciones y analizadores

Tipos de campo

Tipo	Uso para
`text`	Texto completo, analizado
`keyword`	Valores exactos, filtrado, ordenación
`integer`, `float`	Números
`boolean`	Verdadero/falso
`date`	Fechas y horas
`object`	Objetos JSON anidados
`nested`	Arrays de objetos (mantiene relaciones)
`geo_point`	Coordenadas lat/lon

Analizadores personalizados

Para procesamiento de texto especializado:

{
  "settings": {
    "analysis": {
      "analyzer": {
        "autocomplete": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "autocomplete_filter"]
        }
      },
      "filter": {
        "autocomplete_filter": {
          "type": "edge_ngram",
          "min_gram": 2,
          "max_gram": 20
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "autocomplete",
        "search_analyzer": "standard"
      }
    }
  }
}

Gestión del clúster

Salud del clúster

curl -X GET "http://localhost:9200/_cluster/health"

Respuesta:

{
  "cluster_name": "elasticsearch",
  "status": "green",
  "number_of_nodes": 3,
  "active_primary_shards": 25
}

Estados:

verde: Todos los shards asignados
amarillo: Réplicas no asignadas (nodo único)
rojo: Shards primarios faltantes

Estadísticas de índice

curl -X GET "http://localhost:9200/_cat/indices?v"

Estadísticas de nodo

curl -X GET "http://localhost:9200/_nodes/stats"

Borrar caché

curl -X POST "http://localhost:9200/_cache/clear"

Pruebas con Apidog

Las consultas de Elasticsearch pueden ser complejas. Prueba a fondo.

1. Guardar consultas comunes

Almacenar plantillas de búsqueda en Apidog:

{
  "query": {
    "bool": {
      "must": [
        { "match": { "{{search_field}}": "{{search_term}}" } }
      ],
      "filter": [
        { "range": { "{{price_field}}": { "lte": "{{max_price}}" } } }
      ]
    }
  }
}

2. Validar respuestas

pm.test('Search returns results', () => {
  const response = pm.response.json()
  pm.expect(response.hits.total.value).to.be.above(0)
})

pm.test('Aggregations present', () => {
  const response = pm.response.json()
  pm.expect(response.aggregations).to.exist
})

3. Separación de entornos

# Local
ES_HOST: http://localhost:9200
ES_USER: elastic
ES_PASSWORD: your_password

# Producción
ES_HOST: https://search.yourcompany.com
ES_API_KEY: prod_api_key

Prueba las API de Elasticsearch con Apidog - gratis

Errores comunes y soluciones

403 Prohibido

Causa: Autenticación fallida o permisos insuficientes.

Solución: Verifica las credenciales. Comprueba que la clave API tenga los permisos de índice correctos.

404 index_not_found_exception

Causa: El índice no existe.

Solución: Crea el índice primero, o usa la creación automática (habilitada por defecto pero no recomendada para producción).

circuit_breaking_exception

Causa: La consulta usa demasiada memoria.

Solución: Reduce el parámetro size, simplifica las consultas, añade filtros para reducir el conjunto de resultados.

search_phase_execution_exception

Causa: Error de sintaxis en la consulta.

Solución: Revisa tu JSON. Problemas comunes: comillas faltantes, rutas de campo incorrectas.

Alternativas y comparaciones

Característica	Elasticsearch	OpenSearch	Meilisearch	Typesense
Configuración	Autoalojado	Autoalojado	Binario único	Binario único
Calidad de búsqueda	Excelente	Bueno	Excelente	Bueno
Curva de aprendizaje	Pronunciada	Pronunciada	Fácil	Fácil
Escalabilidad	Excelente	Excelente	Bueno	Bueno
Oferta en la nube	Elastic Cloud	OpenSearch Serverless	Meilisearch Cloud	Typesense Cloud

Elasticsearch tiene la mayoría de las características y la comunidad más grande. Meilisearch y Typesense son más simples para la búsqueda básica.

Casos de uso en el mundo real

Búsqueda en comercio electrónico. Un sitio de venta al por menor indexa 100.000 productos. Los usuarios buscan por nombre, descripción, categoría y rango de precios. El autocompletado sugiere productos mientras escriben. Los filtros restringen los resultados por categoría y disponibilidad.

Registros de aplicaciones. Un equipo de DevOps envía registros a Elasticsearch a través de Filebeat. Los ingenieros buscan registros por servicio, gravedad y rango de tiempo. Los paneles muestran tasas de error y tiempos de respuesta.

Análisis de seguridad. Un equipo de seguridad indexa registros de red. Buscan direcciones IP sospechosas, visualizan patrones de tráfico y alertan sobre anomalías detectadas mediante agregaciones.

Conclusión

Esto es lo que has aprendido:

Indexar documentos como JSON
Consultar con el DSL de Elasticsearch
Usar agregaciones para análisis
Configurar asignaciones para una búsqueda óptima
Monitorizar la salud del clúster

Tus próximos pasos:

Ejecuta Elasticsearch localmente
Crea un índice con asignaciones
Indexa algunos documentos de prueba
Escribe consultas de búsqueda
Prueba las agregaciones

Prueba las API de Elasticsearch con Apidog - gratis

button

Preguntas frecuentes

¿Cuál es la diferencia entre Elasticsearch y Solr?Ambos son motores de búsqueda basados en Lucene. Elasticsearch tiene un mejor diseño distribuido y API. Solr tiene más funciones empresariales. La mayoría de los nuevos proyectos eligen Elasticsearch.

¿Cómo manejo los caracteres especiales en la búsqueda?Escapa los caracteres especiales: ()[]{}:^\"\\+-!~*?| con una barra invertida. O usa una simple_query_string que es más indulgente.

¿Qué es un shard?Los shards son partes de un índice. Cada shard es un índice Lucene. Los shards primarios son para escritura, los shards de réplica son copias para escalado de lectura y tolerancia a fallos.

¿Cuántos shards debo crear?Regla general: 20-50 GB por shard. Empieza con 1 shard primario, añade réplicas. Solo aumenta los shards primarios cuando sea necesario (no se pueden disminuir).

¿Puedo cambiar las asignaciones después de la indexación?Parcialmente. Puedes añadir nuevos campos libremente. Para cambiar los tipos de campo existentes, reindexa los datos. Usa plantillas de índice para gestionar las asignaciones de forma consistente.

¿Qué es el parámetro _routing?Enruta documentos a shards específicos basándose en un valor de campo. El valor por defecto es _id. Usa el enrutamiento cuando las consultas siempre filtran por un campo específico (como user_id) para un mejor rendimiento.

¿Cómo manejo los datos basados en el tiempo?Usa índices basados en fechas: logs-2026.03.24. Esto te permite eliminar datos antiguos eliminando índices y mejora el rendimiento de las consultas al buscar en menos índices.