Elasticsearch client for TypeScript: @elastic/elasticsearch

Elasticsearch client for TypeScript (@elastic/elasticsearch)

In modern web development, full-text search and data analysis have become an integral part of many applications. Elasticsearch is a powerful distributed search engine built on top of Apache Lucene. To work with it from TypeScript applications (both on the Node.js server and in the browser), the official client @elastic/elasticsearch is used. In this article, we will thoroughly examine its installation, configuration, and main capabilities.

What is @elastic/elasticsearch?

@elastic/elasticsearch is the official, high-performance client for Elasticsearch, written in TypeScript. It provides a full set of APIs for interacting with an Elasticsearch cluster, including:

• Indexing and deleting documents
• Full-text search with support for complex queries
• Aggregations for data analysis (grouping, statistics)
• Managing indices and mappings
• Support for connection pooling, retries, and load balancing

Thanks to full TypeScript support, you get autocompletion, type checking, and documentation directly in the IDE.

Installation

To get started, install the package via npm or yarn:

npm install @elastic/elasticsearch# oryarn add @elastic/elasticsearch

If you are using TypeScript, no additional types need to be installed — they are already built into the package.

Connecting and configuring the client

Create a client instance by specifying the URL of your Elasticsearch cluster:

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

const client = new Client({  node: 'http://localhost:9200', // or cloud endpoint  auth: {    username: 'elastic',    password: 'changeme'  },  // For production, it is recommended to use TLS  tls: {    rejectUnauthorized: false // development only!  }});

For cloud deployments (Elastic Cloud), use cloud.id and auth.apiKey:

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

Basic operations

1. Indexing a document

Adding a new document to an index:

interface Product {  id: number;  name: string;  description: string;  price: number;  tags: string[];}

async function indexProduct(product: Product) {  const response = await client.index({    index: 'products',    id: String(product.id),    body: product,    refresh: 'wait_for' // wait for the index to refresh  });  console.log('Document indexed:', response.result);}

indexProduct({  id: 1,  name: 'Lenovo ThinkPad Laptop',  description: 'Powerful laptop for development',  price: 1200,  tags: ['electronics', 'laptops']});

2. Searching documents

Simple full-text search on the description field:

async function searchProducts(query: string) {  const response = await client.search({    index: 'products',    body: {      query: {        match: {          description: query        }      },      // Pagination      from: 0,      size: 10    }  });

  const hits = response.hits.hits.map(hit => hit._source);  console.log('Found products:', hits);  return hits;}

searchProducts('laptop development');

3. Aggregations

Grouping products by tags:

async function aggregateByTags() {  const response = await client.search({    index: 'products',    body: {      size: 0, // do not return the documents themselves      aggs: {        by_tag: {          terms: {            field: 'tags.keyword',            size: 20          }        }