From a0453ebcf5ba0aa6bcb5c9bf7c81bc87d84e7a40 Mon Sep 17 00:00:00 2001
From: sergerdn <64213648+sergerdn@users.noreply.github.com>
Date: Wed, 29 Mar 2023 23:20:29 +0300
Subject: [PATCH] docs: update docstrings in ElasticVectorSearch class (#2141)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This merge includes updated comments in the ElasticVectorSearch class to
provide information on how to connect to `Elasticsearch` instances that
require login credentials, including Elastic Cloud, without any
functional changes.

The `ElasticVectorSearch` class now inherits from the `ABC` abstract
base class, which does not break or change any functionality. This
allows for easy subclassing and creation of custom implementations in
the future or for any users, especially for me 😄

I confirm that before pushing these changes, I ran:
```bash
make format && make lint
```

To ensure that the new documentation is rendered correctly I ran
```bash
make docs_build
```

To ensure that the new documentation has no broken links, I ran a check
```bash
make docs_linkcheck
```


![Capture](https://user-images.githubusercontent.com/64213648/228541688-38f17c7b-b012-4678-86b9-4dd607469062.JPG)

Also take a look at https://github.com/hwchase17/langchain/issues/1865

P.S. Sorry for spamming you with force-pushes. In the future, I will be
smarter.
---
 .../vectorstores/elastic_vector_search.py     | 71 +++++++++++++++++--
 1 file changed, 67 insertions(+), 4 deletions(-)

diff --git a/langchain/vectorstores/elastic_vector_search.py b/langchain/vectorstores/elastic_vector_search.py
index 57a73dcdd6..537dfb0970 100644
--- a/langchain/vectorstores/elastic_vector_search.py
+++ b/langchain/vectorstores/elastic_vector_search.py
@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import uuid
+from abc import ABC
 from typing import Any, Dict, Iterable, List, Optional
 
 from langchain.docstore.document import Document
@@ -31,19 +32,81 @@ def _default_script_query(query_vector: List[float]) -> Dict:
     }
 
 
-class ElasticVectorSearch(VectorStore):
+# ElasticVectorSearch is a concrete implementation of the abstract base class
+# VectorStore, which defines a common interface for all vector database
+# implementations. By inheriting from the ABC class, ElasticVectorSearch can be
+# defined as an abstract base class itself, allowing the creation of subclasses with
+# their own specific implementations. If you plan to subclass ElasticVectorSearch,
+# you can inherit from it and define your own implementation of the necessary methods
+# and attributes.
+class ElasticVectorSearch(VectorStore, ABC):
     """Wrapper around Elasticsearch as a vector database.
 
+    To connect to an Elasticsearch instance that does not require
+    login credentials, pass the Elasticsearch URL and index name along with the
+    embedding object to the constructor.
+
     Example:
         .. code-block:: python
 
             from langchain import ElasticVectorSearch
+            from langchain.embeddings import OpenAIEmbeddings
+
+            embedding = OpenAIEmbeddings()
             elastic_vector_search = ElasticVectorSearch(
-                "http://localhost:9200",
-                "embeddings",
-                embedding
+                elasticsearch_url="http://localhost:9200",
+                index_name="test_index",
+                embedding=embedding
             )
 
+
+    To connect to an Elasticsearch instance that requires login credentials,
+    including Elastic Cloud, use the Elasticsearch URL format
+    https://username:password@es_host:9243. For example, to connect to Elastic
+    Cloud, create the Elasticsearch URL with the required authentication details and
+    pass it to the ElasticVectorSearch constructor as the named parameter
+    elasticsearch_url.
+
+    You can obtain your Elastic Cloud URL and login credentials by logging in to the
+    Elastic Cloud console at https://cloud.elastic.co, selecting your deployment, and
+    navigating to the "Deployments" page.
+
+    To obtain your Elastic Cloud password for the default "elastic" user:
+
+    1. Log in to the Elastic Cloud console at https://cloud.elastic.co
+    2. Go to "Security" > "Users"
+    3. Locate the "elastic" user and click "Edit"
+    4. Click "Reset password"
+    5. Follow the prompts to reset the password
+
+    The format for Elastic Cloud URLs is
+    https://username:password@cluster_id.region_id.gcp.cloud.es.io:9243.
+
+    Example:
+        .. code-block:: python
+
+            from langchain import ElasticVectorSearch
+            from langchain.embeddings import OpenAIEmbeddings
+
+            embedding = OpenAIEmbeddings()
+
+            elastic_host = "cluster_id.region_id.gcp.cloud.es.io"
+            elasticsearch_url = f"https://username:password@{elastic_host}:9243"
+            elastic_vector_search = ElasticVectorSearch(
+                elasticsearch_url=elasticsearch_url,
+                index_name="test_index",
+                embedding=embedding
+            )
+
+    Args:
+        elasticsearch_url (str): The URL for the Elasticsearch instance.
+        index_name (str): The name of the Elasticsearch index for the embeddings.
+        embedding (Embeddings): An object that provides the ability to embed text.
+                It should be an instance of a class that subclasses the Embeddings
+                abstract base class, such as OpenAIEmbeddings()
+
+    Raises:
+        ValueError: If the elasticsearch python package is not installed.
     """
 
     def __init__(self, elasticsearch_url: str, index_name: str, embedding: Embeddings):