elasticsearch-js/docs/basic-config.asciidoc

[[basic-config]]
=== Basic configuration

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


[source,js]
----
const { Client } = require('@elastic/elasticsearch')

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


[cols=2*]
|===
|`node` or `nodes`
a|The Elasticsearch endpoint to use. +
It can be a single string or an array of strings:
[source,js]
----
node: 'http://localhost:9200'
----
Or it can be an object (or an array of objects) that represents the node:
[source,js]
----
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
  }
}
----

|`auth`
a|Your authentication data. You can use both basic authentication and
{ref}/security-api-create-api-key.html[ApiKey]. +
See <<authentication,Authentication>> for more details. +
_Default:_ `null`

Basic authentication:
[source,js]
----
auth: {
  username: 'elastic',
  password: 'changeme'
}
----
{ref}/security-api-create-api-key.html[ApiKey] authentication:
[source,js]
----
auth: {
  apiKey: 'base64EncodedKey'
}
----
Bearer authentication, useful for https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-create-service-token.html[service account tokens]. Be aware that it does not handle automatic token refresh:
[source,js]
----
auth: {
  bearer: 'token'
}
----


|`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 https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how[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 https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how[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 https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how[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 https://nodejs.org/api/tls.html[configuraton]. +
_Default:_ `null`

|`proxy`
a|`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`
[source,js]
----
const client = new Client({
  node: 'http://localhost:9200',
  proxy: 'http://localhost:8080'
})

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

|`agent`
a|`http.AgentOptions, function` - http agent https://nodejs.org/api/http.html#http_new_agent_options[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`
[source,js]
----
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
})
----

|`nodeFilter`
a|`function` - Takes a `Connection` and returns `true` if it can be sent a request, otherwise `false`. +
_Default:_
[source,js]
----
() => true
----

|`nodeSelector`
a|`function` - custom selection strategy. +
_Options:_ `'round-robin'`, `'random'`, custom function +
_Default:_ `'round-robin'` +
_Custom function example:_
[source,js]
----
function nodeSelector (connections) {
  const index = calculateIndex()
  return connections[index]
}
----

|`generateRequestId`
a|`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:_
[source,js]
----
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 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`
a|`object` - Custom configuration for connecting to
https://cloud.elastic.co[Elastic Cloud]. See https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/auth-reference.html[Authentication]
for more details. +
_Default:_ `null` +
_Cloud configuration example:_
[source,js]
----
const client = new Client({
  cloud: {
    id: '<cloud-id>'
  },
  auth: {
    username: 'elastic',
    password: 'changeme'
  }
})
----

|`disablePrototypePoisoningProtection`
|`boolean`, `'proto'`, `'constructor'` - The client can protect you against prototype poisoning attacks. Read https://web.archive.org/web/20200319091159/https://hueniverse.com/square-brackets-are-the-enemy-ff5b9fd8a3e8?gi=184a27ee2a08[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` https://github.com/fastify/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`

|===