@elastic/elasticsearch

What is @elastic/elasticsearch?

@elastic/elasticsearch is the official Node.js client for Elasticsearch. It allows developers to interact with Elasticsearch clusters, perform CRUD operations, search, and manage indices, among other functionalities.

What are @elastic/elasticsearch's main functionalities?

Connecting to Elasticsearch

This code demonstrates how to create a new client instance to connect to an Elasticsearch cluster running on localhost.

const { Client } = require('@elastic/elasticsearch');
const client = new Client({ node: 'http://localhost:9200' });

Indexing Documents

This code sample shows how to index a document into an Elasticsearch index named 'my-index'.

async function run() {
  await client.index({
    index: 'my-index',
    id: '1',
    body: {
      title: 'Test Document',
      content: 'This is a test document.'
    }
  });
}
run().catch(console.log);

Searching Documents

This code demonstrates how to search for documents in the 'my-index' index that match the term 'Test' in the title field.

async function run() {
  const { body } = await client.search({
    index: 'my-index',
    body: {
      query: {
        match: { title: 'Test' }
      }
    }
  });
  console.log(body.hits.hits);
}
run().catch(console.log);

Managing Indices

This code sample shows how to create a new index named 'my-new-index' in Elasticsearch.

async function run() {
  await client.indices.create({
    index: 'my-new-index'
  });
}
run().catch(console.log);

Other packages similar to @elastic/elasticsearch

elasticsearch

The 'elasticsearch' package is an older, community-maintained client for Elasticsearch. It provides similar functionalities but is not officially maintained by Elastic. It may lack some of the newer features and optimizations present in @elastic/elasticsearch.

searchkit

Searchkit is a toolkit for building search UIs with Elasticsearch. It provides higher-level abstractions and components for building search interfaces, making it easier to integrate Elasticsearch into front-end applications. However, it may not offer the same low-level control as @elastic/elasticsearch.

README

elasticsearch-js integration test suite

What? A README to explain how the integration test work??

Yes.

Background

Elasticsearch offers its entire API via HTTP REST endpoints. You can find the whole API specification for every version here.
To support different languages at the same time, the Elasticsearch team decided to provide a YAML specification to test every endpoint, body, headers, warning, error and so on.
This testing suite uses that specification to generate the test for the specified version of Elasticsearch on the fly.

Run

Run the testing suite is very easy, you just need to run the preconfigured npm script:

npm run test:integration

The first time you run this command, the Elasticsearch repository will be cloned inside the integration test folder, to be able to access the YAML specification, so it might take some time (luckily, only the first time).
Once the Elasticsearch repository has been cloned, the testing suite will connect to the provided Elasticsearch instance and then checkout the build hash in the repository. Finally, it will start running every test.

The specification does not allow the test to be run in parallel, so it might take a while to run the entire testing suite; on my machine, MacBookPro15,2 core i7 2.7GHz 16GB of RAM it takes around four minutes.

Exit on the first failure

Bu default the suite will run all the test, even if one assertion has failed. If you want to stop the test at the first failure, use the bailout option:

npm run test:integration -- --bail

Calculate the code coverage

If you want to calculate the code coverage just run the testing suite with the following parameters, once the test ends, it will open a browser window with the results.

npm run test:integration -- --cov --coverage-report=html

How does this thing work?

At first sight, it might seem complicated, but once you understand what the moving parts are, it's quite easy.

1. Connects to the given Elasticsearch instance
2. Gets the ES version and build hash
3. Checkout to the given hash (and clone the repository if it is not present)
4. Reads the folder list and for each folder the yaml file list
5. Starts running folder by folder every file
6. Read and parse the yaml files
7. Creates a subtest structure to have a cleaner output
8. Runs the assertions
9. Repeat!

Inside the index.js file, you will find the connection, cloning, reading and parsing part of the test, while inside the test-runner.js file you will find the function to handle the assertions. Inside test-runner.js, we use a queue to be sure that everything is run in the correct order.

Checkout the rest-api-spec readme if you want to know more about how the assertions work.

Why are we running the test with the --harmony flag?

Because on Node v6 the regex lookbehinds are not supported.