New Elasticsearch JavaScript client released

After a month of active development, gathering feedback and introducing new features, we are thrilled to announce the GA release of the new JavaScript client!

Wait, a new JavaScript client? Yes! We announced the RC1 a few weeks back, and now we’re production-ready.

Try out the Elasticsearch JavaScript client

First, install the client and run Elasticsearch. You can install Elasticsearch locally with our docker image.

npm install @elastic/elasticsearch

Then create a JavaScript file (TypeScript is supported as well!) and paste inside the following snippet:

'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({ node: 'http://localhost:9200' })
async function run () {
  // Let's start by indexing some data
  await client.index({
    index: 'game-of-thrones',
    body: {
      character: 'Ned Stark',
      quote: 'Winter is coming.'
    }
  })
  await client.index({
    index: 'game-of-thrones',
    body: {
      character: 'Daenerys Targaryen',
      quote: 'I am the mother of dragons.'
    }
  })
  await client.index({
    index: 'game-of-thrones',
    // here we are forcing an index refresh,
    // otherwise we will not get any result
    // in the consequent search
    refresh: true,
    body: {
      character: 'Tyrion Lannister',
      quote: 'A mind needs books like a sword needs a whetstone.'
    }
  })
  // Let's search!
  const { body } = await client.search({
    index: 'game-of-thrones',
    body: {
      query: {
        match: {
          quote: 'winter'
        }
      }
    }
  })
  console.log(body.hits.hits)
}
run().catch(console.log)

What’s new?

In addition to all the features added with the new client, in the past month we have listened to your feedback and added new cool features. Some recently-added features are observability, support for sniffing hostnames, improved the type definitions, and the support for a custom HTTP agent. We also vastly improved our JS client documentation and decreased the size of the library.

Observability

Thanks to the new observability features now it will be easier to connect the dots between events. In every event, you will find the id of the request that generated the event, as well as the name of the client (which will be very useful if you are working with child clients).

Below you can see all the data that is exposed by our observability events:

body: any;
statusCode: number | null;
headers: anyObject | null;
warnings: string[] | null;
meta: {
  context: any;
  name: string;
  request: {
    params: TransportRequestParams;
    options: TransportRequestOptions;
    id: any;
  };
  connection: Connection;
  attempts: number;
  aborted: boolean;
  sniff?: {
    hosts: any[];
    reason: string;
  };
};

Want to know more? Check out our observability documentation!

Type definitions

The client offers first-class support for TypeScript, it offers type definitions for its entire API and the parameter of every method. The type definition of the request and response bodies are not yet supported, but we are working on that!

In the meantime, we have vastly improved the developer experience by using generics for all the body definitions.

import { RequestParams } from '@elastic/elasticsearch'
interface SearchBody {
  query: {
    match: { foo: string }
  }
}
const searchParams: RequestParams.Search<SearchBody> = {
  index: 'test',
  body: {
    query: {
      match: { foo: 'bar' }
    }
  }
}
// This is valid as well
const searchParams: RequestParams.Search = {
  index: 'test',
  body: {
    query: {
      match: { foo: 'bar' }
    }
  }
}

You can find a complete example in our TypeScript documentation.

Conclusion

We’re excited about the new JavaScript client, and we hope you are too. Try it out today, locally or on the Elasticsearch Service, and let us know what you think. If you want to know more, you can open an issue in the client repository, post a question in Discuss, or ping @delvedor on Twitter. Happy coding!