213 lines
7.9 KiB
Markdown
213 lines
7.9 KiB
Markdown
---
|
||
mapped_pages:
|
||
- https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/basic-config.html
|
||
---
|
||
|
||
# Basic configuration [basic-config]
|
||
|
||
This page shows you the possible basic configuration options that the clients offers.
|
||
|
||
```js
|
||
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
|
||
node: "http://localhost:9200";
|
||
```
|
||
|
||
Or it can be an object (or an array of objects) that represents the node:
|
||
|
||
```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` | Your authentication data. You can use both basic authentication and [ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key).
|
||
See [Authentication](/reference/connecting.md#authentication) for more details.
|
||
_Default:_ `null`
|
||
|
||
Basic authentication:
|
||
|
||
```js
|
||
auth: {
|
||
username: 'elastic',
|
||
password: 'changeme'
|
||
}
|
||
```
|
||
|
||
[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication:
|
||
|
||
```js
|
||
auth: {
|
||
apiKey: "base64EncodedKey";
|
||
}
|
||
```
|
||
|
||
Bearer authentication, useful for [service account tokens](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-service-token). Be aware that it does not handle automatic token refresh:
|
||
|
||
```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:_ 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](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) 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](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) 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](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) 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](https://nodejs.org/api/tls.md).
|
||
_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
|
||
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](https://nodejs.org/api/http.md#http_new_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
|
||
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` | `function` - Filters which node not to use for a request.
|
||
_Default:_
|
||
|
||
```js
|
||
() => true;
|
||
```
|
||
|
||
|
|
||
| `nodeSelector` | `function` - custom selection strategy.
|
||
_Options:_ `'round-robin'`, `'random'`, custom function
|
||
_Default:_ `'round-robin'`
|
||
_Custom function example:_
|
||
|
||
```js
|
||
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:_
|
||
|
||
```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 [`X-Opaque-Id` support](/reference/observability.md#_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](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details.
|
||
_Default:_ `null`
|
||
*Cloud configuration example:\*
|
||
|
||
```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 [this article](https://web.archive.org/web/20200319091159/https://hueniverse.com/square-brackets-are-the-enemy-ff5b9fd8a3e8?gi=184a27ee2a08) 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](https://github.com/fastify/secure-json-parse) 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` |
|