From 4b5401324800808f977b70545362ba0823d510e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 3 Feb 2020 17:48:13 +0100 Subject: [PATCH] =?UTF-8?q?[DOCS]=20Fine-tunes=20the=20Node.Js=20client=20?= =?UTF-8?q?Typescript=20and=20examples=20se=E2=80=A6=20(#1078)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [DOCS] Fine-tunes the Node.Js client Typescript and examples sections. * [DOCS] Fixes merge conflict. --- docs/examples/asStream.asciidoc | 6 ++++-- docs/examples/bulk.asciidoc | 4 ++-- docs/examples/get.asciidoc | 5 +++-- docs/examples/ignore.asciidoc | 1 + docs/examples/msearch.asciidoc | 3 ++- docs/examples/reindex.asciidoc | 9 +++++++-- docs/examples/scroll.asciidoc | 21 ++++++++++++++++----- docs/examples/search.asciidoc | 7 +++++-- docs/examples/sql.query.asciidoc | 11 +++++++++-- docs/examples/suggest.asciidoc | 7 ++++--- docs/examples/transport.request.asciidoc | 13 ++++++++++--- docs/examples/typescript.asciidoc | 6 ++++-- docs/examples/update.asciidoc | 5 +++-- docs/examples/update_by_query.asciidoc | 4 +++- docs/typescript.asciidoc | 19 ++++++++++++++----- 15 files changed, 87 insertions(+), 34 deletions(-) diff --git a/docs/examples/asStream.asciidoc b/docs/examples/asStream.asciidoc index d449fca1a..df66744e0 100644 --- a/docs/examples/asStream.asciidoc +++ b/docs/examples/asStream.asciidoc @@ -1,7 +1,8 @@ [[as_stream_examples]] == asStream -Instead of getting the parsed body back, you will get the raw Node.js stream of data. +Instead of getting the parsed body back, you will get the raw Node.js stream of +data. [source,js] ---- @@ -76,7 +77,8 @@ async function run () { run().catch(console.log) ---- -TIP: This can be useful if you need to pipe the Elasticsearch's response to a proxy, or send it directly to another source. +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] ---- diff --git a/docs/examples/bulk.asciidoc b/docs/examples/bulk.asciidoc index e2104e4d1..9e0830703 100644 --- a/docs/examples/bulk.asciidoc +++ b/docs/examples/bulk.asciidoc @@ -1,8 +1,8 @@ [[bulk_examples]] == Bulk -The `bulk` API makes it possible to perform many index/delete operations in a single API call. + -This can greatly increase the indexing speed. +The `bulk` API makes it possible to perform many index/delete operations in a +single API call. This can greatly increase the indexing speed. [source,js] ---- diff --git a/docs/examples/get.asciidoc b/docs/examples/get.asciidoc index c2fd5a61d..3fa0fd720 100644 --- a/docs/examples/get.asciidoc +++ b/docs/examples/get.asciidoc @@ -1,8 +1,9 @@ [[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'`. +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] --------- diff --git a/docs/examples/ignore.asciidoc b/docs/examples/ignore.asciidoc index c7a40583d..8b8ec6b34 100644 --- a/docs/examples/ignore.asciidoc +++ b/docs/examples/ignore.asciidoc @@ -1,5 +1,6 @@ [[ignore_examples]] == Ignore + HTTP status codes which should not be considered errors for this request. [source,js] diff --git a/docs/examples/msearch.asciidoc b/docs/examples/msearch.asciidoc index 9cf2d79cd..49fadd1ea 100644 --- a/docs/examples/msearch.asciidoc +++ b/docs/examples/msearch.asciidoc @@ -1,7 +1,8 @@ [[msearch_examples]] == MSearch -The multi search API allows to execute several search requests within the same API. +The multi search API allows to execute several search requests within the same +API. [source,js] ---- diff --git a/docs/examples/reindex.asciidoc b/docs/examples/reindex.asciidoc index a99984d69..c91ac5793 100644 --- a/docs/examples/reindex.asciidoc +++ b/docs/examples/reindex.asciidoc @@ -1,9 +1,14 @@ [[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. +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. +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] ---- diff --git a/docs/examples/scroll.asciidoc b/docs/examples/scroll.asciidoc index 84b5aed83..71c5308d1 100644 --- a/docs/examples/scroll.asciidoc +++ b/docs/examples/scroll.asciidoc @@ -1,13 +1,23 @@ [[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. +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, e.g. in order to reindex the contents of one index into a new index with a different configuration. +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. +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 Elasticsearch how long it should keep the “search context” alive. +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. [source,js] ---- @@ -100,7 +110,8 @@ async function run () { run().catch(console.log) ---- -Another cool usage of the `scroll` API can be done with Node.js ≥ 10, by using async iteration! +Another cool usage of the `scroll` API can be done with Node.js ≥ 10, by using +async iteration! [source,js] ---- diff --git a/docs/examples/search.asciidoc b/docs/examples/search.asciidoc index 62420024a..006804fe6 100644 --- a/docs/examples/search.asciidoc +++ b/docs/examples/search.asciidoc @@ -1,8 +1,11 @@ [[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]. +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] ---- diff --git a/docs/examples/sql.query.asciidoc b/docs/examples/sql.query.asciidoc index e6bee5f4f..bc1dab10e 100644 --- a/docs/examples/sql.query.asciidoc +++ b/docs/examples/sql.query.asciidoc @@ -1,9 +1,16 @@ [[sql_query_examples]] == SQL -Elasticsearch SQL is an X-Pack component that allows SQL-like queries to be executed in real-time against Elasticsearch. Whether using the REST interface, command-line or JDBC, any client can use SQL to search and aggregate data natively inside Elasticsearch. One can think of Elasticsearch SQL as a translator, one that understands both SQL and Elasticsearch and makes it easy to read and process data in real-time, at scale by leveraging Elasticsearch capabilities. +{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. +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] ---- diff --git a/docs/examples/suggest.asciidoc b/docs/examples/suggest.asciidoc index 004e51648..beaccf51f 100644 --- a/docs/examples/suggest.asciidoc +++ b/docs/examples/suggest.asciidoc @@ -1,10 +1,11 @@ [[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 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. +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] ---- diff --git a/docs/examples/transport.request.asciidoc b/docs/examples/transport.request.asciidoc index 5cd89aa76..385f61091 100644 --- a/docs/examples/transport.request.asciidoc +++ b/docs/examples/transport.request.asciidoc @@ -1,12 +1,19 @@ [[transport_request_examples]] == transport.request -It can happen that you need to communicate with Elasticsearch 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 Elasticsearch when you use an API method. +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`. +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. +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] ---- diff --git a/docs/examples/typescript.asciidoc b/docs/examples/typescript.asciidoc index 32cc146fe..4fb97e7f2 100644 --- a/docs/examples/typescript.asciidoc +++ b/docs/examples/typescript.asciidoc @@ -1,9 +1,11 @@ [[typescript_examples]] == Typescript -The client offers a first-class support for TypeScript, since it ships the type definitions for every exposed API. +The client offers a first-class support for TypeScript, since it ships the type +definitions for every exposed API. -NOTE: If you are using TypeScript you will be required to use _snake_case_ style to define the API parameters instead of _camelCase_. +NOTE: If you are using TypeScript you will be required to use _snake_case_ style +to define the API parameters instead of _camelCase_. [source,ts] ---- diff --git a/docs/examples/update.asciidoc b/docs/examples/update.asciidoc index ab08f79fb..9f5ce102b 100644 --- a/docs/examples/update.asciidoc +++ b/docs/examples/update.asciidoc @@ -1,8 +1,9 @@ [[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. +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] --------- diff --git a/docs/examples/update_by_query.asciidoc b/docs/examples/update_by_query.asciidoc index 7d4a647e7..a9740ddf6 100644 --- a/docs/examples/update_by_query.asciidoc +++ b/docs/examples/update_by_query.asciidoc @@ -1,7 +1,9 @@ [[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. +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] --------- diff --git a/docs/typescript.asciidoc b/docs/typescript.asciidoc index e6f1ca8c3..94f8a28ff 100644 --- a/docs/typescript.asciidoc +++ b/docs/typescript.asciidoc @@ -1,12 +1,19 @@ [[typescript]] == TypeScript support -The client offers a first-class support for TypeScript, since it ships the type definitions for every exposed API. +The client offers a first-class support for TypeScript, since it ships the type +definitions for every exposed API. -NOTE: If you are using TypeScript you will be required to use _snake_case_ style to define the API parameters instead of _camelCase_. +NOTE: If you are using TypeScript you will be required to use _snake_case_ style +to define the API parameters instead of _camelCase_. -Other than the types for the surface API, the client offers the types for every request method, via the `RequestParams`, if you need the types for a search request for instance, you can access them via `RequestParams.Search`. -Every API that supports a body, accepts a https://www.typescriptlang.org/docs/handbook/generics.html[generics] which represents the type of the request body, if you don't configure anything, it will default to `any`. +Other than the types for the surface API, the client offers the types for every +request method, via the `RequestParams`, if you need the types for a search +request for instance, you can access them via `RequestParams.Search`. +Every API that supports a body, accepts a +https://www.typescriptlang.org/docs/handbook/generics.html[generics] which +represents the type of the request body, if you don't configure anything, it +will default to `any`. For example: @@ -40,7 +47,9 @@ const searchParams: RequestParams.Search = { } ---- -You can find the type definiton of a response in `ApiResponse`, which accepts a generics as well if you want to specify the body type, otherwise it defaults to `any`. +You can find the type definiton of a response in `ApiResponse`, which accepts a +generics as well if you want to specify the body type, otherwise it defaults to +`any`. [source,ts] ----