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

[DOCS] Fine-tunes the Node.js client introduction (#985)

Browse Source
This commit is contained in:
István Zoltán Szabó
2019-10-10 10:18:21 +02:00
committed by István Zoltán Szabó
parent 7f7635a44b
commit 8d08bb9665
1 changed files with 54 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
docs/introduction.asciidoc
View File

@ -1,9 +1,11 @@
[[introduction]]
== Introduction
The official Node.js client for Elasticsearch.
The official Node.js client for {es}.
=== Features
* One-to-one mapping with REST API.
* Generalized, pluggable architecture.
* Configurable, automatic discovery of cluster nodes.
@ -12,21 +14,27 @@ The official Node.js client for Elasticsearch.
* Child client support.
* TypeScript support out of the box.
=== Install
[source,sh]
----
npm install @elastic/elasticsearch
----
=== Compatibility
The minimum supported version of Node.js is `v8`.
The library is compatible with all Elasticsearch versions since 5.x, and you should use the same major version of the Elasticsearch instance that you are using.
The library is compatible with all {es} versions since 5.x. We recommend you to
use the same major version of the client as the {es} instance that you are
using.
[%header,cols=2*]
|===
|Elasticsearch Version
|{es} Version
|Client Version
|`master`
@ -42,26 +50,33 @@ The library is compatible with all Elasticsearch versions since 5.x, and you sho
|`5.x`
|===
To install a specific major of the client, run the following command:
To install a specific major version of the client, run the following command:
----
npm install @elastic/elasticsearch@<major>
----
==== Browser
WARNING: There is no official support for the browser environment. It exposes your Elasticsearch instance to everyone, which could lead to security issues.
We recommend that you write a lightweight proxy that uses this client instead.
WARNING: There is no official support for the browser environment. It exposes
your {es} instance to everyone, which could lead to security issues. We
recommend you to write a lightweight proxy that uses this client instead.
=== Quick start
First of all, require the client and initialize it:
First of all, require, then initialize the client:
[source,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.
You can use both the callback API and the promise API, both behave the same way.
[source,js]
----
// promise API
@ -78,7 +93,10 @@ client.search({
if (err) console.log(err)
})
----
The returned value of **every** API call is formed as follows:
[source,ts]
----
{
@ -90,7 +108,9 @@ The returned value of **every** API call is formed as follows:
}
----
Let's see a complete example!
[source,js]
----
'use strict'
@ -102,7 +122,7 @@ 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
// type: '_doc', // uncomment this line if you are using {es} ≤ 6
body: {
character: 'Ned Stark',
quote: 'Winter is coming.'
@ -111,7 +131,7 @@ async function run () {
await client.index({
index: 'game-of-thrones',
// type: '_doc', // uncomment this line if you are using Elasticsearch ≤ 6
// type: '_doc', // uncomment this line if you are using {es} ≤ 6
body: {
character: 'Daenerys Targaryen',
quote: 'I am the blood of the dragon.'
@ -120,21 +140,21 @@ async function run () {
await client.index({
index: 'game-of-thrones',
// type: '_doc', // uncomment this line if you are using Elasticsearch ≤ 6
// type: '_doc', // uncomment this line if you are using {es} ≤ 6
body: {
character: 'Tyrion Lannister',
quote: 'A mind needs books like a sword needs a whetstone.'
}
})
// here we are forcing an index refresh, otherwise we will not
// We need to force an index refresh at this point, otherwise we will not
// get any result in the consequent search
await client.indices.refresh({ index: 'game-of-thrones' })
// Let's search!
const { body } = await client.search({
index: 'game-of-thrones',
// type: '_doc', // uncomment this line if you are using Elasticsearch ≤ 6
// type: '_doc', // uncomment this line if you are using {es} ≤ 6
body: {
query: {
match: { quote: 'winter' }
@ -148,25 +168,32 @@ async function run () {
run().catch(console.log)
----
==== Install multiple versions
If you are using multiple versions of Elasticsearch, you need to use multiple versions of the client. +
In the past, install multiple versions of the same package was not possible, but with `npm v6.9`, you can do that via aliasing.
The command you must run to install different version of the client is:
==== Install multiple versions
If you are using multiple versions of {es}, you need to use multiple versions of
the client as well. In the past, installing multiple versions of the same
package was not possible, but with `npm v6.9`, you can do it via aliasing.
To install different version of the client, run the following command:
[source,sh]
----
npm install <alias>@npm:@elastic/elasticsearch@<version>
----
So for example if you need to install `7.x` and `6.x`, you will run
For example, if you need to install `7.x` and `6.x`, run the following commands:
[source,sh]
----
npm install es6@npm:@elastic/elasticsearch@6
npm install es7@npm:@elastic/elasticsearch@7
----
And your `package.json` will look like the following:
Your `package.json` will look similar to the following example:
[source,json]
----
"dependencies": {
@ -175,7 +202,8 @@ And your `package.json` will look like the following:
}
----
You will require the packages from your code by using the alias you have defined.
Require the packages from your code by using the alias you have defined.
[source,js]
----
@ -189,9 +217,13 @@ client6.info(console.log)
client7.info(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 {es} (the one
that lives in the {es} master branch), use the following command:
[source,sh]
----
npm install esmaster@github:elastic/elasticsearch-js
----
WARNING: This command will install the master branch of the client, which is not considered stable.
WARNING: This command installs the master branch of the client which is not
considered stable.