[DOCS] Adds Configuration section to Node.JS docs (#1391)
This commit is contained in:
István Zoltán Szabó
committed by
GitHub
GitHub
parent
618b244473
commit
883ef386e3
120
docs/advanced-config.asciidoc
Normal file
120
docs/advanced-config.asciidoc
Normal file
@ -0,0 +1,120 @@
|
|||||||
|
[[advanced-config]]
|
||||||
|
=== Advanced configuration
|
||||||
|
|
||||||
|
If you need to customize the client behavior heavily, you are in the right
|
||||||
|
place! The client enables you to customize the following internals:
|
||||||
|
|
||||||
|
* `Transport` class
|
||||||
|
* `ConnectionPool` class
|
||||||
|
* `Connection` class
|
||||||
|
* `Serializer` class
|
||||||
|
|
||||||
|
|
||||||
|
[discrete]
|
||||||
|
==== `Transport`
|
||||||
|
|
||||||
|
This class is responsible for performing the request to {es} and handling
|
||||||
|
errors, it also handles the sniffing.
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
----
|
||||||
|
const { Client, Transport } = require('@elastic/elasticsearch')
|
||||||
|
|
||||||
|
class MyTransport extends Transport {
|
||||||
|
request (params, options, callback) {
|
||||||
|
// your code
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const client = new Client({
|
||||||
|
Transport: MyTransport
|
||||||
|
})
|
||||||
|
----
|
||||||
|
|
||||||
|
Sometimes you need to inject a small snippet of your code and then continue to
|
||||||
|
use the usual client code. In such cases, call `super.method`:
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
----
|
||||||
|
class MyTransport extends Transport {
|
||||||
|
request (params, options, callback) {
|
||||||
|
// your code
|
||||||
|
return super.request(params, options, callback)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
----
|
||||||
|
|
||||||
|
|
||||||
|
[discrete]
|
||||||
|
==== `ConnectionPool`
|
||||||
|
|
||||||
|
This class is responsible for keeping in memory all the {es} Connection that you
|
||||||
|
are using. There is a single Connection for every node. The connection pool
|
||||||
|
handles the resurrection strategies and the updates of the pool.
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
----
|
||||||
|
const { Client, ConnectionPool } = require('@elastic/elasticsearch')
|
||||||
|
|
||||||
|
class MyConnectionPool extends ConnectionPool {
|
||||||
|
markAlive (connection) {
|
||||||
|
// your code
|
||||||
|
super.markAlive(connection)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const client = new Client({
|
||||||
|
ConnectionPool: MyConnectionPool
|
||||||
|
})
|
||||||
|
----
|
||||||
|
|
||||||
|
|
||||||
|
[discrete]
|
||||||
|
==== `Connection`
|
||||||
|
|
||||||
|
This class represents a single node, it holds every information we have on the
|
||||||
|
node, such as roles, id, URL, custom headers and so on. The actual HTTP request
|
||||||
|
is performed here, this means that if you want to swap the default HTTP client
|
||||||
|
(Node.js core), you should override the `request` method of this class.
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
----
|
||||||
|
const { Client, Connection } = require('@elastic/elasticsearch')
|
||||||
|
|
||||||
|
class MyConnection extends Connection {
|
||||||
|
request (params, callback) {
|
||||||
|
// your code
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const client = new Client({
|
||||||
|
Connection: MyConnection
|
||||||
|
})
|
||||||
|
----
|
||||||
|
|
||||||
|
|
||||||
|
[discrete]
|
||||||
|
==== `Serializer`
|
||||||
|
|
||||||
|
This class is responsible for the serialization of every request, it offers the
|
||||||
|
following methods:
|
||||||
|
|
||||||
|
* `serialize(object: any): string;` serializes request objects.
|
||||||
|
* `deserialize(json: string): any;` deserializes response strings.
|
||||||
|
* `ndserialize(array: any[]): string;` serializes bulk request objects.
|
||||||
|
* `qserialize(object: any): string;` serializes request query parameters.
|
||||||
|
|
||||||
|
[source,js]
|
||||||
|
----
|
||||||
|
const { Client, Serializer } = require('@elastic/elasticsearch')
|
||||||
|
|
||||||
|
class MySerializer extends Serializer {
|
||||||
|
serialize (object) {
|
||||||
|
// your code
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const client = new Client({
|
||||||
|
Serializer: MySerializer
|
||||||
|
})
|
||||||
|
----
|
||||||
247
docs/basic-config.asciidoc
Normal file
247
docs/basic-config.asciidoc
Normal file
@ -0,0 +1,247 @@
|
|||||||
|
[[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({
|
||||||
|
node: 'http://localhost:9200',
|
||||||
|
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'),
|
||||||
|
ssl: 'ssl 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 https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/auth-reference.html[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'
|
||||||
|
}
|
||||||
|
----
|
||||||
|
|
||||||
|
|
||||||
|
|`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`
|
||||||
|
|
||||||
|
|`ssl`
|
||||||
|
|`http.SecureContextOptions` - ssl 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` - Filters which node not to use for a request. +
|
||||||
|
_Default:_
|
||||||
|
[source,js]
|
||||||
|
----
|
||||||
|
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`
|
||||||
|
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: 'name:bG9jYWxob3N0JGFiY2QkZWZnaA=='
|
||||||
|
},
|
||||||
|
auth: {
|
||||||
|
username: 'elastic',
|
||||||
|
password: 'changeme'
|
||||||
|
}
|
||||||
|
})
|
||||||
|
----
|
||||||
|
|
||||||
|
|===
|
||||||
@ -1,5 +1,5 @@
|
|||||||
[[child-client]]
|
[[child]]
|
||||||
== Creating a child client
|
=== Creating a child client
|
||||||
|
|
||||||
There are some use cases where you may need multiple instances of the client.
|
There are some use cases where you may need multiple instances of the client.
|
||||||
You can easily do that by calling `new Client()` as many times as you need, but
|
You can easily do that by calling `new Client()` as many times as you need, but
|
||||||
|
|||||||
@ -1,371 +1,11 @@
|
|||||||
[[client-configuration]]
|
[[client-configuration]]
|
||||||
== Client configuration
|
== Configuration
|
||||||
|
|
||||||
|
|
||||||
The client is designed to be easily configured for your needs. In the following
|
The client is designed to be easily configured for your needs. In the following
|
||||||
section, you can see the possible basic options that you can use to configure
|
section, you can see the possible options that you can use to configure it.
|
||||||
it.
|
|
||||||
|
|
||||||
[source,js]
|
* <<basic-config>>
|
||||||
----
|
* <<advanced-config>>
|
||||||
const { Client } = require('@elastic/elasticsearch')
|
* <<child>>
|
||||||
|
* <<extend>>
|
||||||
const client = new Client({
|
|
||||||
node: 'http://localhost:9200',
|
|
||||||
maxRetries: 5,
|
|
||||||
requestTimeout: 60000,
|
|
||||||
sniffOnStart: true
|
|
||||||
})
|
|
||||||
----
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
=== Basic options
|
|
||||||
|
|
||||||
[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'),
|
|
||||||
ssl: 'ssl 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 https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/auth-reference.html[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'
|
|
||||||
}
|
|
||||||
----
|
|
||||||
|
|
||||||
|
|
||||||
|`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`
|
|
||||||
|
|
||||||
|`ssl`
|
|
||||||
|`http.SecureContextOptions` - ssl 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` - Filters which node not to use for a request. +
|
|
||||||
_Default:_
|
|
||||||
[source,js]
|
|
||||||
----
|
|
||||||
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`
|
|
||||||
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: 'name:bG9jYWxob3N0JGFiY2QkZWZnaA=='
|
|
||||||
},
|
|
||||||
auth: {
|
|
||||||
username: 'elastic',
|
|
||||||
password: 'changeme'
|
|
||||||
}
|
|
||||||
})
|
|
||||||
----
|
|
||||||
|
|
||||||
|===
|
|
||||||
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
=== Advanced configuration
|
|
||||||
|
|
||||||
If you need to customize the client behavior heavily, you are in the right
|
|
||||||
place! The client allows you to customize the following internals:
|
|
||||||
|
|
||||||
* `Transport` class
|
|
||||||
* `ConnectionPool` class
|
|
||||||
* `Connection` class
|
|
||||||
* `Serializer` class
|
|
||||||
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
=== `Transport`
|
|
||||||
|
|
||||||
This class is responsible for performing the request to {es} and handling
|
|
||||||
errors, it also handles the sniffing.
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
----
|
|
||||||
const { Client, Transport } = require('@elastic/elasticsearch')
|
|
||||||
|
|
||||||
class MyTransport extends Transport {
|
|
||||||
request (params, options, callback) {
|
|
||||||
// your code
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const client = new Client({
|
|
||||||
Transport: MyTransport
|
|
||||||
})
|
|
||||||
----
|
|
||||||
|
|
||||||
Sometimes you need to inject a small snippet of your code and then continue to
|
|
||||||
use the usual client code. In such cases, call `super.method`:
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
----
|
|
||||||
class MyTransport extends Transport {
|
|
||||||
request (params, options, callback) {
|
|
||||||
// your code
|
|
||||||
return super.request(params, options, callback)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
----
|
|
||||||
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
=== `ConnectionPool`
|
|
||||||
|
|
||||||
This class is responsible for keeping in memory all the {es} Connection that we
|
|
||||||
are using. There is a single Connection for every node. The connection pool
|
|
||||||
handles the resurrection strategies and the updates of the pool.
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
----
|
|
||||||
const { Client, ConnectionPool } = require('@elastic/elasticsearch')
|
|
||||||
|
|
||||||
class MyConnectionPool extends ConnectionPool {
|
|
||||||
markAlive (connection) {
|
|
||||||
// your code
|
|
||||||
super.markAlive(connection)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const client = new Client({
|
|
||||||
ConnectionPool: MyConnectionPool
|
|
||||||
})
|
|
||||||
----
|
|
||||||
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
=== `Connection`
|
|
||||||
|
|
||||||
This class represents a single node, it holds every information we have on the
|
|
||||||
node, such as roles, id, URL, custom headers and so on. The actual HTTP request
|
|
||||||
is performed here, this means that if you want to swap the default HTTP client
|
|
||||||
(Node.js core), you should override the `request` method of this class.
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
----
|
|
||||||
const { Client, Connection } = require('@elastic/elasticsearch')
|
|
||||||
|
|
||||||
class MyConnection extends Connection {
|
|
||||||
request (params, callback) {
|
|
||||||
// your code
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const client = new Client({
|
|
||||||
Connection: MyConnection
|
|
||||||
})
|
|
||||||
----
|
|
||||||
|
|
||||||
|
|
||||||
[discrete]
|
|
||||||
=== `Serializer`
|
|
||||||
|
|
||||||
This class is responsible for the serialization of every request, it offers the
|
|
||||||
following methods:
|
|
||||||
|
|
||||||
* `serialize(object: any): string;` serializes request objects.
|
|
||||||
* `deserialize(json: string): any;` deserializes response strings.
|
|
||||||
* `ndserialize(array: any[]): string;` serializes bulk request objects.
|
|
||||||
* `qserialize(object: any): string;` serializes request query parameters.
|
|
||||||
|
|
||||||
[source,js]
|
|
||||||
----
|
|
||||||
const { Client, Serializer } = require('@elastic/elasticsearch')
|
|
||||||
|
|
||||||
class MySerializer extends Serializer {
|
|
||||||
serialize (object) {
|
|
||||||
// your code
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
const client = new Client({
|
|
||||||
Serializer: MySerializer
|
|
||||||
})
|
|
||||||
----
|
|
||||||
|
|||||||
@ -1,5 +1,5 @@
|
|||||||
[[extend-client]]
|
[[extend]]
|
||||||
== Extend the client
|
=== Extend the client
|
||||||
|
|
||||||
Sometimes you need to reuse the same logic, or you want to build a custom API to
|
Sometimes you need to reuse the same logic, or you want to build a custom API to
|
||||||
allow you simplify your code. The easiest way to achieve that is by extending
|
allow you simplify your code. The easiest way to achieve that is by extending
|
||||||
|
|||||||
@ -7,11 +7,13 @@ include::introduction.asciidoc[]
|
|||||||
include::installation.asciidoc[]
|
include::installation.asciidoc[]
|
||||||
include::connecting.asciidoc[]
|
include::connecting.asciidoc[]
|
||||||
include::configuration.asciidoc[]
|
include::configuration.asciidoc[]
|
||||||
|
include::basic-config.asciidoc[]
|
||||||
|
include::advanced-config.asciidoc[]
|
||||||
|
include::child.asciidoc[]
|
||||||
|
include::extend.asciidoc[]
|
||||||
include::reference.asciidoc[]
|
include::reference.asciidoc[]
|
||||||
include::breaking-changes.asciidoc[]
|
include::breaking-changes.asciidoc[]
|
||||||
include::observability.asciidoc[]
|
include::observability.asciidoc[]
|
||||||
include::child.asciidoc[]
|
|
||||||
include::extend.asciidoc[]
|
|
||||||
include::helpers.asciidoc[]
|
include::helpers.asciidoc[]
|
||||||
include::typescript.asciidoc[]
|
include::typescript.asciidoc[]
|
||||||
include::testing.asciidoc[]
|
include::testing.asciidoc[]
|
||||||
|
|||||||
Reference in New Issue
Block a user