Cliente Elasticsearch para TypeScript: @elastic/elasticsearch

Cliente Elasticsearch para TypeScript: @elastic/elasticsearch

La librería @elastic/elasticsearch es el cliente oficial y más completo para interactuar con el motor de búsqueda Elasticsearch desde aplicaciones en TypeScript y JavaScript. Proporciona una API conveniente para realizar todas las operaciones principales: indexación, búsqueda, actualización, eliminación de datos, así como la gestión del clúster y la ejecución de agregaciones complejas. Gracias al soporte completo de TypeScript, los desarrolladores obtienen tipado estricto, autocompletado en el IDE y menos errores en la etapa de compilación.

Instalación

Para instalar el cliente, ejecute el comando en la terminal:

npm install @elastic/elasticsearch

Adicionalmente, se recomienda instalar los tipos para Node.js si trabaja en un entorno Node:

npm install -D @types/node

Configuración básica de conexión

Cree una instancia del cliente especificando la URL de su servidor Elasticsearch. Por defecto, se utiliza el puerto 9200.

import { Client } from '@elastic/elasticsearch';

const client = new Client({  node: 'http://localhost:9200',  // Para clústeres en la nube, use cloud: { id: '...' }  // auth: { apiKey: '...' } o { username: '...', password: '...' }});

Tipado de respuestas

Una de las principales ventajas de TypeScript es la capacidad de tipar los documentos. El cliente admite genéricos, lo que permite definir estrictamente la estructura de los datos:

interface Book {  title: string;  author: string;  year: number;  isbn: string;  rating?: number; // campo opcional}

// Ahora todas las operaciones con el índice 'books' estarán tipadasasync function addBook(book: Book) {  const result = await client.index<Book>({    index: 'books',    document: book,  });  return result;}

Operaciones CRUD

Creación/indexación de un documento

const book: Book = {  title: 'Guerra y paz',  author: 'León Tolstói',  year: 1869,  isbn: '978-5-17-123456-7',};

const response = await client.index({  index: 'books',  id: '1', // opcional, se puede omitir — Elasticsearch generará un ID  document: book,});console.log('Documento indexado:', response._id);

Obtener un documento por ID

const getResponse = await client.get({  index: 'books',  id: '1',});console.log('Documento encontrado:', getResponse._source); // tipado como Book

Actualizar un documento

await client.update({  index: 'books',  id: '1',  doc: {    rating: 4.8, // actualización parcial  },});

Eliminar un documento

await client.delete({  index: 'books',  id: '1',});

Búsqueda de datos

El método principal para la búsqueda de texto completo es search. Acepta el Query DSL (Domain Specific Language) de Elasticsearch.

interface SearchResult {  hits: {    total: { value: number };    hits: Array<{ _source: Book }>;  };}

async function searchBooks(query: string) {  const result = await client.search<SearchResult>({    index: 'books',    query: {      multi_match: {        query: query,        fields: ['title', 'author'], // búsqueda en múltiples campos      },    },  });

  const books = result.hits.hits.map(hit => hit._source);  return books;}

// Usoconst books = await searchBooks('Tolstói');console.log(books); // array de objetos Book

Agregaciones

Las agregaciones permiten obtener datos estadísticos sobre el índice, por ejemplo, la cantidad de libros por año.

async function getBooksByYear() {  const result = await client.search({    index: 'books',    size: 0, // no devolvemos los documentos, solo las agregaciones    aggs: {      books_per_year: {        terms: { field: 'year' },      },    },