DEV Community

Cover image for Cómo Usar las APIs de Elasticsearch
Roobia
Roobia

Posted on • Originally published at apidog.com

Cómo Usar las APIs de Elasticsearch

En resumen

Las API de Elasticsearch permiten búsqueda y análisis a gran escala. Indexa documentos como JSON, consulta usando el potente DSL y agrega resultados para análisis. La autenticación se realiza con claves API o autenticación básica. Para pruebas, utiliza Apidog para validar asignaciones de índices, probar consultas y depurar agregaciones antes de desplegar en producción.

Prueba Apidog hoy

Introducción

Elasticsearch es un motor distribuido de búsqueda y análisis. Procesa texto estructurado, logs, métricas y más. Es común en aplicaciones de búsqueda de texto completo, análisis de logs para debugging y dashboards de analítica en tiempo real.

Elasticsearch es el núcleo de la pila ELK (Elasticsearch, Logstash, Kibana), pero puedes consumirlo directamente vía API.

💡 Consejo: Si desarrollas funciones de búsqueda o análisis de logs, Apidog te permite probar consultas, validar asignaciones y depurar agregaciones. Guarda tus plantillas de búsqueda y compártelas con el equipo.

Prueba las API de Elasticsearch con Apidog - gratis

Al finalizar 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 descarga el binario desde elastic.co
Enter fullscreen mode Exit fullscreen mode

Verificar instalación 

curl -X GET "http://localhost:9200"
Enter fullscreen mode Exit fullscreen mode

Respuesta esperada:

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

Autenticación

Desde la versión 8.x, Elasticsearch requiere autenticación por defecto.

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

Alternativamente, usa claves API generadas en Kibana o vía API.

Índices y documentos

Crear un índice

Define settings y mappings iniciales:

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" }
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Respuesta:

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

Obtener un documento 

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

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Eliminar un documento 

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

Operaciones masivas (bulk)

Indexa varios documentos eficientemente:

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}
'
Enter fullscreen mode Exit fullscreen mode

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"
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Consultas booleanas

Combina condiciones para búsquedas avanzadas:

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

Búsqueda de texto completo con puntuación 

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

Los campos con ^2 tienen mayor peso en la puntuación.

Búsqueda de frases

Busca frases exactas:

