Skip to content

[Backport 8.9] [DOCS] Adds getting started content based on the template #1931

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 5, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 170 additions & 0 deletions docs/getting-started.asciidoc
Original file line number Diff line number Diff line change
@@ -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 <<installation>> 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 <<client-connecting>> 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 <<client-helpers>> 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].
Binary file added docs/images/create-api-key.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/es-endpoint.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions docs/index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
Expand Down
60 changes: 0 additions & 60 deletions docs/introduction.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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: '<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

Expand Down