[docs] Migrate docs from AsciiDoc to Markdown (#2635)

* delete asciidoc files

* add migrated files

* Apply suggestions from review

Co-authored-by: Josh Mock <josh@joshmock.com>

* Apply suggestions from review

Co-authored-by: Josh Mock <josh@joshmock.com>

* add the new ci checks (#2634)

---------

Co-authored-by: Marci W <333176+marciw@users.noreply.github.com>
Co-authored-by: Josh Mock <josh@joshmock.com>
This commit is contained in:
Colleen McGinnis
2025-02-27 11:51:14 -06:00
committed by GitHub
parent ac231c859e
commit 3e5e568c07
142 changed files with 18203 additions and 31131 deletions

View File

@ -1,99 +0,0 @@
[[as_stream_examples]]
=== asStream
Instead of getting the parsed body back, you will get the raw Node.js stream of
data.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
const bulkResponse = await client.bulk({
refresh: true,
operations: [
// operation to perform
{ index: { _index: 'game-of-thrones' } },
// the document to index
{
character: 'Ned Stark',
quote: 'Winter is coming.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Daenerys Targaryen',
quote: 'I am the blood of the dragon.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Tyrion Lannister',
quote: 'A mind needs books like a sword needs a whetstone.'
}
]
})
if (bulkResponse.errors) {
console.log(bulkResponse)
process.exit(1)
}
// Let's search!
const result = await client.search({
index: 'game-of-thrones',
query: {
match: {
quote: 'winter'
}
}
}, {
asStream: true
})
let payload = ''
result.setEncoding('utf8')
for await (const chunk of result) {
payload += chunk
}
console.log(JSON.parse(payload))
}
run().catch(console.log)
----
TIP: This can be useful if you need to pipe the {es}'s response to a proxy, or
send it directly to another source.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
const fastify = require('fastify')()
fastify.post('/search/:index', async (req, reply) => {
const { body, statusCode, headers } = await client.search({
index: req.params.index,
...req.body
}, {
asStream: true,
meta: true
})
reply.code(statusCode).headers(headers)
return body
})
fastify.listen(3000)
----

View File

@ -1,93 +0,0 @@
[[bulk_examples]]
=== Bulk
With the {jsclient}/api-reference.html#_bulk[`bulk` API], you can perform multiple index/delete operations in a
single API call. The `bulk` API significantly increases indexing speed.
NOTE: You can also use the <<bulk-helper,bulk helper>>.
[source,js]
----
'use strict'
require('array.prototype.flatmap').shim()
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
await client.indices.create({
index: 'tweets',
operations: {
mappings: {
properties: {
id: { type: 'integer' },
text: { type: 'text' },
user: { type: 'keyword' },
time: { type: 'date' }
}
}
}
}, { ignore: [400] })
const dataset = [{
id: 1,
text: 'If I fall, don\'t bring me back.',
user: 'jon',
time: new Date()
}, {
id: 2,
text: 'Winter is coming',
user: 'ned',
time: new Date()
}, {
id: 3,
text: 'A Lannister always pays his debts.',
user: 'tyrion',
time: new Date()
}, {
id: 4,
text: 'I am the blood of the dragon.',
user: 'daenerys',
time: new Date()
}, {
id: 5, // change this value to a string to see the bulk response with errors
text: 'A girl is Arya Stark of Winterfell. And I\'m going home.',
user: 'arya',
time: new Date()
}]
const operations = dataset.flatMap(doc => [{ index: { _index: 'tweets' } }, doc])
const bulkResponse = await client.bulk({ refresh: true, operations })
if (bulkResponse.errors) {
const erroredDocuments = []
// The items array has the same order of the dataset we just indexed.
// The presence of the `error` key indicates that the operation
// that we did for the document has failed.
bulkResponse.items.forEach((action, i) => {
const operation = Object.keys(action)[0]
if (action[operation].error) {
erroredDocuments.push({
// If the status is 429 it means that you can retry the document,
// otherwise it's very likely a mapping error, and you should
// fix the document before to try it again.
status: action[operation].status,
error: action[operation].error,
operation: operations[i * 2],
document: operations[i * 2 + 1]
})
}
})
console.log(erroredDocuments)
}
const count = await client.count({ index: 'tweets' })
console.log(count)
}
run().catch(console.log)
----

