habsi/elasticsearch-js
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated docs indentation and added more examples

Browse Source
This commit is contained in:
delvedor
2019-02-13 07:51:39 +01:00
parent d4b2d4676b
commit 8cd8dd3410
4 changed files with 201 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
docs/breaking-changes.asciidoc
View File

@ -14,13 +14,43 @@ Every breaking change was carefully weighted, and every breaking change has soli
* There is no more an integrated logger. The client now is an event emitter that emits the following events: `request`, `response`, and `error`.
* The code is no longer shipped with all the versions of the API, but only the same major version of the package.
* The code is no longer shipped with all the versions of the API, but only the same major version of the package, this means that if you are using Elasticsearch `v6`, you will be required to install `@elasticelasticsearc@6`, and so on.
* The internals are completely different, so if you used to tweak a lot with them, you will need to refactor your code, while the surface API should be almost the same.
* No more browser support, for that will be built another module, `@elastic/elasticsearch-browser`. This module is intended for Node.js only.
* The returned value of an API call will no longer be the `body`, `statusCode`, and `headers` for callbacks and just the `body` for promises. The new returned value will be a unique object containing the `body`, `statusCode`, `headers`, and `warnings`, for both callback and promises. With the `asStream` parameter you can get the original HTTP response stream if the case you need to pipe it to another response for a forwarding use case.
* The returned value of an API call will no longer be the `body`, `statusCode`, and `headers` for callbacks and just the `body` for promises. The new returned value will be a unique object containing the `body`, `statusCode`, `headers`, and `warnings`, for both callback and promises. +
With the `asStream` parameter you can get the original HTTP response stream if the case you need to pipe it to another response for a forwarding use case.
[source,js]
----
// before
const body = await client.search({
index: 'my-index',
body: { foo: 'bar' }
})
client.search({
index: 'my-index',
body: { foo: 'bar' }
}, (err, body, statusCode, headers) => {
if (err) console.log(err)
})
// after
const { body, statusCode, headers, warnings } = await client.search({
index: 'my-index',
body: { foo: 'bar' }
})
client.search({
index: 'my-index',
body: { foo: 'bar' }
}, (err, { body, statusCode, headers, warnings }) => {
if (err) console.log(err)
})
----
* Errors: there is no longer a custom error class for every HTTP status code (such as `BadRequest` or `NotFound`), but there is a single `ResponseError` instead.
All the error classes have been renamed, and now all are suffixed with `Error` at the end. +
@ -37,9 +67,97 @@ Errors that has been renamed:
** `Serialization` => `SerializationError`
** `Serialization` => `DeserializationError`
* You must specify the port number in the configuration
* You must specify the port number in the configuration. In the previous version you can specifiy the host and port in a variety of ways, with the new client there is only one via the `node` parameter.
* The plugins option has been removed, if you want to extend the client now you should use the client.extend API.
There is a clear distinction between the API related parameters and the client related configurations, the parameters `ignore`, `headers`, `requestTimeout` and `maxRetries` are no longer part of the API object, and you should specify them in a second option object.
[source,js]
----
// before
const { Client } = require('elasticsearch')
const client = new Client({ plugins: [...] })
// after
const { Client } = require('@elastic/elasticsearch')
const client = new Client({ ... })
client.extend(...)
----
* There is a clear distinction between the API related parameters and the client related configurations, the parameters `ignore`, `headers`, `requestTimeout` and `maxRetries` are no longer part of the API object, and you should specify them in a second option object.
[source,js]
----
// before
const body = await client.search({
index: 'my-index',
body: { foo: 'bar' },
ignore: [404]
})
client.search({
index: 'my-index',
body: { foo: 'bar' },
ignore: [404]
}, (err, body, statusCode, headers) => {
if (err) console.log(err)
})
// after
const { body, statusCode, headers, warnings } = await client.search({
index: 'my-index',
body: { foo: 'bar' }
}, {
ignore: [404]
})
client.search({
index: 'my-index',
body: { foo: 'bar' }
}, {
ignore: [404]
}, (err, { body, statusCode, headers, warnings }) => {
if (err) console.log(err)
})
----
* The `transport.request` method will no longer accept the `query` key, but the `querystring` key instead (which can be a string or an object), furthermore, you need to send a bulk-like request, instead of the `body` key, you should use the `bulkBody` key. Also in this method, the client specific parameters should be passed as a second object.
[source,js]
----
// before
const body = await client.transport.request({
method: 'GET',
path: '/my-index/_search',
body: { foo: 'bar' },
query: { bar: 'baz' }
ignore: [404]
})
client.transport.request({
method: 'GET',
path: '/my-index/_search',
body: { foo: 'bar' },
query: { bar: 'baz' }
ignore: [404]
}, (err, body, statusCode, headers) => {
if (err) console.log(err)
})
// after
const { body, statusCode, headers, warnings } = await client.transport.request({
method: 'GET',
path: '/my-index/_search',
body: { foo: 'bar' },
querystring: { bar: 'baz' }
}, {
ignore: [404]
})
client.transport.request({
method: 'GET',
path: '/my-index/_search',
body: { foo: 'bar' },
querystring: { bar: 'baz' }
}, {
ignore: [404]
}, (err, { body, statusCode, headers, warnings }) => {
if (err) console.log(err)
})
----

