Cliente Elasticsearch para TypeScript: @elastic/elasticsearch

Cliente Elasticsearch para TypeScript (@elastic/elasticsearch)

\n\n

En el desarrollo web moderno, la búsqueda de texto completo y el análisis de datos se han convertido en una parte esencial de muchas aplicaciones. Elasticsearch es un potente sistema de búsqueda distribuido construido sobre Apache Lucene. Para trabajar con él desde aplicaciones TypeScript (tanto en el servidor Node.js como en el navegador), se utiliza el cliente oficial @elastic/elasticsearch. En este artículo, analizaremos en detalle su instalación, configuración y principales capacidades.

\n\n

¿Qué es @elastic/elasticsearch?

\n\n

@elastic/elasticsearch es el cliente oficial de alto rendimiento para Elasticsearch, escrito en TypeScript. Proporciona un conjunto completo de API para interactuar con un clúster de Elasticsearch, incluyendo:

\n\n

\n
• Indexación y eliminación de documentos
\n
• Búsqueda de texto completo con soporte para consultas complejas
\n
• Agregaciones para análisis de datos (agrupación, estadísticas)
\n
• Gestión de índices y mapeo
\n
• Soporte para pool de conexiones, reintentos y balanceo de carga
\n

\n\n

Gracias al soporte completo de TypeScript, obtienes autocompletado, verificación de tipos y documentación directamente en el IDE.

\n\n

Instalación

\n\n

Para comenzar, instala el paquete mediante npm o yarn:

\n\n

npm install @elastic/elasticsearch\n# o\nyarn add @elastic/elasticsearch

\n\n

Si usas TypeScript, no es necesario instalar tipos adicionales, ya vienen incluidos en el paquete.

\n\n

Conexión y configuración del cliente

\n\n

Crea una instancia del cliente especificando la URL de tu clúster de Elasticsearch:

\n\n

import { Client } from '@elastic/elasticsearch';\n\nconst client = new Client({\n  node: 'http://localhost:9200', // o endpoint en la nube\n  auth: {\n    username: 'elastic',\n    password: 'changeme'\n  },\n  // Para producción se recomienda usar TLS\n  tls: {\n    rejectUnauthorized: false // ¡solo para desarrollo!\n  }\n});

\n\n

Para despliegues en la nube (Elastic Cloud), usa cloud.id y auth.apiKey:

\n\n

const client = new Client({\n  cloud: {\n    id: 'my-cluster:dXMtZWFzdD...'\n  },\n  auth: {\n    apiKey: 'base64EncodedApiKey'\n  }\n});

\n\n

Operaciones principales

\n\n

1. Indexación de un documento

\n\n

Añadir un nuevo documento a un índice:

\n\n

interface Product {\n  id: number;\n  name: string;\n  description: string;\n  price: number;\n  tags: string[];\n}\n\nasync function indexProduct(product: Product) {\n  const response = await client.index({\n    index: 'products',\n    id: String(product.id),\n    body: product,\n    refresh: 'wait_for' // esperar a que el índice se actualice\n  });\n  console.log('Document indexed:', response.result);\n}\n\nindexProduct({\n  id: 1,\n  name: 'Portátil Lenovo ThinkPad',\n  description: 'Potente portátil para desarrollo',\n  price: 1200,\n  tags: ['electrónica', 'portátiles']\n});

\n\n

2. Búsqueda de documentos

\n\n

Búsqueda simple de texto completo en el campo description:

\n\n

async function searchProducts(query: string) {\n  const response = await client.search({\n    index: 'products',\n    body: {\n      query: {\n        match: {\n          description: query\n        }\n      },\n      // Paginación\n      from: 0,\n      size: 10\n    }\n  });\n\n  const hits = response.hits.hits.map(hit => hit._source);\n  console.log('Found products:', hits);\n  return hits;\n}\n\nsearchProducts('portátil desarrollo');

\n\n

3. Agregaciones

\n\n

Agrupación de productos por etiquetas:

\n\n

async function aggregateByTags() {\n  const response = await client.search({\n    index: 'products',\n    body: {\n      size: 0, // no devolver los documentos en sí\n      aggs: {\n        by_tag: {\n          terms: {\n            field: 'tags.keyword',\n            size: 20\n          }\n        }\n