View File

@ -1,37 +0,0 @@
[[exists_examples]]
=== Exists
Check that the document `/game-of-thrones/1` exists.
NOTE: Since this API uses the `HEAD` method, the body value will be boolean.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
await client.index({
index: 'game-of-thrones',
id: '1',
document: {
character: 'Ned Stark',
quote: 'Winter is coming.'
}
})
const exists = await client.exists({
index: 'game-of-thrones',
id: 1
})
console.log(exists) // true
}
run().catch(console.log)
----

View File

@ -1,37 +0,0 @@
[[get_examples]]
=== Get
The get API allows to get a typed JSON document from the index based on its id.
The following example gets a JSON document from an index called
`game-of-thrones`, under a type called `_doc`, with id valued `'1'`.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
await client.index({
index: 'game-of-thrones',
id: '1',
document: {
character: 'Ned Stark',
quote: 'Winter is coming.'
}
})
const document = await client.get({
index: 'game-of-thrones',
id: '1'
})
console.log(document)
}
run().catch(console.log)
----

View File

@ -1,65 +0,0 @@
[[ignore_examples]]
=== Ignore
HTTP status codes which should not be considered errors for this request.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
const bulkResponse = await client.bulk({
refresh: true,
operations: [
// operation to perform
{ index: { _index: 'game-of-thrones' } },
// the document to index
{
character: 'Ned Stark',
quote: 'Winter is coming.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Daenerys Targaryen',
quote: 'I am the blood of the dragon.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Tyrion Lannister',
quote: 'A mind needs books like a sword needs a whetstone.'
}
]
})
if (bulkResponse.errors) {
console.log(bulkResponse)
process.exit(1)
}
// Let's search!
const result = await client.search({
index: 'game-of-thrones',
body: {
query: {
match: {
quote: 'fire'
}
}
}
}, {
ignore: [404]
})
console.log(result) // ResponseError
}
run().catch(console.log)
----

View File

@ -1,34 +0,0 @@
[[examples]]
== Examples
Following you can find some examples on how to use the client.
* Use of the <<as_stream_examples,asStream>> parameter;
* Executing a <<bulk_examples,bulk>> request;
* Executing a <<exists_examples,exists>> request;
* Executing a <<get_examples,get>> request;
* Executing a <<sql_query_examples,sql.query>> request;
* Executing a <<update_examples,update>> request;
* Executing a <<update_by_query_examples,update by query>> request;
* Executing a <<reindex_examples,reindex>> request;
* Use of the <<ignore_examples,ignore>> parameter;
* Executing a <<msearch_examples,msearch>> request;
* How do I <<scroll_examples,scroll>>?
* Executing a <<search_examples,search>> request;
* I need <<suggest_examples,suggestions>>;
* How to use the <<transport_request_examples,transport.request>> method;
include::asStream.asciidoc[]
include::bulk.asciidoc[]
include::exists.asciidoc[]
include::get.asciidoc[]
include::ignore.asciidoc[]
include::msearch.asciidoc[]
include::scroll.asciidoc[]
include::search.asciidoc[]
include::suggest.asciidoc[]
include::transport.request.asciidoc[]
include::sql.query.asciidoc[]
include::update.asciidoc[]
include::update_by_query.asciidoc[]
include::reindex.asciidoc[]

View File

@ -1,60 +0,0 @@
[[msearch_examples]]
=== MSearch
The multi search API allows to execute several search requests within the same
API.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
const bulkResponse = await client.bulk({
refresh: true,
operations: [
{ index: { _index: 'game-of-thrones' } },
{
character: 'Ned Stark',
quote: 'Winter is coming.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Daenerys Targaryen',
quote: 'I am the blood of the dragon.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Tyrion Lannister',
quote: 'A mind needs books like a sword needs a whetstone.'
}
]
})
if (bulkResponse.errors) {
console.log(bulkResponse)
process.exit(1)
}
const result = await client.msearch({
searches: [
{ index: 'game-of-thrones' },
{ query: { match: { character: 'Daenerys' } } },
{ index: 'game-of-thrones' },
{ query: { match: { character: 'Tyrion' } } }
]
})
console.log(result.responses)
}
run().catch(console.log)
----

