[DOCS] Reorganizes Introduction and Installation chapters (#1315)
This commit is contained in:
István Zoltán Szabó
committed by
GitHub
GitHub
parent
7b11152a12
commit
88ef53b0ef
@ -5,6 +5,7 @@ This document contains code snippets to show you how to connect to various {es}
|
||||
providers.
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Elastic Cloud
|
||||
|
||||
If you are using https://www.elastic.co/cloud[Elastic Cloud], the client offers
|
||||
@ -38,6 +39,7 @@ const client = new Client({
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Basic authentication
|
||||
|
||||
You can provide your credentials by passing the `username` and `password`
|
||||
@ -69,6 +71,7 @@ const client = new Client({
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== ApiKey authentication
|
||||
|
||||
You can use the
|
||||
@ -106,6 +109,7 @@ const client = new Client({
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== SSL configuration
|
||||
|
||||
Without any additional configuration you can specify `https://` node urls, and
|
||||
|
||||
@ -6,6 +6,7 @@ to install with `npm install elasticsearch` – you will encounter some breaking
|
||||
changes.
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Don’t panic!
|
||||
|
||||
Every breaking change was carefully weighed, and each is justified. Furthermore,
|
||||
@ -13,6 +14,7 @@ the new codebase has been rewritten with modern JavaScript and has been
|
||||
carefully designed to be easy to maintain.
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Breaking changes
|
||||
|
||||
* Minimum supported version of Node.js is `v8`.
|
||||
@ -209,6 +211,7 @@ client.transport.request({
|
||||
})
|
||||
----
|
||||
|
||||
[discrete]
|
||||
=== Talk is cheap. Show me the code.
|
||||
|
||||
You can find a code snippet with the old client below followed by the same code
|
||||
|
||||
@ -17,7 +17,7 @@ const client = new Client({
|
||||
})
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Basic options
|
||||
|
||||
[cols=2*]
|
||||
@ -242,6 +242,7 @@ const client = new Client({
|
||||
|===
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Advanced configuration
|
||||
|
||||
If you need to customize the client behavior heavily, you are in the right
|
||||
@ -253,6 +254,7 @@ place! The client allows you to customize the following internals:
|
||||
* `Serializer` class
|
||||
|
||||
|
||||
[discrete]
|
||||
=== `Transport`
|
||||
|
||||
This class is responsible for performing the request to {es} and handling
|
||||
@ -287,6 +289,7 @@ class MyTransport extends Transport {
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== `ConnectionPool`
|
||||
|
||||
This class is responsible for keeping in memory all the {es} Connection that we
|
||||
@ -310,6 +313,7 @@ const client = new Client({
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== `Connection`
|
||||
|
||||
This class represents a single node, it holds every information we have on the
|
||||
@ -333,6 +337,7 @@ const client = new Client({
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== `Serializer`
|
||||
|
||||
This class is responsible for the serialization of every request, it offers the
|
||||
|
||||
@ -6,12 +6,16 @@ The client comes with an handy collection of helpers to give you a more comforta
|
||||
CAUTION: The client helpers are experimental, and the API may change in the next minor releases.
|
||||
The helpers will not work in any Node.js version lower than 10.
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Bulk Helper
|
||||
|
||||
~Added~ ~in~ ~`v7.7.0`~
|
||||
|
||||
Running Bulk requests can be complex due to the shape of the API, this helper aims to provide a nicer developer experience around the Bulk API.
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Usage
|
||||
[source,js]
|
||||
----
|
||||
@ -150,8 +154,12 @@ const b = client.helpers.bulk({
|
||||
|
||||
|===
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Supported operations
|
||||
|
||||
|
||||
[discrete]
|
||||
===== Index
|
||||
[source,js]
|
||||
----
|
||||
@ -165,6 +173,8 @@ client.helpers.bulk({
|
||||
})
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
===== Create
|
||||
[source,js]
|
||||
----
|
||||
@ -178,7 +188,10 @@ client.helpers.bulk({
|
||||
})
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
===== Update
|
||||
|
||||
[source,js]
|
||||
----
|
||||
client.helpers.bulk({
|
||||
@ -195,7 +208,10 @@ client.helpers.bulk({
|
||||
})
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
===== Delete
|
||||
|
||||
[source,js]
|
||||
----
|
||||
client.helpers.bulk({
|
||||
@ -208,7 +224,10 @@ client.helpers.bulk({
|
||||
})
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Abort a bulk operation
|
||||
|
||||
If needed, you can abort a bulk operation at any time. The bulk helper returns a https://promisesaplus.com/[thenable], which has an `abort` method.
|
||||
|
||||
NOTE: The abort method will stop the execution of the bulk operation, but if you are using a concurrency higher than one, the operations that are already running will not be stopped.
|
||||
@ -235,7 +254,10 @@ const b = client.helpers.bulk({
|
||||
console.log(await b)
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Passing custom options to the Bulk API
|
||||
|
||||
You can pass any option supported by the link:{ref}/docs-bulk.html#docs-bulk-api-query-params[Bulk API] to the helper, and the helper will use those options in conjuction with the Bulk
|
||||
API call.
|
||||
|
||||
@ -252,6 +274,8 @@ const result = await client.helpers.bulk({
|
||||
})
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Usage with an async generator
|
||||
|
||||
[source,js]
|
||||
@ -282,6 +306,8 @@ const result = await client.helpers.bulk({
|
||||
console.log(result)
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Multi Search Helper
|
||||
|
||||
~Added~ ~in~ ~`v7.8.0`~
|
||||
@ -290,7 +316,10 @@ If you are sending search request at a high rate, this helper might be useful fo
|
||||
It will use the mutli search API under the hood to batch the requests and improve the overall performances of your application. +
|
||||
The `result` exposes a `documents` property as well, which allows you to access directly the hits sources.
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Usage
|
||||
|
||||
[source,js]
|
||||
----
|
||||
const { Client } = require('@elastic/elasticsearch')
|
||||
@ -372,7 +401,10 @@ const m = client.helpers.msearch({
|
||||
|
||||
|===
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Stopping the Msearch Helper
|
||||
|
||||
If needed, you can stop a msearch processor at any time. The msearch helper returns a https://promisesaplus.com/[thenable], which has an `stop` method.
|
||||
|
||||
If you are creating multiple msearch helpers instances and using them for a limitied period of time, remember to always use the `stop` method once you have finished using them, otherwise your application will start leaking memory.
|
||||
@ -405,6 +437,8 @@ m.search(
|
||||
setImmediate(() => m.stop())
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Search Helper
|
||||
|
||||
~Added~ ~in~ ~`v7.7.0`~
|
||||
@ -430,6 +464,8 @@ for (const doc of documents) {
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Scroll Search Helper
|
||||
|
||||
~Added~ ~in~ ~`v7.7.0`~
|
||||
@ -455,6 +491,8 @@ for await (const result of scrollSearch) {
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Clear a scroll search
|
||||
|
||||
If needed, you can clear a scroll search by calling `result.clear()`:
|
||||
@ -468,6 +506,8 @@ for await (const result of scrollSearch) {
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Quickly getting the documents
|
||||
|
||||
If you only need the documents from the result of a scroll search, you can access them via `result.documents`:
|
||||
@ -479,6 +519,8 @@ for await (const result of scrollSearch) {
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Scroll Documents Helper
|
||||
|
||||
~Added~ ~in~ ~`v7.7.0`~
|
||||
|
||||
@ -4,6 +4,7 @@
|
||||
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
|
||||
|
||||
include::introduction.asciidoc[]
|
||||
include::installation.asciidoc[]
|
||||
include::usage.asciidoc[]
|
||||
include::configuration.asciidoc[]
|
||||
include::reference.asciidoc[]
|
||||
|
||||
21
docs/installation.asciidoc
Normal file
21
docs/installation.asciidoc
Normal file
@ -0,0 +1,21 @@
|
||||
[[installation]]
|
||||
== Installation
|
||||
|
||||
This page guides you through the installation process of the client.
|
||||
|
||||
To install the latest version of the client, run the following command:
|
||||
|
||||
[source,sh]
|
||||
----
|
||||
npm install @elastic/elasticsearch
|
||||
----
|
||||
|
||||
To install a specific major version of the client, run the following command:
|
||||
|
||||
[source,sh]
|
||||
----
|
||||
npm install @elastic/elasticsearch@<major>
|
||||
----
|
||||
|
||||
To learn more about the supported major versions, please refer to the
|
||||
<<js-compatibility-matrix>>.
|
||||
@ -1,9 +1,11 @@
|
||||
[[introduction]]
|
||||
== Introduction
|
||||
|
||||
The official Node.js client for {es}.
|
||||
This is the official Node.js client for {es}. This page gives a quick overview
|
||||
about the features of the client.
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Features
|
||||
|
||||
* One-to-one mapping with REST API.
|
||||
@ -15,15 +17,9 @@ The official Node.js client for {es}.
|
||||
* TypeScript support out of the box.
|
||||
|
||||
|
||||
=== Install
|
||||
|
||||
[source,sh]
|
||||
----
|
||||
npm install @elastic/elasticsearch
|
||||
----
|
||||
|
||||
|
||||
=== Compatibility
|
||||
[discrete]
|
||||
[[js-compatibility-matrix]]
|
||||
=== Compatibility matrix
|
||||
|
||||
The minimum supported version of Node.js is `v8`.
|
||||
|
||||
@ -50,13 +46,8 @@ using.
|
||||
|`5.x`
|
||||
|===
|
||||
|
||||
To install a specific major version of the client, run the following command:
|
||||
|
||||
----
|
||||
npm install @elastic/elasticsearch@<major>
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Browser
|
||||
|
||||
WARNING: There is no official support for the browser environment. It exposes
|
||||
@ -64,6 +55,7 @@ your {es} instance to everyone, which could lead to security issues. We
|
||||
recommend you to write a lightweight proxy that uses this client instead.
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Quick start
|
||||
|
||||
First of all, require, then initialize the client:
|
||||
@ -176,7 +168,7 @@ async function run () {
|
||||
run().catch(console.log)
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Install multiple versions
|
||||
|
||||
If you are using multiple versions of {es}, you need to use multiple versions of
|
||||
|
||||
@ -11,6 +11,8 @@ a large codebase with many events happening at the same time.
|
||||
To help you with this, the client offers you a correlation id system and other
|
||||
features. Let's see them in action.
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Events
|
||||
|
||||
The client is an event emitter, this means that you can listen for its event and
|
||||
@ -126,6 +128,7 @@ request: {
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Correlation id
|
||||
|
||||
Correlating events can be quite hard, especially if there are many events at the
|
||||
@ -193,6 +196,7 @@ client.search({
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Context object
|
||||
|
||||
Sometimes, you might need to make some custom data available in your events, you
|
||||
@ -268,6 +272,7 @@ client.search({
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Client name
|
||||
|
||||
If you are using multiple instances of the client or if you are using multiple
|
||||
@ -321,6 +326,7 @@ child.search({
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== X-Opaque-Id support
|
||||
|
||||
To improve the overall observability, the client offers an easy way to configure
|
||||
|
||||
@ -33,6 +33,8 @@ the `Connection` component since it has very few responsibilities and
|
||||
it does not interact with other internal components other than getting
|
||||
requests and returning responses.
|
||||
|
||||
|
||||
[discrete]
|
||||
=== `@elastic/elasticsearch-mock`
|
||||
|
||||
Writing each time a mock for your test can be annoying and error-prone,
|
||||
|
||||
@ -1,5 +1,4 @@
|
||||
[[typescript]]
|
||||
|
||||
== TypeScript support
|
||||
|
||||
The client offers a first-class support for TypeScript, since it ships the type
|
||||
@ -39,6 +38,7 @@ console.log(response.body)
|
||||
You don't have to specify all the generics, but the order must be respected.
|
||||
|
||||
|
||||
[discrete]
|
||||
=== A complete example
|
||||
|
||||
[source,ts]
|
||||
|
||||
@ -81,6 +81,7 @@ client.search({
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Aborting a request
|
||||
|
||||
If needed, you can abort a running request by calling the `request.abort()` method returned by the API.
|
||||
@ -134,6 +135,7 @@ request.abort()
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Request specific options
|
||||
If needed you can pass request specific options in a second object:
|
||||
|
||||
@ -210,6 +212,8 @@ _Default:_ `null`
|
||||
_Default:_ `null`
|
||||
|===
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Connecting through a proxy
|
||||
|
||||
~Added~ ~in~ ~`v7.10.0`~
|
||||
@ -250,6 +254,8 @@ const client = new Client({
|
||||
})
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Error handling
|
||||
|
||||
The client exposes a variety of error objects that you can use to enhance your
|
||||
|
||||
Reference in New Issue
Block a user