elasticsearch-js/docs/usage.asciidoc

[[client-usage]]
== Usage

Using the client is straightforward, it supports all the public APIs of {es}, 
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 is a boolean value when you use `HEAD` APIs.

The above value is 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 about 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 also returns 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 
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 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 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)
----


You can find the errors exported by the client in the table below.

[cols=2*]
|===
|`ElasticsearchClientError`
|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 request, it can be a connection error or a malformed stream of data.

|`NoLivingConnectionsError`
|Given the configuration, the ConnectionPool was not able to find a usable Connection for this request.

|`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.
|===