8.5 KiB
mapped_pages
| mapped_pages | |
|---|---|
|
Basic configuration [basic-config]
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
})
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'),
tls: 'tls options',
agent: 'http agent options',
id: 'custom node id',
headers: { 'custom': 'headers' },
roles: {
master: true,
data: true,
ingest: true,
ml: false
}
}
auth
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'
}
maxRetries
Type: number
Default: 3
Max number of retries for each request.
requestTimeout
Type: number
Default: No value
Max request timeout in milliseconds for each request.
pingTimeout
Type: number
Default: 3000
Max ping request timeout in milliseconds for each request.
sniffInterval
Type: number, boolean
Default: false
Perform a sniff operation every n milliseconds.
:::{tip}
Sniffing might not be the best solution. Before using the various sniff options, review this blog post.
:::
sniffOnStart
Type: boolean
Default: false
Perform a sniff once the client is started. Be sure to review the sniffing best practices blog post.
sniffEndpoint
Type: string
Default: '_nodes/_all/http'
Endpoint to ping during a sniff. Be sure to review the sniffing best practices blog post.
sniffOnConnectionFault
Type: boolean
Default: false
Perform a sniff on connection fault. Be sure to review the sniffing best practices blog post.
resurrectStrategy
Type: string
Default: 'ping'
Configure the node resurrection strategy.
Options: 'ping', 'optimistic', 'none'
suggestCompression
Type: boolean
Default: false
Adds an accept-encoding header to every request.
compression
Type: string, boolean
Default: false
Enables gzip request body compression.
Options: 'gzip', false
tls
Type: http.SecureContextOptions
Default: null
The tls configuraton.
proxy
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'
})
agent
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
})
nodeFilter
Type: function
Filter that indicates whether a node should be used for a request. Default function definition:
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
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]
}
generateRequestId
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'
}
name
Type: string, symbol
Default: elasticsearch-js
The name to identify the client instance in the events.
opaqueIdPrefix
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.
headers
Type: object
Default: {}
A set of custom headers to send in every request.
context
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.
enableMetaHeader
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.
cloud
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'
}
})
disablePrototypePoisoningProtection
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.
caFingerprint
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.
maxResponseSize
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.
maxCompressedResponseSize
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.