View File

@ -1,79 +0,0 @@
[[reindex_examples]]
=== Reindex
The `reindex` API extracts the document source from the source index and indexes
the documents into the destination index. You can copy all documents to the
destination index, reindex a subset of the documents or update the source before
to reindex it.
In the following example we have a `game-of-thrones` index which contains
different quotes of various characters, we want to create a new index only for
the house Stark and remove the `house` field from the document source.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
await client.index({
index: 'game-of-thrones',
document: {
character: 'Ned Stark',
quote: 'Winter is coming.',
house: 'stark'
}
})
await client.index({
index: 'game-of-thrones',
document: {
character: 'Arya Stark',
quote: 'A girl is Arya Stark of Winterfell. And I\'m going home.',
house: 'stark'
}
})
await client.index({
index: 'game-of-thrones',
refresh: true,
document: {
character: 'Tyrion Lannister',
quote: 'A Lannister always pays his debts.',
house: 'lannister'
}
})
await client.reindex({
wait_for_completion: true,
refresh: true,
source: {
index: 'game-of-thrones',
query: {
match: { house: 'stark' }
}
},
dest: {
index: 'stark-index'
},
script: {
lang: 'painless',
source: 'ctx._source.remove("house")'
}
})
const result = await client.search({
index: 'stark-index',
query: { match_all: {} }
})
console.log(result.hits.hits)
}
run().catch(console.log)
----

View File

@ -1,195 +0,0 @@
[[scroll_examples]]
=== Scroll
While a search request returns a single “page” of results, the scroll API can be
used to retrieve large numbers of results (or even all results) from a single
search request, in much the same way as you would use a cursor on a traditional
database.
Scrolling is not intended for real time user requests, but rather for processing
large amounts of data, for example in order to reindex the contents of one index
into a new index with a different configuration.
NOTE: The results that are returned from a scroll request reflect the state of
the index at the time that the initial search request was made, like a snapshot
in time. Subsequent changes to documents (index, update or delete) will only
affect later search requests.
In order to use scrolling, the initial search request should specify the scroll
parameter in the query string, which tells {es} how long it should keep the
“search context” alive.
NOTE: Did you know that we provide an helper for sending scroll requests? You can find it <<scroll-search-helper,here>>.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
const allQuotes = []
const responseQueue = []
// Let's index some data!
const bulkResponse = await client.bulk({
// here we are forcing an index refresh,
// otherwise we will not get any result
// in the consequent search
refresh: true,
operations: [
// operation to perform
{ index: { _index: 'game-of-thrones' } },
// the document to index
{
character: 'Ned Stark',
quote: 'Winter is coming.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Daenerys Targaryen',
quote: 'I am the blood of the dragon.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Tyrion Lannister',
quote: 'A mind needs books like a sword needs a whetstone.'
}
]
})
if (bulkResponse.errors) {
console.log(bulkResponse)
process.exit(1)
}
// start things off by searching, setting a scroll timeout, and pushing
// our first response into the queue to be processed
const response = await client.search({
index: 'game-of-thrones',
// keep the search results "scrollable" for 30 seconds
scroll: '30s',
// for the sake of this example, we will get only one result per search
size: 1,
// filter the source to only include the quote field
_source: ['quote'],
query: {
match_all: {}
}
})
responseQueue.push(response)
while (responseQueue.length) {
const body = responseQueue.shift()
// collect the titles from this response
body.hits.hits.forEach(function (hit) {
allQuotes.push(hit._source.quote)
})
// check to see if we have collected all of the quotes
if (body.hits.total.value === allQuotes.length) {
console.log('Every quote', allQuotes)
break
}
// get the next response if there are more quotes to fetch
responseQueue.push(
await client.scroll({
scroll_id: body._scroll_id,
scroll: '30s'
})
)
}
}
run().catch(console.log)
----
Another cool usage of the `scroll` API can be done with Node.js ≥ 10, by using
async iteration!
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
// Scroll utility
async function * scrollSearch (params) {
let response = await client.search(params)
while (true) {
const sourceHits = response.hits.hits
if (sourceHits.length === 0) {
break
}
for (const hit of sourceHits) {
yield hit
}
if (!response._scroll_id) {
break
}
response = await client.scroll({
scroll_id: response._scroll_id,
scroll: params.scroll
})
}
}
async function run () {
await client.bulk({
refresh: true,
operations: [
{ index: { _index: 'game-of-thrones' } },
{
character: 'Ned Stark',
quote: 'Winter is coming.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Daenerys Targaryen',
quote: 'I am the blood of the dragon.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Tyrion Lannister',
quote: 'A mind needs books like a sword needs a whetstone.'
}
]
})
const params = {
index: 'game-of-thrones',
scroll: '30s',
size: 1,
_source: ['quote'],
query: {
match_all: {}
}
}
for await (const hit of scrollSearch(params)) {
console.log(hit._source)
}
}
run().catch(console.log)
----

