Elastic
Start free trial Contact Sales
Loading

Basic configuration

This page shows you the possible basic configuration options that the clients offers.

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

const client = new Client({
  cloud: { id: '<cloud-id>' },
  auth: { apiKey: 'base64EncodedKey' },
  maxRetries: 5,
  sniffOnStart: true
})
node or nodes The Elasticsearch endpoint to use.
It can be a single string or an array of strings:

js<br>node: 'http://localhost:9200'<br>

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

js<br>node: {<br> url: new URL('http://localhost:9200'),<br> tls: 'tls options',<br> agent: 'http agent options',<br> id: 'custom node id',<br> headers: { 'custom': 'headers' }<br> roles: {<br> master: true,<br> data: true,<br> ingest: true,<br> ml: false<br> }<br>}<br>
auth Your authentication data. You can use both basic authentication and ApiKey.
See Authentication for more details.
Default: null

Basic authentication:

js<br>auth: {<br> username: 'elastic',<br> password: 'changeme'<br>}<br>

ApiKey authentication:

js<br>auth: {<br> apiKey: 'base64EncodedKey'<br>}<br>

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

js<br>auth: {<br> bearer: 'token'<br>}<br>
maxRetries number - Max number of retries for each request.
Default: 3
requestTimeout number - Max request timeout in milliseconds for each request.
Default: No value
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
tls http.SecureContextOptions - tls 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

js<br>const client = new Client({<br> node: 'http://localhost:9200',<br> proxy: 'http://localhost:8080'<br>})<br><br>const client = new Client({<br> node: 'http://localhost:9200',<br> proxy: 'http://user:pwd@localhost:8080'<br>})<br>
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

js<br>const client = new Client({<br> node: 'http://localhost:9200',<br> agent: { agent: 'options' }<br>})<br><br>const client = new Client({<br> node: 'http://localhost:9200',<br> // the function takes as parameter the option<br> // object passed to the Connection constructor<br> agent: (opts) => new CustomAgent()<br>})<br><br>const client = new Client({<br> node: 'http://localhost:9200',<br> // Disable agent and keep-alive<br> agent: false<br>})<br>
nodeFilter function - Filters which node not to use for a request.
Default:

js<br>function defaultNodeFilter (node) {<br> // avoid master only nodes<br> if (node.roles.master === true &&<br> node.roles.data === false &&<br> node.roles.ingest === false) {<br> return false<br> }<br> return true<br>}<br>
nodeSelector function - custom selection strategy.
Options: 'round-robin', 'random', custom function
Default: 'round-robin'
Custom function example:

js<br>function nodeSelector (connections) {<br> const index = calculateIndex()<br> return connections[index]<br>}<br>
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:

js<br>function generateRequestId (params, options) {<br> // your id generation logic<br> // must be syncronous<br> return 'id'<br>}<br>
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 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 your events.It will be merged with the API level context option.
Default: null
enableMetaHeader boolean - If true, adds an header named 'x-elastic-client-meta', containing some minimal telemetry data,such as the client and platform version.
Default: true
cloud object - Custom configuration for connecting to Elastic Cloud. See Authentication for more details.
Default: null
Cloud configuration example:

js<br>const client = new Client({<br> cloud: {<br> id: '<cloud-id>'<br> },<br> auth: {<br> username: 'elastic',<br> password: 'changeme'<br> }<br>})<br>
disablePrototypePoisoningProtection boolean, 'proto', 'constructor' - The client can protect you against prototype poisoning attacks. Read this article to learn more about this security concern. 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. Read the secure-json-parse documentation to learn more.
Default: true
caFingerprint string - 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.
Default: null
maxResponseSize number - When configured, it verifies that the uncompressed response size is lower than the configured number, if it’s higher it will abort the request. It cannot be higher than buffer.constants.MAX_STRING_LENGTH
Default: null
maxCompressedResponseSize number - When configured, it verifies that the compressed response size is lower than the configured number, if it’s higher it will abort the request. It cannot be higher than buffer.constants.MAX_LENGTH
Default: null