Merge branch 'main' into renovate/ms-2.x

Author: JoshMock

docs/doc_examples/120fcf9f55128d6a81d5e87a9c235bbd.asciidoc

@@ -3,16 +3,17 @@
 
 [source, js]
 ----
-const response = await client.inference.streamInference({
-  task_type: "chat_completion",
+const response = await client.inference.chatCompletionUnified({
   inference_id: "openai-completion",
-  model: "gpt-4o",
-  messages: [
-    {
-      role: "user",
-      content: "What is Elastic?",
-    },
-  ],
+  chat_completion_request: {
+    model: "gpt-4o",
+    messages: [
+      {
+        role: "user",
+        content: "What is Elastic?",
+      },
+    ],
+  },
 });
 console.log(response);
 ----

docs/doc_examples/13ecdf99114098c76b050397d9c3d4e6.asciidoc

@@ -3,8 +3,7 @@
 
 [source, js]
 ----
-const response = await client.inference.inference({
-  task_type: "sparse_embedding",
+const response = await client.inference.sparseEmbedding({
   inference_id: "my-elser-model",
   input:
     "The sky above the port was the color of television tuned to a dead channel.",

docs/doc_examples/141ef0ebaa3b0772892b79b9bb85efb0.asciidoc

@@ -3,9 +3,8 @@
 
 [source, js]
 ----
-const response = await client.inference.put({
-  task_type: "my-inference-endpoint",
-  inference_id: "_update",
+const response = await client.inference.update({
+  inference_id: "my-inference-endpoint",
   inference_config: {
     service_settings: {
       api_key: "<API_KEY>",

docs/doc_examples/45954b8aaedfed57012be8b6538b0a24.asciidoc

@@ -3,42 +3,43 @@
 
 [source, js]
 ----
-const response = await client.inference.streamInference({
-  task_type: "chat_completion",
+const response = await client.inference.chatCompletionUnified({
   inference_id: "openai-completion",
-  messages: [
-    {
-      role: "user",
-      content: [
-        {
-          type: "text",
-          text: "What's the price of a scarf?",
+  chat_completion_request: {
+    messages: [
+      {
+        role: "user",
+        content: [
+          {
+            type: "text",
+            text: "What's the price of a scarf?",
+          },
+        ],
+      },
+    ],
+    tools: [
+      {
+        type: "function",
+        function: {
+          name: "get_current_price",
+          description: "Get the current price of a item",
+          parameters: {
+            type: "object",
+            properties: {
+              item: {
+                id: "123",
+              },
+            },
+          },
         },
-      ],
-    },
-  ],
-  tools: [
-    {
+      },
+    ],
+    tool_choice: {
       type: "function",
       function: {
         name: "get_current_price",
-        description: "Get the current price of a item",
-        parameters: {
-          type: "object",
-          properties: {
-            item: {
-              id: "123",
-            },
-          },
-        },
       },
     },
-  ],
-  tool_choice: {
-    type: "function",
-    function: {
-      name: "get_current_price",
-    },
   },
 });
 console.log(response);

docs/doc_examples/4b91ad7c9b44e07db4a4e81390f19ad3.asciidoc

@@ -3,8 +3,7 @@
 
 [source, js]
 ----
-const response = await client.inference.streamInference({
-  task_type: "completion",
+const response = await client.inference.streamCompletion({
   inference_id: "openai-completion",
   input: "What is Elastic?",
 });

docs/doc_examples/7429b16221fe741fd31b0584786dd0b0.asciidoc

@@ -3,8 +3,7 @@
 
 [source, js]
 ----
-const response = await client.inference.inference({
-  task_type: "text_embedding",
+const response = await client.inference.textEmbedding({
   inference_id: "my-cohere-endpoint",
   input:
     "The sky above the port was the color of television tuned to a dead channel.",

docs/doc_examples/82bb6c61dab959f4446dc5ecab7ecbdf.asciidoc

@@ -3,30 +3,31 @@
 
 [source, js]
 ----
-const response = await client.inference.streamInference({
-  task_type: "chat_completion",
+const response = await client.inference.chatCompletionUnified({
   inference_id: "openai-completion",
-  messages: [
-    {
-      role: "assistant",
-      content: "Let's find out what the weather is",
-      tool_calls: [
-        {
-          id: "call_KcAjWtAww20AihPHphUh46Gd",
-          type: "function",
-          function: {
-            name: "get_current_weather",
-            arguments: '{"location":"Boston, MA"}',
+  chat_completion_request: {
+    messages: [
+      {
+        role: "assistant",
+        content: "Let's find out what the weather is",
+        tool_calls: [
+          {
+            id: "call_KcAjWtAww20AihPHphUh46Gd",
+            type: "function",
+            function: {
+              name: "get_current_weather",
+              arguments: '{"location":"Boston, MA"}',
+            },
           },
-        },
-      ],
-    },
-    {
-      role: "tool",
-      content: "The weather is cold",
-      tool_call_id: "call_KcAjWtAww20AihPHphUh46Gd",
-    },
-  ],
+        ],
+      },
+      {
+        role: "tool",
+        content: "The weather is cold",
+        tool_call_id: "call_KcAjWtAww20AihPHphUh46Gd",
+      },
+    ],
+  },
 });
 console.log(response);
 ----

docs/doc_examples/b45a8c6fc746e9c90fd181e69a605fad.asciidoc

@@ -3,8 +3,7 @@
 
 [source, js]
 ----
-const response = await client.inference.inference({
-  task_type: "completion",
+const response = await client.inference.completion({
   inference_id: "openai_chat_completions",
   input: "What is Elastic?",
 });

docs/doc_examples/f1b24217b1d9ba6ea5e4fa6e6f412022.asciidoc

@@ -3,8 +3,7 @@
 
 [source, js]
 ----
-const response = await client.inference.inference({
-  task_type: "rerank",
+const response = await client.inference.rerank({
   inference_id: "cohere_rerank",
   input: ["luke", "like", "leia", "chewy", "r2d2", "star", "wars"],
   query: "star wars main character",

docs/reference/api-reference.md

@@ -7553,23 +7553,6 @@ client.inference.get({ ... })
 - **`task_type` (Optional, Enum("sparse_embedding" | "text_embedding" | "rerank" | "completion" | "chat_completion"))**: The task type
 - **`inference_id` (Optional, string)**: The inference Id
 
-## client.inference.postEisChatCompletion [_inference.post_eis_chat_completion]
-Perform a chat completion task through the Elastic Inference Service (EIS).
-
-Perform a chat completion inference task with the `elastic` service.
-
-[Endpoint documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-post-eis-chat-completion)
-
-```ts
-client.inference.postEisChatCompletion({ eis_inference_id })
-```
-
-### Arguments [_arguments_inference.post_eis_chat_completion]
-
-#### Request (object) [_request_inference.post_eis_chat_completion]
-- **`eis_inference_id` (string)**: The unique identifier of the inference endpoint.
-- **`chat_completion_request` (Optional, { messages, model, max_completion_tokens, stop, temperature, tool_choice, tools, top_p })**
-
 ## client.inference.put [_inference.put]
 Create an inference endpoint.
 When you create an inference endpoint, the associated machine learning model is automatically deployed if it is not already running.
@@ -7776,26 +7759,6 @@ These settings are specific to the `cohere` service.
 - **`task_settings` (Optional, { input_type, return_documents, top_n, truncate })**: Settings to configure the inference task.
 These settings are specific to the task type you specified.
 
-## client.inference.putEis [_inference.put_eis]
-Create an Elastic Inference Service (EIS) inference endpoint.
-
-Create an inference endpoint to perform an inference task through the Elastic Inference Service (EIS).
-
-[Endpoint documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-inference-put-eis)
-
-```ts
-client.inference.putEis({ task_type, eis_inference_id, service, service_settings })
-```
-
-### Arguments [_arguments_inference.put_eis]
-
-#### Request (object) [_request_inference.put_eis]
-- **`task_type` (Enum("chat_completion"))**: The type of the inference task that the model will perform.
-NOTE: The `chat_completion` task type only supports streaming and only through the _stream API.
-- **`eis_inference_id` (string)**: The unique identifier of the inference endpoint.
-- **`service` (Enum("elastic"))**: The type of service supported for the specified task type. In this case, `elastic`.
-- **`service_settings` ({ model_id, rate_limit })**: Settings used to install the inference model. These settings are specific to the `elastic` service.
-
 ## client.inference.putElasticsearch [_inference.put_elasticsearch]
 Create an Elasticsearch inference endpoint.
 
@@ -13567,8 +13530,6 @@ Multi-target syntax is supported.
 - **`master_timeout` (Optional, string | -1 | 0)**: The period to wait for the master node.
 If the master node is not available before the timeout expires, the request fails and returns an error.
 To indicate that the request should never timeout, set it to `-1`.
-- **`timeout` (Optional, string | -1 | 0)**: The period of time to wait for a response.
-If no response is received before the timeout expires, the request fails and returns an error.
 
 ## client.snapshot.create [_snapshot.create]
 Create a snapshot.

docs/reference/configuration.md

@@ -9,6 +9,6 @@ The client is designed to be easily configured for your needs. In the following
 
 - [Basic configuration](/reference/basic-config.md)
 - [Advanced configuration](/reference/advanced-config.md)
-- [Timeout best practices](docs-content://troubleshoot/elasticsearch/elasticsearch-client-javascript-api/nodejs.md)
+- [Timeout best practices](/reference/timeout-best-practices.md)
 - [Creating a child client](/reference/child.md)
-- [Testing](/reference/client-testing.md)
+- [Testing](/reference/client-testing.md)

docs/reference/timeout-best-practices.md

@@ -0,0 +1,13 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/timeout-best-practices.html
+---
+
+# Timeout best practices [timeout-best-practices]
+
+Starting in 9.0.0, this client is configured to not time out any HTTP request by default. {{es}} will always eventually respond to any request, even if it takes several minutes. Reissuing a request that it has not responded to yet can cause performance side effects. See the [official {{es}} recommendations for HTTP clients](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#_http_client_configuration) for more information.
+
+Prior to 9.0, this client was configured by default to operate like many HTTP client libraries do, by using a relatively short (30 second) timeout on all requests sent to {{es}}, raising a `TimeoutError` when that time period elapsed without receiving a response.
+
+If you need to set timeouts on Elasticsearch requests, setting the `requestTimeout` value to a millisecond value will cause this client to operate as it did prior to 9.0.
+

docs/reference/toc.yml

@@ -31,4 +31,5 @@ toc:
       - file: update_examples.md
       - file: update_by_query_examples.md
       - file: reindex_examples.md
-  - file: client-helpers.md
+  - file: client-helpers.md
+  - file: timeout-best-practices.md

docs/release-notes/breaking-changes.md

@@ -3,22 +3,53 @@ navigation_title: "Breaking changes"
 ---
 
 # Elasticsearch JavaScript Client breaking changes [elasticsearch-javascript-client-breaking-changes]
+
 Breaking changes can impact your Elastic applications, potentially disrupting normal operations. Before you upgrade, carefully review the Elasticsearch JavaScript Client breaking changes and take the necessary steps to mitigate any issues. To learn how to upgrade, check [Upgrade](docs-content://deploy-manage/upgrade.md).
 
 % ## Next version [elasticsearch-javascript-client-versionnext-breaking-changes]
 
-% ::::{dropdown} Title of breaking change 
+% ::::{dropdown} Title of breaking change
 % Description of the breaking change.
 % For more information, check [PR #](PR link).
 % **Impact**<br> Impact of the breaking change.
 % **Action**<br> Steps for mitigating deprecation impact.
 % ::::
 
-% ## 9.0.0 [elasticsearch-javascript-client-900-breaking-changes]
+## 9.0.0 [elasticsearch-javascript-client-900-breaking-changes]
 
-% ::::{dropdown} Title of breaking change 
-% Description of the breaking change.
-% For more information, check [PR #](PR link).
-% **Impact**<br> Impact of the breaking change.
-% **Action**<br> Steps for mitigating deprecation impact.
-% ::::
+::::{dropdown} Changes to the optional body property
+
+In 8.x, every API function had a `body` property that would provide a place to put arbitrary values that should go in the HTTP request body, even if they were not noted in the specification or documentation. In 9.0, each API function still includes an optional `body` property, but TypeScript's type checker will disallow properties that should go in the root of the object. A `querystring` parameter has also been added that behaves the same as `body`, but inserts its values into the request querystring.
+
+**Impact**<br> Some adjustments to API calls may be necessary for code that used a `body` property 8.x, especially to appease the TypeScript type checker, but it should not have any impact on any code that was not using a `body` property.
+
+**Action**<br> Check existing code for use of the `body` property, and move any properties that should be in the root object according to the API function's request type definition. If using TypeScript, the TypeScript type checker will surface most of these issues for you.
+::::
+
+::::{dropdown} Changes to API parameter collation into an HTTP request
+
+The logic for where each parameter in an API function call should be added to its HTTP request has been updated:
+
+1. If recognized as a `body` parameter according to the Elasticsearch specification, put it in the JSON body
+2. If recognized as a `path` parameter, put it in the URL path
+3. If recognized as a `query` parameter or a "common" query parameter (e.g. `pretty`, `error_trace`), put it in the querystring
+4. If not recognized, and this API accepts a JSON body, put it in the JSON body
+5. If not recognized and this API does not accept a JSON body, put it in the querystring
+
+The first two steps are identical in 8.x. The final three steps replace the logic from 8.x that put all unrecognized parameters in the querystring.
+
+**Impact**<br> Some parameters that were sent via querystring to Elasticsearch may be sent in the JSON request body, and vice versa.
+
+**Action**<br> If Elasticsearch sends back an error response due to a request not being valid, verify with the client's TypeScript type definitions, or via the docs, that the parameters your code passes are correct.
+::::
+
+::::{dropdown} Removal of the default 30-second timeout on all API calls
+
+The default 30-second timeout on all HTTP requests sent to Elasticsearch has been dropped in favor of having no timeout set at all. The previous behavior still works as it did when setting the `requestTimeout` value.
+
+See pull request [#2573](https://github.com/elastic/elasticsearch-js/pull/2573) for more information.
+
+**Impact**<br> Requests to Elasticsearch that used to time out after 30 seconds will now wait for as long as it takes for Elasticsearch to respond.
+
+**Action**<br> In environments where it is not ideal to wait for an API response indefinitely, manually setting the `requestTimeout` option when instantiating the client still works as it did in 8.x.
+::::

docs/release-notes/deprecations.md

@@ -5,18 +5,13 @@ navigation_title: "Deprecations"
 # Elasticsearch JavaScript Client deprecations [elasticsearch-javascript-client-deprecations]
 Over time, certain Elastic functionality becomes outdated and is replaced or removed. To help with the transition, Elastic deprecates functionality for a period before removal, giving you time to update your applications.
 
-Review the deprecated functionality for Elasticsearch JavaScript Client. While deprecations have no immediate impact, we strongly encourage you update your implementation after you upgrade. To learn how to upgrade, check out [Upgrade](docs-content://deploy-manage/upgrade.md).
+Review the deprecated functionality for the Elasticsearch JavaScript Client. While deprecations have no immediate impact, we strongly encourage you update your implementation after you upgrade. To learn how to upgrade, check out [Upgrade](docs-content://deploy-manage/upgrade.md).
 
-% ## Next version
+## 9.0.0 [elasticsearch-javascript-client-900-deprecations]
 
-% ::::{dropdown} Deprecation title
-% Description of the deprecation.
-% For more information, check [PR #](PR link).
-% **Impact**<br> Impact of deprecation. 
-% **Action**<br> Steps for mitigating deprecation impact.
-% ::::
+_No deprecations_
 
-% ## 9.0.0 [elasticsearch-javascript-client-900-deprecations]
+% ## Next version
 
 % ::::{dropdown} Deprecation title
 % Description of the deprecation.