View File

@ -1,64 +0,0 @@
[[search_examples]]
=== Search
The `search` API allows you to execute a search query and get back search hits
that match the query. The query can either be provided using a simple
https://www.elastic.co/guide/en/elasticsearch/reference/6.6/search-uri-request.html[query string as a parameter],
or using a
https://www.elastic.co/guide/en/elasticsearch/reference/6.6/search-request-body.html[request body].
[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',
// here we are forcing an index refresh,
// otherwise we will not get any result
// in the consequent search
refresh: true,
document: {
character: 'Tyrion Lannister',
quote: 'A mind needs books like a sword needs a whetstone.'
}
})
// 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)
----

View File

@ -1,72 +0,0 @@
[[sql_query_examples]]
=== SQL
{es} SQL is an X-Pack component that allows SQL-like queries to be executed in
real-time against {es}. Whether using the REST interface, command-line or JDBC,
any client can use SQL to search and aggregate data natively inside {es}. One
can think of {es} SQL as a translator, one that understands both SQL and {es}
and makes it easy to read and process data in real-time, at scale by leveraging
{es} capabilities.
In the following example we will search all the documents that has the field
`house` equals to `stark`, log the result with the tabular view and then
manipulate the result to obtain an object easy to navigate.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
await client.index({
index: 'game-of-thrones',
document: {
character: 'Ned Stark',
quote: 'Winter is coming.',
house: 'stark'
}
})
await client.index({
index: 'game-of-thrones',
document: {
character: 'Arya Stark',
quote: 'A girl is Arya Stark of Winterfell. And I\'m going home.',
house: 'stark'
}
})
await client.index({
index: 'game-of-thrones',
refresh: true,
document: {
character: 'Tyrion Lannister',
quote: 'A Lannister always pays his debts.',
house: 'lannister'
}
})
const result = await client.sql.query({
query: "SELECT * FROM \"game-of-thrones\" WHERE house='stark'"
})
console.log(result)
const data = result.rows.map(row => {
const obj = {}
for (let i = 0; i < row.length; i++) {
obj[result.columns[i].name] = row[i]
}
return obj
})
console.log(data)
}
run().catch(console.log)
----

View File

@ -1,67 +0,0 @@
[[suggest_examples]]
=== Suggest
The suggest feature suggests similar looking terms based on a provided text by
using a suggester. _Parts of the suggest feature are still under development._
The suggest request part is defined alongside the query part in a `search`
request. If the query part is left out, only suggestions are returned.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
const bulkResponse = await client.bulk({
refresh: true,
operations: [
{ index: { _index: 'game-of-thrones' } },
{
character: 'Ned Stark',
quote: 'Winter is coming.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Daenerys Targaryen',
quote: 'I am the blood of the dragon.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Tyrion Lannister',
quote: 'A mind needs books like a sword needs a whetstone.'
}
]
})
if (bulkResponse.errors) {
console.log(bulkResponse)
process.exit(1)
}
const result = await client.search({
index: 'game-of-thrones',
query: {
match: { quote: 'winter' }
},
suggest: {
gotsuggest: {
text: 'winter',
term: { field: 'quote' }
}
}
})
console.log(result)
}
run().catch(console.log)
----

