elasticsearch-js/docs/usage.asciidoc

[[client-usage]]
== Usage

Use the  client is pretty straightforward, it supports all the public APIs of Elasticsearch, and every method exposes the same signature.

[source,js]
----
const { Client } = require('@elastic/elasticsearch')
const client = new Client({ node: 'http://localhost:9200' })

// promise API
const result = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
})

// callback API
client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, (err, result) => {
  if (err) console.log(err)
})
----

The returned value of every API call is formed as follows:

[source,ts]
----
{
  body: object | boolean
  statusCode: number
  headers: object
  warnings: [string],
  meta: object
}
----

NOTE: The body will be a boolean value when using `HEAD` APIs.

The above value will be returned even if there is an error during the execution of the request, this means that you can safely use the https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment[destructuring assignment].

The `meta` key contains all the information regarding the request, such as attempt, options, and the connection that has been used.

[source,js]
----
// promise API
const { body } = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
})

// callback API
client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, (err, { body }) => {
  if (err) console.log(err)
})
----

=== Aborting a request

When using the callback style API, the function will also return an object that allows you to abort the API request.

[source,js]
----
// calback API
const request = client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
}, (err, { body }) => {
  if (err) console.log(err)
})

request.abort()
----

Aborting a request with the promise style API is not supported, but you can easily achieve that with convenience wrapper.

[source,js]
----
function abortableRequest (params, options) {
  var request = null
  const promise = new Promise((resolve, reject) => {
    request = client.search(params, options, (err, result) => {
      err ? reject(err) : resolve(res)
    })
  })
  return {
    promise,
    abort: () => request.abort()
  }
}

const request = abortableRequest({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
})

request.abort()
// access the promise with `request.promise.[method]`
----

=== Request specific options
If needed you can pass request specific options in a second object:
[source,js]
----
// promise API
const result = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
})

// calback API
client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
}, (err, { body }) => {
  if (err) console.log(err)
})
----

The supported request specific options are:
[cols=2*]
|===
|`ignore`
|`[number]` -  HTTP status codes which should not be considered errors for this request. +
_Default:_ `null`

|`requestTimeout`
|`number` - Max request timeout for the request, it overrides the client default. +
_Default:_ `30000`

|`maxRetries`
|`number` - Max number of retries for the request, it overrides the client default. +
_Default:_ `3`

|`compression`
|`string, boolean` - Enables body compression for the request. +
_Options:_ `false`, `'gzip'` +
_Default:_ `false`

|`asStream`
|`boolean` - Instead of getting the parsed body back, you will get the raw Node.js stream of data. +
_Default:_ `false`

|`headers`
|`object` - Custom headers for the request. +
_Default:_ `null`

|`querystring`
|`object` - Custom querystring for the request. +
_Default:_ `null`

|`id`
|`any` - Custom request id. _(overrides the top level request id generator)_ +
_Default:_ `null`

|`context`
|`any` - Custom object per request. _(you can use it to pass some data to the clients events)_ +
_Default:_ `null`
|===

=== Error handling
The client exposes a variety of error objects, that you can use to enhance your error handling. +
You can find all the error objects inside the `errors` key in the client.

[source,js]
----
const { errors } = require('@elastic/elasticsearch')
console.log(errors)
----

Following you can find the errors exported by the client.
[cols=2*]
|===
|`ElasticsearchClientErrors`
|Every error inherits from this class, it is the basic error generated by the client.

|`TimeoutError`
|Generated when a request exceeds the `requestTimeout` option.

|`ConnectionError`
|Generated when an error occurs during the reequest, it can be a connection error or a malformed stream of data.

|`NoLivingConnectionsError`
|Generated in case of all connections present in the connection pool are dead.

|`SerializationError`
|Generated if the serialization fails.

|`DeserializationError`
|Generated if the deserialization fails.

|`ConfigurationError`
|Generated if there is a malformed configuration or parameter.

|`ResponseError`
|Generated when in case of a `4xx` or `5xx` response.
|===