{
  "query": {
    "match_phrase": {
      "description": "noise canceling"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Comodín y expresiones regulares 

{
  "query": {
    "wildcard": {
      "name": "*headphone*"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Ordenación 

{
  "query": { "match_all": {} },
  "sort": [
    { "price": "asc" },
    { "_score": "desc" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Paginación 

{
  "from": 20,
  "size": 10,
  "query": { "match_all": {} }
}
Enter fullscreen mode Exit fullscreen mode

Agregaciones

Utiliza agregaciones para obtener estadísticas y métricas.

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" } }
        }
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Histograma de precios 

{
  "size": 0,
  "aggs": {
    "price_histogram": {
      "histogram": {
        "field": "price",
        "interval": 25
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Histogramas de fechas 

{
  "size": 0,
  "aggs": {
    "sales_over_time": {
      "date_histogram": {
        "field": "created_at",
        "calendar_interval": "month"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Cardinalidad (recuentos únicos) 

{
  "size": 0,
  "aggs": {
    "unique_categories": {
      "cardinality": { "field": "category" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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

Configura un analizador para autocompletado:

{
  "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"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Gestión del clúster

Salud del clúster 

curl -X GET "http://localhost:9200/_cluster/health"
Enter fullscreen mode Exit fullscreen mode

Respuesta:

{
  "cluster_name": "elasticsearch",
  "status": "green",
  "number_of_nodes": 3,
  "active_primary_shards": 25
}
Enter fullscreen mode Exit fullscreen mode

Estados:

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

Estadísticas de índice 

curl -X GET "http://localhost:9200/_cat/indices?v"
Enter fullscreen mode Exit fullscreen mode

Estadísticas de nodo 

curl -X GET "http://localhost:9200/_nodes/stats"
Enter fullscreen mode Exit fullscreen mode

Borrar caché 

curl -X POST "http://localhost:9200/_cache/clear"
Enter fullscreen mode Exit fullscreen mode

Pruebas con Apidog

Las consultas en Elasticsearch pueden ser complejas. Testéalas a fondo antes de desplegar.

Testing Elasticsearch APIs con Apidog

1. Guardar consultas comunes

Define plantillas reutilizables con variables:

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

2. Validar respuestas

Automatiza pruebas de respuesta con JavaScript en Apidog:

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
})
Enter fullscreen mode Exit fullscreen mode

3. Separación de entornos

Define variables para ambientes local y producción:

# 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
Enter fullscreen mode Exit fullscreen mode

Prueba las API de Elasticsearch con Apidog - gratis

Errores comunes y soluciones

403 Prohibido

Causa: Autenticación fallida o permisos insuficientes.

Solución: Verifica tus credenciales y que la clave API tenga permisos correctos.

404 index_not_found_exception

Causa: El índice no existe.

Solución: Crea el índice antes o habilita la creación automática (no recomendado para producción).

circuit_breaking_exception

Causa: Consulta requiere demasiada memoria.

Solución: Reduce el parámetro size, simplifica la consulta o añade filtros.

search_phase_execution_exception

Causa: Error de sintaxis en la consulta.

Solución: Valida el JSON. Corrige comillas, rutas de campo o errores de formato.

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 cantidad de características y comunidad. Meilisearch y Typesense son más simples para búsquedas básicas.

Casos de uso en el mundo real

Búsqueda en e-commerce: Indexa productos, permite búsquedas por nombre, descripción, categoría y rango de precios. Implementa autocompletado y filtros por categoría/disponibilidad.

Logs de aplicaciones: Envía logs a Elasticsearch con Filebeat. Filtra por servicio, severidad y tiempo. Usa dashboards para tasas de error y tiempos de respuesta.

Analítica de seguridad: Indexa logs de red, busca IPs sospechosas, visualiza patrones de tráfico y detecta anomalías con agregaciones.

Conclusión

Lo aprendido:

  • Indexación de documentos JSON
  • Consultas usando el DSL de Elasticsearch
  • Agregaciones para análisis
  • Configuración de asignaciones óptimas
  • Monitorización del clúster

Próximos pasos:

  1. Ejecuta Elasticsearch localmente
  2. Crea un índice con mappings adecuados
  3. Indexa documentos de prueba
  4. Escribe consultas de búsqueda
  5. Prueba agregaciones

Prueba las API de Elasticsearch con Apidog - gratis

Preguntas frecuentes

¿Cuál es la diferencia entre Elasticsearch y Solr?

Ambos son motores de búsqueda basados en Lucene. Elasticsearch está más orientado a APIs y distribución; Solr ofrece más funciones empresariales. Para proyectos nuevos, Elasticsearch suele ser preferido.

¿Cómo manejo caracteres especiales en búsquedas?

Escapa estos caracteres: ()[]{}:^\"\\+-!~*?| con una barra invertida. O utiliza simple_query_string.

¿Qué es un shard?

Partición de un índice. Un shard primario es para escritura; los de réplica son copias para lectura/escalado.

¿Cuántos shards crear?

20-50 GB por shard es buena práctica. Empieza con 1 shard primario y réplicas; sólo aumenta los primarios si es necesario.

¿Puedo cambiar mappings tras la indexación?

Puedes añadir nuevos campos. Para cambiar tipos de campo existentes, es necesario reindexar. Usa plantillas de índice para consistencia.

¿Qué es el parámetro _routing?

Permite enrutar documentos a shards específicos según un campo (por defecto _id). Útil si consultas siempre filtran por un campo concreto (ej: user_id).

¿Cómo manejo datos basados en tiempo?

Usa índices por fecha (logs-2026.03.24). Así puedes eliminar datos antiguos fácilmente y mejorar el rendimiento de consulta.

Top comments (0)