View File

@ -1,74 +0,0 @@
[[transport_request_examples]]
=== transport.request
It can happen that you need to communicate with {es} by using an API that is not
supported by the client, to mitigate this issue you can directly call
`client.transport.request`, which is the internal utility that the client uses
to communicate with {es} when you use an API method.
NOTE: When using the `transport.request` method you must provide all the
parameters needed to perform an HTTP call, such as `method`, `path`,
`querystring`, and `body`.
TIP: If you find yourself use this method too often, take in consideration the
use of `client.extend`, which will make your code look cleaner and easier to
maintain.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
const bulkResponse = await client.bulk({
refresh: true,
operations: [
{ index: { _index: 'game-of-thrones' } },
{
character: 'Ned Stark',
quote: 'Winter is coming.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Daenerys Targaryen',
quote: 'I am the blood of the dragon.'
},
{ index: { _index: 'game-of-thrones' } },
{
character: 'Tyrion Lannister',
quote: 'A mind needs books like a sword needs a whetstone.'
}
]
})
if (bulkResponse.errors) {
console.log(bulkResponse)
process.exit(1)
}
const response = await client.transport.request({
method: 'POST',
path: '/game-of-thrones/_search',
body: {
query: {
match: {
quote: 'winter'
}
}
},
querystring: {}
})
console.log(response)
}
run().catch(console.log)
----

View File

@ -1,95 +0,0 @@
[[update_examples]]
=== Update
The update API allows updates of a specific document using the given script. In
the following example, we will index a document that also tracks how many times
a character has said the given quote, and then we will update the `times` field.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
await client.index({
index: 'game-of-thrones',
id: '1',
document: {
character: 'Ned Stark',
quote: 'Winter is coming.',
times: 0
}
})
await client.update({
index: 'game-of-thrones',
id: '1',
script: {
lang: 'painless',
source: 'ctx._source.times++'
// you can also use parameters
// source: 'ctx._source.times += params.count',
// params: { count: 1 }
}
})
const document = await client.get({
index: 'game-of-thrones',
id: '1'
})
console.log(document)
}
run().catch(console.log)
----
With the update API, you can also run a partial update of a document.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
await client.index({
index: 'game-of-thrones',
id: '1',
document: {
character: 'Ned Stark',
quote: 'Winter is coming.',
isAlive: true
}
})
await client.update({
index: 'game-of-thrones',
id: '1',
doc: {
isAlive: false
}
})
const document = await client.get({
index: 'game-of-thrones',
id: '1'
})
console.log(document)
}
run().catch(console.log)
----

View File

@ -1,60 +0,0 @@
[[update_by_query_examples]]
=== Update By Query
The simplest usage of _update_by_query just performs an update on every document
in the index without changing the source. This is useful to pick up a new
property or some other online mapping change.
[source,js]
----
'use strict'
const { Client } = require('@elastic/elasticsearch')
const client = new Client({
cloud: { id: '<cloud-id>' },
auth: { apiKey: 'base64EncodedKey' }
})
async function run () {
await client.index({
index: 'game-of-thrones',
document: {
character: 'Ned Stark',
quote: 'Winter is coming.'
}
})
await client.index({
index: 'game-of-thrones',
refresh: true,
document: {
character: 'Arya Stark',
quote: 'A girl is Arya Stark of Winterfell. And I\'m going home.'
}
})
await client.updateByQuery({
index: 'game-of-thrones',
refresh: true,
script: {
lang: 'painless',
source: 'ctx._source["house"] = "stark"'
},
query: {
match: {
character: 'stark'
}
}
})
const result = await client.search({
index: 'game-of-thrones',
query: { match_all: {} }
})
console.log(result.hits.hits)
}
run().catch(console.log)
----