68
docs/configuration.asciidoc
View File

@ -7,10 +7,10 @@ The client is designed to be easily configured as you see fit for your needs, fo
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
node: 'http://localhost:9200'
maxRetries: 5,
requestTimeout: 60000,
sniffOnStart: true
node: 'http://localhost:9200'
maxRetries: 5,
requestTimeout: 60000,
sniffOnStart: true
})
----
@ -28,17 +28,17 @@ 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
}
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
}
}
----
@ -138,9 +138,9 @@ This class is responsible to perform the request to Elasticsearch and handling e
const { Client, Transport } = require('@elastic/elasticsearch')
class MyTransport extends Transport {
request (params, options, callback) {
// your code
}
request (params, options, callback) {
// your code
}
}
const client = new Client({
@ -152,10 +152,10 @@ Sometimes you just need to inject a little snippet of your code and then continu
[source,js]
----
class MyTransport extends Transport {
request (params, options, callback) {
// your code
super.request(params, options, callback)
}
request (params, options, callback) {
// your code
super.request(params, options, callback)
}
}
----
@ -167,10 +167,10 @@ Moreover, the connection pool will handle the resurrection strategies and the up
const { Client, ConnectionPool } = require('@elastic/elasticsearch')
class MyConnectionPool extends ConnectionPool {
markAlive (connection) {
// your code
super.markAlive(connection)
}
markAlive (connection) {
// your code
super.markAlive(connection)
}
}
const client = new Client({
@ -185,13 +185,13 @@ This class represents a single Node, it holds every information we have on the n
const { Client, Connection } = require('@elastic/elasticsearch')
class MyConnection extends Connection {
request (params, callback) {
// your code
}
request (params, callback) {
// your code
}
}
const client = new Client({
Connection: MyConnection
Connection: MyConnection
})
----
@ -208,12 +208,12 @@ This class is responsible of the serialization of every request, it offers the f
const { Client, Serializer } = require('@elastic/elasticsearch')
class MySerializer extends Serializer {
serialize (object) {
// your code
}
serialize (object) {
// your code
}
}
const client = new Client({
Serializer: MySerializer
Serializer: MySerializer
})
----

72
docs/extend.asciidoc
View File

@ -11,50 +11,50 @@ const { Client } = require('@elastic/elasticsearch')
const client = new Client({ node: 'http://localhost:9200' })
client.extend('supersearch', ({ makeRequest, ConfigurationError }) => {
return function supersearch (params, options) {
const {
body,
index,
method,
...querystring
} = params
return function supersearch (params, options) {
const {
body,
index,
method,
...querystring
} = params
// params validation
if (body == null) {
throw new ConfigurationError('Missing required parameter: body')
}
// build request object
const request = {
method: method || 'POST',
path: `/${encodeURIComponent(index)}/_search_`,
body,
querystring
}
// build request options object
const requestOptions = {
ignore: options.ignore || null,
requestTimeout: options.requestTimeout || null,
maxRetries: options.maxRetries || null,
asStream: options.asStream || false,
headers: options.headers || null
}
return makeRequest(request, requestOptions)
// params validation
if (body == null) {
throw new ConfigurationError('Missing required parameter: body')
}
// build request object
const request = {
method: method || 'POST',
path: `/${encodeURIComponent(index)}/_search_`,
body,
querystring
}
// build request options object
const requestOptions = {
ignore: options.ignore || null,
requestTimeout: options.requestTimeout || null,
maxRetries: options.maxRetries || null,
asStream: options.asStream || false,
headers: options.headers || null
}
return makeRequest(request, requestOptions)
}
})
client.extend('utility.index', ({ makeRequest }) => {
return function _index (params, options) {
// your code
}
return function _index (params, options) {
// your code
}
})
client.extend('utility.delete', ({ makeRequest }) => {
return function _delete (params, options) {
// your code
}
return function _delete (params, options) {
// your code
}
})
client.supersearch(...)

18
docs/usage.asciidoc
View File

@ -162,7 +162,7 @@ a|Emitted before to send the actual request to Elasticsearch.
[source,js]
----
client.on('request', (err, meta) => {
console.log(err, meta)
console.log(err, meta)
})
----
`meta` is an object that contains the following informations:
@ -178,7 +178,7 @@ a|Emitted before to send the actual request to Elasticsearch.
[source,js]
----
client.on('response', (err, meta) => {
console.log(err, meta)
console.log(err, meta)
})
----
`meta` is an object that contains the following informations:
@ -194,7 +194,7 @@ a|Emitted before to send the actual request to Elasticsearch.
[source,js]
----
client.on('sniff', (err, meta) => {
console.log(err, meta)
console.log(err, meta)
})
----
`meta` is an object that contains the following informations:
@ -207,7 +207,7 @@ a|Emitted before to send the actual request to Elasticsearch.
[source,js]
----
client.on('resurrect', (err, meta) => {
console.log(err, meta)
console.log(err, meta)
})
----
`meta` is an object that contains the following informations:
@ -227,10 +227,10 @@ const { Client } = require('@elastic/elasticsearch')
const client = new Client({ node: 'http://localhost:9200' })
client.on('response', (err, meta) => {
if (err) {
logger.error(err)
} else {
logger.info(meta)
}
if (err) {
logger.error(err)
} else {
logger.info(meta)
}
})
----