Client configurationedit

The client is designed to be easily configured for your needs. In the following section, you can see the possible basic options that you can use to configure it.

const { Client } = require('@elastic/elasticsearch')

const client = new Client({
  node: 'http://localhost:9200',
  maxRetries: 5,
  requestTimeout: 60000,
  sniffOnStart: true
})

Basic optionsedit

node or nodes

The Elasticsearch endpoint to use.
It can be a single string or an array of strings:

node: 'http://localhost:9200'

Or it can be an object (or an array of objects) that represents the node:

node: {
  url: new URL('http://localhost:9200'),
  ssl: 'ssl options',
  agent: 'http agent options',
  id: 'custom node id',
  headers: { 'custom': 'headers' }
  roles: {
    master: true,
    data: true,
    ingest: true,
    ml: false
  }
}

auth

Your authentication data. You can use both basic authentication and ApiKey.
See Authentication for more details.
Default: null

Basic authentication:

auth: {
  username: 'elastic',
  password: 'changeme'
}

ApiKey authentication:

auth: {
  apiKey: 'base64EncodedKey'
}

maxRetries

number - Max number of retries for each request.
Default: 3

requestTimeout

number - Max request timeout in milliseconds for each request.
Default: 30000

pingTimeout

number - Max ping request timeout in milliseconds for each request.
Default: 3000

sniffInterval

number, boolean - Perform a sniff operation every n milliseconds. Sniffing might not be the best solution for you, take a look here to know more.
Default: false

sniffOnStart

boolean - Perform a sniff once the client is started. Sniffing might not be the best solution for you, take a look here to know more.
Default: false

sniffEndpoint

string - Endpoint to ping during a sniff.
Default: '_nodes/_all/http'

sniffOnConnectionFault

boolean - Perform a sniff on connection fault. Sniffing might not be the best solution for you, take a look here to know more.
Default: false

resurrectStrategy

string - Configure the node resurrection strategy.
Options: 'ping', 'optimistic', 'none'
Default: 'ping'

suggestCompression

boolean - Adds accept-encoding header to every request.
Default: false

compression

string, boolean - Enables gzip request body compression.
Options: 'gzip', false
Default: false

ssl

http.SecureContextOptions - ssl configuraton.
Default: null

proxy

string, URL - If you are using an http(s) proxy, you can put its url here. The client will automatically handle the connection to it.
Default: null

const client = new Client({
  node: 'http://localhost:9200',
  proxy: 'http://localhost:8080'
})

const client = new Client({
  node: 'http://localhost:9200',
  proxy: 'http://user:pwd@localhost:8080'
})

agent

http.AgentOptions, function - http agent options, or a function that returns an actual http agent instance. If you want to disable the http agent use entirely (and disable the keep-alive feature), set the agent to false.
Default: null

const client = new Client({
  node: 'http://localhost:9200',
  agent: { agent: 'options' }
})

const client = new Client({
  node: 'http://localhost:9200',
  agent: () => new CustomAgent()
})

const client = new Client({
  node: 'http://localhost:9200',
  // Disable agent and keep-alive
  agent: false
})

nodeFilter

function - Filters which node not to use for a request.
Default:

function defaultNodeFilter (node) {
  // avoid master only nodes
  if (node.roles.master === true &&
      node.roles.data === false &&
      node.roles.ingest === false) {
    return false
  }
  return true
}

nodeSelector

function - custom selection strategy.
Options: 'round-robin', 'random', custom function
Default: 'round-robin'
Custom function example:

function nodeSelector (connections) {
  const index = calculateIndex()
  return connections[index]
}

generateRequestId

function - function to generate the request id for every request, it takes two parameters, the request parameters and options.
By default it generates an incremental integer for every request.
Custom function example:

function generateRequestId (params, options) {
  // your id generation logic
  // must be syncronous
  return 'id'
}

name

`string

symbol` - The name to identify the client instance in the events.
Default: elasticsearch-js

opaqueIdPrefix

string - A string that will be use to prefix any X-Opaque-Id header.
See https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/observability.html#x-opaque-id_support[X-Opaque-Id support] for more details.
_Default:
null

headers

object - A set of custom headers to send in every request.
Default: {}

context

object - A custom object that you can use for observability in yoru events. It will be merged with the API level context option.
Default: null

cloud

Advanced configurationedit

If you need to customize the client behavior heavily, you are in the right place! The client allows you to customize the following internals:

  • Transport class
  • ConnectionPool class
  • Connection class
  • Serializer class

Transportedit

This class is responsible for performing the request to Elasticsearch and handling errors, it also handles the sniffing.

const { Client, Transport } = require('@elastic/elasticsearch')

class MyTransport extends Transport {
  request (params, options, callback) {
    // your code
  }
}

const client = new Client({
    Transport: MyTransport
})

Sometimes you need to inject a small snippet of your code and then continue to use the usual client code. In such cases, call super.method:

class MyTransport extends Transport {
  request (params, options, callback) {
    // your code
    return super.request(params, options, callback)
  }
}

ConnectionPooledit

This class is responsible for keeping in memory all the Elasticsearch Connection that we are using. There is a single Connection for every node. The connection pool handles the resurrection strategies and the updates of the pool.

const { Client, ConnectionPool } = require('@elastic/elasticsearch')

class MyConnectionPool extends ConnectionPool {
  markAlive (connection) {
    // your code
    super.markAlive(connection)
  }
}

const client = new Client({
    ConnectionPool: MyConnectionPool
})

Connectionedit

This class represents a single node, it holds every information we have on the node, such as roles, id, URL, custom headers and so on. The actual HTTP request is performed here, this means that if you want to swap the default HTTP client (Node.js core), you should override the request method of this class.

const { Client, Connection } = require('@elastic/elasticsearch')

class MyConnection extends Connection {
  request (params, callback) {
    // your code
  }
}

const client = new Client({
  Connection: MyConnection
})

Serializeredit

This class is responsible for the serialization of every request, it offers the following methods:

  • serialize(object: any): string; serializes request objects.
  • deserialize(json: string): any; deserializes response strings.
  • ndserialize(array: any[]): string; serializes bulk request objects.
  • qserialize(object: any): string; serializes request query parameters.
const { Client, Serializer } = require('@elastic/elasticsearch')

class MySerializer extends Serializer {
  serialize (object) {
    // your code
  }
}

const client = new Client({
  Serializer: MySerializer
})