Update docs for v8 (#1572)

elastic · Feb 11, 2022 · 5086a19 · 5086a19
1 parent 221f9a9
commit 5086a19
Show file tree

Hide file tree

Showing 37 changed files with 311 additions and 1,260 deletions.
diff --git a/README.md b/README.md
@@ -51,6 +51,7 @@ of `^7.10.0`).
 | --------------- |------------------| ---------------------- |
 | `8.x`           | `December 2019`  | `7.11` (early 2021)    |
 | `10.x`          | `April 2021`      | `7.12` (mid 2021)     |
+| `12.x`          | `April 2022`      | `8.2` (early 2022)     |
 
 ### Compatibility
 
@@ -59,7 +60,7 @@ Elasticsearch language clients are only backwards compatible with default distri
 
 | Elasticsearch Version | Client Version |
 | --------------------- |----------------|
-| `master`              | `master`       |
+| `8.x`                 | `8.x`          |
 | `7.x`                 | `7.x`          |
 | `6.x`                 | `6.x`          |
 | `5.x`                 | `5.x`          |
@@ -80,60 +81,16 @@ We recommend that you write a lightweight proxy that uses this client instead, y
 - [Usage](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-connecting.html#client-usage)
 - [Client configuration](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-configuration.html)
 - [API reference](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference.html)
-- [Breaking changes coming from the old client](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/breaking-changes.html)
 - [Authentication](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-connecting.html#authentication)
 - [Observability](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/observability.html)
 - [Creating a child client](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/child.html)
-- [Extend the client](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/extend.html)
 - [Client helpers](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-helpers.html)
 - [Typescript support](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/typescript.html)
 - [Testing](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-testing.html)
 - [Examples](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/examples.html)
 
 ## Quick start
 
-First of all, require the client and initialize it:
-```js
-const { Client } = require('@elastic/elasticsearch')
-const client = new Client({ node: 'http://localhost:9200' })
-```
-
-You can use both the callback-style API and the promise-style API, both behave the same way.
-```js
-// promise API
-const result = await client.search({
-  index: 'my-index',
-  body: {
-    query: {
-      match: { hello: 'world' }
-    }
-  }
-})
-
-// callback API
-client.search({
-  index: 'my-index',
-  body: {
-    query: {
-      match: { hello: 'world' }
-    }
-  }
-}, (err, result) => {
-  if (err) console.log(err)
-})
-```
-The returned value of **every** API call is formed as follows:
-```ts
-{
-  body: object | boolean
-  statusCode: number
-  headers: object
-  warnings: [string]
-  meta: object
-}
-```
-
-Let's see a complete example!
 ```js
 'use strict'
 
@@ -144,26 +101,23 @@ async function run () {
   // Let's start by indexing some data
   await client.index({
     index: 'game-of-thrones',
-    // type: '_doc', // uncomment this line if you are using Elasticsearch ≤ 6
-    body: {
+    document: {
       character: 'Ned Stark',
       quote: 'Winter is coming.'
     }
   })
 
   await client.index({
     index: 'game-of-thrones',
-    // type: '_doc', // uncomment this line if you are using Elasticsearch ≤ 6
-    body: {
+    document: {
       character: 'Daenerys Targaryen',
       quote: 'I am the blood of the dragon.'
     }
   })
 
   await client.index({
     index: 'game-of-thrones',
-    // type: '_doc', // uncomment this line if you are using Elasticsearch ≤ 6
-    body: {
+    document: {
       character: 'Tyrion Lannister',
       quote: 'A mind needs books like a sword needs a whetstone.'
     }
@@ -174,17 +128,14 @@ async function run () {
   await client.indices.refresh({ index: 'game-of-thrones' })
 
   // Let's search!
-  const { body } = await client.search({
+  const result= await client.search({
     index: 'game-of-thrones',
-    // type: '_doc', // uncomment this line if you are using Elasticsearch ≤ 6
-    body: {
-      query: {
-        match: { quote: 'winter' }
-      }
+    query: {
+      match: { quote: 'winter' }
     }
   })
 
-  console.log(body.hits.hits)
+  console.log(result.hits.hits)
 }
 
 run().catch(console.log)
@@ -217,13 +168,13 @@ const { Client: Client7 } = require('es7')
 const client6 = new Client6({ node: 'http://localhost:9200' })
 const client7 = new Client7({ node: 'http://localhost:9201' })
 
-client6.info(console.log)
-client7.info(console.log)
+client6.info().then(console.log, console.log)
+client7.info().then(console.log, console.log)
 ```
 
-Finally, if you want to install the client for the next version of Elasticsearch *(the one that lives in Elasticsearch’s master branch)*, you can use the following command:
+Finally, if you want to install the client for the next version of Elasticsearch *(the one that lives in Elasticsearch’s main branch)*, you can use the following command:
 ```sh
-npm install esmaster@github:elastic/elasticsearch-js
+npm install esmain@github:elastic/elasticsearch-js
 ```
 
 ## License

diff --git a/docs/advanced-config.asciidoc b/docs/advanced-config.asciidoc
@@ -45,9 +45,9 @@ is performed here, this means that if you want to swap the default HTTP client
 
 [source,js]
 ----
-const { Client, Connection } = require('@elastic/elasticsearch')
+const { Client, BaseConnection } = require('@elastic/elasticsearch')
 
-class MyConnection extends Connection {
+class MyConnection extends BaseConnection {
   request (params, callback) {
     // your code
   }

diff --git a/docs/basic-config.asciidoc b/docs/basic-config.asciidoc
@@ -32,7 +32,7 @@ Or it can be an object (or an array of objects) that represents the node:
 ----
 node: {
   url: new URL('http://localhost:9200'),
-  ssl: 'ssl options',
+  tls: 'tls options',
   agent: 'http agent options',
   id: 'custom node id',
   headers: { 'custom': 'headers' }
@@ -118,8 +118,8 @@ _Default:_ `false`
 _Options:_ `'gzip'`, `false` +
 _Default:_ `false`
 
-|`ssl`
-|`http.SecureContextOptions` - ssl https://nodejs.org/api/tls.html[configuraton]. +
+|`tls`
+|`http.SecureContextOptions` - tls https://nodejs.org/api/tls.html[configuraton]. +
 _Default:_ `null`
 
 |`proxy`
@@ -267,24 +267,4 @@ _Default:_ `null`
 |`number` - When configured, it verifies that the compressed response size is lower than the configured number, if it's higher it will abort the request. It cannot be higher than buffer.constants.MAX_LENTGH +
 _Default:_ `null`
 
-|===
-
-[discrete]
-==== Performances considerations
-
-By default, the client will protection you against prototype poisoning attacks.
-Read https://web.archive.org/web/20200319091159/https://hueniverse.com/square-brackets-are-the-enemy-ff5b9fd8a3e8?gi=184a27ee2a08[this article] to learn more.
-If needed you can disable prototype poisoning protection entirely or one of the two checks.
-Read the `secure-json-parse` https://github.com/fastify/secure-json-parse[documentation] to learn more.
-
-While it's good to be safe, you should know that security always comes with a cost.
-With big enough payloads, this security check could causea drop in the overall performances,
-which might be a problem for your application.
-If you know you can trust the data stored in Elasticsearch, you can safely disable this check.
-
-[source,js]
-----
-const client = new Client({
-  disablePrototypePoisoningProtection: true
-})
-----
+|===