Basic configuration

This page explains the basic configuration options for the JavaScript client.

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

const client = new Client({
  cloud: { id: '<cloud-id>' },
  auth: { apiKey: 'base64EncodedKey' },
  maxRetries: 5,
  sniffOnStart: true
})

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

node: 'http://localhost:9200'

nodes: ['http://localhost:9200', 'http://localhost:9201']

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

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

Default: null

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

Basic authentication:

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

ApiKey authentication:

auth: {
  apiKey: 'base64EncodedKey'
}

Bearer authentication, useful for service account tokens. Be aware that it does not handle automatic token refresh:

auth: {
  bearer: 'token'
}

Type: number
Default: 3

Max number of retries for each request.

Type: number
Default: No value

Max request timeout in milliseconds for each request.

Type: number
Default: 3000

Max ping request timeout in milliseconds for each request.

Type: number, boolean
Default: false

Perform a sniff operation every n milliseconds.

Type: boolean
Default: false

Perform a sniff once the client is started. Be sure to review the sniffing best practices blog post.

Type: string
Default: '_nodes/_all/http'

Endpoint to ping during a sniff. Be sure to review the sniffing best practices blog post.

Type: boolean
Default: false

Perform a sniff on connection fault. Be sure to review the sniffing best practices blog post.

Type: string
Default: 'ping'

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

Type: boolean
Default: false

Adds an accept-encoding header to every request.

Type: string, boolean
Default: false

Enables gzip request body compression.
Options: 'gzip', false

Type: http.SecureContextOptions
Default: null

The tls configuraton.

Type: string, URL
Default: null

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

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'
})

Type: http.AgentOptions, function
Default: null

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.

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

const client = new Client({
  node: 'http://localhost:9200',
  // the function takes as parameter the option
  // object passed to the Connection constructor
  agent: (opts) => new CustomAgent()
})

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

Type: function

Filter that indicates whether a node should be used for a request. Default function definition:

function defaultNodeFilter (conn) {
  if (conn.roles != null) {
    if (
      // avoid master-only nodes
      conn.roles.master &&
      !conn.roles.data &&
      !conn.roles.ingest &&
      !conn.roles.ml
    ) return false
  }
  return true
}

Type: function
Default: 'round-robin'

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

Custom function example:

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

Type: 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'
}

Type: string, symbol
Default: elasticsearch-js

The name to identify the client instance in the events.

Type: string
Default: null

A string that will be use to prefix any X-Opaque-Id header. See X-Opaque-Id support for more details.

Type: object
Default: {}

A set of custom headers to send in every request.

Type: object
Default: null

A custom object that you can use for observability in your events. It will be merged with the API level context option.

Type: boolean
Default: true

If true, adds an header named 'x-elastic-client-meta', containing some minimal telemetry data, such as the client and platform version.

Type: object
Default: null

Custom configuration for connecting to Elastic Cloud. See Authentication for more details.

Cloud configuration example:

const client = new Client({
  cloud: {
    id: '<cloud-id>'
  },
  auth: {
    username: 'elastic',
    password: 'changeme'
  }
})

Default: true

boolean, 'proto', 'constructor' - The client can protect you against prototype poisoning attacks. For more information, refer to Square Brackets are the Enemy. If needed, you can enable prototype poisoning protection entirely (false) or one of the two checks ('proto' or 'constructor'). For performance reasons, it is disabled by default. To learn more, refer to the secure-json-parse documentation.

Type: string
Default: null

If configured, verify that the fingerprint of the CA certificate that has signed the certificate of the server matches the supplied fingerprint. Only accepts SHA256 digest fingerprints.

Type: number
Default: null

When configured, maxResponseSize verifies that the uncompressed response size is lower than the configured number. If it’s higher, the request will be canceled. The maxResponseSize cannot be higher than the value of buffer.constants.MAX_STRING_LENGTH.

Type: number
Default: null

When configured, maxCompressedResponseSize verifies that the compressed response size is lower than the configured number. If it’s higher, the request will be canceled. The maxCompressedResponseSize cannot be higher than the value of buffer.constants.MAX_STRING_LENGTH.

Type: object
Default: A configuration that will replace known sources of sensitive data in Error metadata

Options for how to redact potentially sensitive data from metadata attached to Error objects

Type: string
Default: "stack"

Setting to "stack" sets defaults assuming a traditional (non-serverless) Elasticsearch instance. Setting to "serverless" sets defaults to work more seamlessly with Elastic Cloud Serverless, like enabling compression and disabling features that assume the possibility of multiple Elasticsearch nodes.