Cliente Elasticsearch para TypeScript: @elastic/elasticsearch

Cliente Elasticsearch para TypeScript: @elastic/elasticsearch

A biblioteca @elastic/elasticsearch é o cliente oficial e mais completo para interagir com o mecanismo de busca Elasticsearch a partir de aplicações em TypeScript e JavaScript. Ela fornece uma API conveniente para realizar todas as operações principais: indexação, busca, atualização, exclusão de dados, bem como gerenciamento de cluster e execução de agregações complexas. Graças ao suporte completo ao TypeScript, os desenvolvedores obtêm tipagem estrita, autocompletar na IDE e menos erros em tempo de compilação.

Instalação

Para instalar o cliente, execute o comando no terminal:

npm install @elastic/elasticsearch

Adicionalmente, recomenda-se instalar os tipos para Node.js, se você estiver trabalhando no ambiente Node:

npm install -D @types/node

Configuração básica de conexão

Crie uma instância do cliente, informando a URL do seu servidor Elasticsearch. Por padrão, é usada a porta 9200.

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

const client = new Client({  node: 'http://localhost:9200',  // Para clusters em nuvem, use cloud: { id: '...' }  // auth: { apiKey: '...' } ou { username: '...', password: '...' }});

Tipagem de respostas

Uma das principais vantagens do TypeScript é a capacidade de tipar documentos. O cliente suporta genéricos, permitindo definir estritamente a estrutura dos dados:

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

// Agora todas as operações no índice 'books' serão tipadasasync function addBook(book: Book) {  const result = await client.index<Book>({    index: 'books',    document: book,  });  return result;}

Operações CRUD

Criação/Indexação de documento

const book: Book = {  title: 'Guerra e Paz',  author: 'Liev Tolstói',  year: 1869,  isbn: '978-5-17-123456-7',};

const response = await client.index({  index: 'books',  id: '1', // opcional, pode não informar — o Elasticsearch gerará um ID  document: book,});console.log('Documento indexado:', response._id);

Obtenção de documento por ID

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

Atualização de documento

await client.update({  index: 'books',  id: '1',  doc: {    rating: 4.8, // atualização parcial  },});

Exclusão de documento

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

Busca de dados

O método principal para busca em texto completo é search. Ele aceita o Query DSL (Domain Specific Language) do 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'], // busca em vários 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

Agregações

As agregações permitem obter dados estatísticos sobre o índice, por exemplo, a quantidade de livros por ano.

async function getBooksByYear() {  const result = await client.search({    index: 'books',    size: 0, // não retorna os documentos em si, apenas as agregações    aggs: {      books_per_year: {        terms: { field: 'year' },      },    },