diff --git a/docs/getting-started.asciidoc b/docs/getting-started.asciidoc new file mode 100644 index 000000000..d272d1302 --- /dev/null +++ b/docs/getting-started.asciidoc @@ -0,0 +1,170 @@ +[[getting-started-js]] +== Getting started + +This page guides you through the installation process of the Node.js client, +shows you how to instantiate the client, and how to perform basic Elasticsearch +operations with it. + +[discrete] +=== Requirements + +* https://nodejs.org/[Node.js] version 14.x or newer +* https://docs.npmjs.com/downloading-and-installing-node-js-and-npm[`npm`], usually bundled with Node.js + +[discrete] +=== Installation + +To install the latest version of the client, run the following command: + +[source,shell] +-------------------------- +npm install @elastic/elasticsearch +-------------------------- + +Refer to the <> page to learn more. + + +[discrete] +=== Connecting + +You can connect to the Elastic Cloud using an API key and the Elasticsearch +endpoint. + +[source,js] +---- +const { Client } = require('@elastic/elasticsearch') +const client = new Client({ + node: 'https://...', // Elasticsearch endpoint + auth: { + apiKey: { // API key ID and secret + id: 'foo', + api_key: 'bar', + } + } +}) +---- + +Your Elasticsearch endpoint can be found on the **My deployment** page of your +deployment: + +image::images/es-endpoint.jpg[alt="Finding Elasticsearch endpoint",align="center"] + +You can generate an API key on the **Management** page under Security. + +image::images/create-api-key.png[alt="Create API key",align="center"] + +For other connection options, refer to the <> section. + + +[discrete] +=== Operations + +Time to use Elasticsearch! This section walks you through the basic, and most +important, operations of Elasticsearch. + + +[discrete] +==== Creating an index + +This is how you create the `my_index` index: + +[source,js] +---- +await client.indices.create({ index: 'my_index' }) +---- + + +[discrete] +==== Indexing documents + +This is a simple way of indexing a document: + +[source,js] +---- +await client.index({ + index: 'my_index', + id: 'my_document_id', + document: { + foo: 'foo', + bar: 'bar', + }, +}) +---- + + +[discrete] +==== Getting documents + +You can get documents by using the following code: + +[source,js] +---- +await client.get({ + index: 'my_index', + id: 'my_document_id', +}) +---- + + +[discrete] +==== Searching documents + +This is how you can create a single match query with the client: + +[source,js] +---- +await client.search({ + query: { + match: { + foo: 'foo' + } + } +}) +---- + + +[discrete] +==== Updating documents + +This is how you can update a document, for example to add a new field: + +[source,js] +---- +await client.update({ + index: 'my_index', + id: 'my_document_id', + doc: { + foo: 'bar', + new_field: 'new value' + } +}) +---- + + +[discrete] +==== Deleting documents + +[source,js] +---- +await client.delete({ + index: 'my_index', + id: 'my_document_id', +}) +---- + + +[discrete] +==== Deleting an index + +[source,js] +---- +await client.indices.delete({ index: 'my_index' }) +---- + + +[discrete] +== Further reading + +* Use <> for a more comfortable experience with the APIs. +* For an elaborate example of how to ingest data into Elastic Cloud, +refer to {cloud}/ec-getting-started-node-js.html[this page]. diff --git a/docs/images/create-api-key.png b/docs/images/create-api-key.png new file mode 100644 index 000000000..d75c23030 Binary files /dev/null and b/docs/images/create-api-key.png differ diff --git a/docs/images/es-endpoint.jpg b/docs/images/es-endpoint.jpg new file mode 100644 index 000000000..6da2e7565 Binary files /dev/null and b/docs/images/es-endpoint.jpg differ diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 2de0d54a7..eda790be4 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -4,6 +4,7 @@ include::{asciidoc-dir}/../../shared/versions/stack/{source_branch}.asciidoc[] include::{asciidoc-dir}/../../shared/attributes.asciidoc[] include::introduction.asciidoc[] +include::getting-started.asciidoc[] include::changelog.asciidoc[] include::installation.asciidoc[] include::connecting.asciidoc[] diff --git a/docs/introduction.asciidoc b/docs/introduction.asciidoc index 83885d09e..e6b5963e0 100644 --- a/docs/introduction.asciidoc +++ b/docs/introduction.asciidoc @@ -17,66 +17,6 @@ about the features of the client. * TypeScript support out of the box. -[discrete] -=== Quick start - -[source,js] ----- -'use strict' - -const { Client } = require('@elastic/elasticsearch') -const client = new Client({ - cloud: { id: '' }, - auth: { apiKey: 'base64EncodedKey' } -}) - -async function run () { - // Let's start by indexing some data - await client.index({ - index: 'game-of-thrones', - document: { - character: 'Ned Stark', - quote: 'Winter is coming.' - } - }) - - await client.index({ - index: 'game-of-thrones', - document: { - character: 'Daenerys Targaryen', - quote: 'I am the blood of the dragon.' - } - }) - - await client.index({ - index: 'game-of-thrones', - document: { - 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 - // get any result in the consequent search - await client.indices.refresh({ index: 'game-of-thrones' }) - - // Let's search! - const result= await client.search({ - index: 'game-of-thrones', - query: { - match: { quote: 'winter' } - } - }) - - console.log(result.hits.hits) -} - -run().catch(console.log) ----- - -TIP: For an elaborate example of how to ingest data into Elastic Cloud, -refer to {cloud}/ec-getting-started-node-js.html[this page]. - [discrete] ==== Install multiple versions