# AsyncElasticsearchStore

> **Class** in `langchain_elasticsearch`

📖 [View in docs](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore)

`Elasticsearch` vector store.

## Signature

```python
AsyncElasticsearchStore(
    self,
    index_name: str,
    *,
    embedding: Optional[Embeddings] = None,
    client: Optional[AsyncElasticsearch] = None,
    es_url: Optional[str] = None,
    es_cloud_id: Optional[str] = None,
    es_user: Optional[str] = None,
    es_api_key: Optional[str] = None,
    es_password: Optional[str] = None,
    vector_query_field: str = 'vector',
    query_field: str = 'text',
    distance_strategy: Optional[Literal[DistanceStrategy.COSINE, DistanceStrategy.DOT_PRODUCT, DistanceStrategy.EUCLIDEAN_DISTANCE, DistanceStrategy.MAX_INNER_PRODUCT]] = None,
    strategy: Union[BaseRetrievalStrategy, AsyncRetrievalStrategy] = ApproxRetrievalStrategy(),
    es_params: Optional[Dict[str, Any]] = None,
    custom_index_settings: Optional[Dict[str, Any]] = None,
    num_dimensions: Optional[int] = None,
    metadata_mappings: Optional[Dict[str, Any]] = None,
)
```

## Description

**Setup:**

Install `langchain_elasticsearch` and start Elasticsearch locally using
the start-local script.

```bash
pip install -qU langchain_elasticsearch
curl -fsSL https://elastic.co/start-local | sh
```

This will create an `elastic-start-local` folder. To start Elasticsearch
and Kibana:
```bash
cd elastic-start-local
./start.sh
```

Elasticsearch will be available at `http://localhost:9200`. The password
for the `elastic` user and API key are stored in the `.env` file in the
`elastic-start-local` folder.

Key init args — indexing params:
    index_name: str
        Name of the index to create.
    embedding: Embeddings
        Embedding function to use.
    custom_index_settings: Optional[Dict[str, Any]]
        A dictionary of custom settings for the index.
        This can include configurations like the number of shards, number of replicas,
        analysis settings, and other index-specific settings. If not provided, default
        settings will be used. Note that if the same setting is provided by both the user
        and the strategy, will raise an error.

Key init args — client params:
    client: Optional[Elasticsearch or AsyncElasticsearch]
        Pre-existing Elasticsearch connection. Either provide this OR credentials.
    es_url: Optional[str]
        URL of the Elasticsearch instance to connect to.
    es_cloud_id: Optional[str]
        Cloud ID of the Elasticsearch instance to connect to.
    es_user: Optional[str]
        Username to use when connecting to Elasticsearch.
    es_password: Optional[str]
        Password to use when connecting to Elasticsearch.
    es_api_key: Optional[str]
        API key to use when connecting to Elasticsearch.
    es_params: Optional[Dict[str, Any]]
        Additional parameters for the Elasticsearch client.

**Instantiate:**

```python
from langchain_elasticsearch import ElasticsearchStore
from langchain_openai import OpenAIEmbeddings

vector_store = ElasticsearchStore(
    index_name="langchain-demo",
    embedding=OpenAIEmbeddings(),
    es_url="http://localhost:9200",
)
```

Instantiate with API key (URL):
    ```python
    from langchain_elasticsearch import ElasticsearchStore
    from langchain_openai import OpenAIEmbeddings

    store = ElasticsearchStore(
        index_name="langchain-demo",
        embedding=OpenAIEmbeddings(),
        es_url="http://localhost:9200",
        es_api_key="your-api-key"
    )
    ```

Instantiate with username/password (URL):
    ```python
    from langchain_elasticsearch import ElasticsearchStore
    from langchain_openai import OpenAIEmbeddings

    store = ElasticsearchStore(
        index_name="langchain-demo",
        embedding=OpenAIEmbeddings(),
        es_url="http://localhost:9200",
        es_user="elastic",
        es_password="password"
    )
    ```

If you want to use a cloud hosted Elasticsearch instance, you can pass in the
cloud_id argument instead of the es_url argument.

Instantiate from cloud (with username/password):
    ```python
    from langchain_elasticsearch.vectorstores import ElasticsearchStore
    from langchain_openai import OpenAIEmbeddings

    store = ElasticsearchStore(
        embedding=OpenAIEmbeddings(),
        index_name="langchain-demo",
        es_cloud_id="<cloud_id>",
        es_user="elastic",
        es_password="<password>"
    )
    ```

Instantiate from cloud (with API key):
    ```python
    from langchain_elasticsearch.vectorstores import ElasticsearchStore
    from langchain_openai import OpenAIEmbeddings

    store = ElasticsearchStore(
        embedding=OpenAIEmbeddings(),
        index_name="langchain-demo",
        es_cloud_id="<cloud_id>",
        es_api_key="your-api-key"
    )
    ```

You can also connect to an existing Elasticsearch instance by passing in a
pre-existing Elasticsearch connection via the client argument.

**Instantiate from existing connection:**

```python
from langchain_elasticsearch.vectorstores import ElasticsearchStore
from langchain_openai import OpenAIEmbeddings
from elasticsearch import Elasticsearch

client = Elasticsearch("http://localhost:9200")

store = ElasticsearchStore(
    embedding=OpenAIEmbeddings(),
    index_name="langchain-demo",
    client=client
)
```

Class methods (afrom_texts, afrom_documents) accept the same connection options:

**Instantiate from texts with credentials:**

```python
from langchain_elasticsearch import ElasticsearchStore

store = await ElasticsearchStore.afrom_texts(
    texts=["text1", "text2"],
    index_name="langchain-demo",
    es_url="http://localhost:9200"
)
```

**Instantiate from texts with client:**

```python
from langchain_elasticsearch import ElasticsearchStore
from elasticsearch import Elasticsearch

client = Elasticsearch("http://localhost:9200")
store = await ElasticsearchStore.afrom_texts(
    texts=["text1", "text2"],
    index_name="langchain-demo",
    client=client
)
```

**Add Documents:**

```python
from langchain_core.documents import Document

document_1 = Document(page_content="foo", metadata={"baz": "bar"})
document_2 = Document(page_content="thud", metadata={"bar": "baz"})
document_3 = Document(page_content="i will be deleted :(")

documents = [document_1, document_2, document_3]
ids = ["1", "2", "3"]
vector_store.add_documents(documents=documents, ids=ids)
```

**Delete Documents:**

```python
vector_store.delete(ids=["3"])
```

**Search:**

```python
results = vector_store.similarity_search(query="thud",k=1)
for doc in results:
    print(f"* {doc.page_content} [{doc.metadata}]")
```

```python
* thud [{'bar': 'baz'}]
```

**Search with filter:**

```python
results = vector_store.similarity_search(query="thud",k=1,filter=[{"term": {"metadata.bar.keyword": "baz"}}])
for doc in results:
    print(f"* {doc.page_content} [{doc.metadata}]")
```

```python
* thud [{'bar': 'baz'}]
```

**Search with score:**

```python
results = vector_store.similarity_search_with_score(query="qux",k=1)
for doc, score in results:
    print(f"* [SIM={score:3f}] {doc.page_content} [{doc.metadata}]")
```

```python
* [SIM=0.916092] foo [{'baz': 'bar'}]
```

**Async:**

```python
from langchain_elasticsearch import AsyncElasticsearchStore

vector_store = AsyncElasticsearchStore(...)

# add documents
await vector_store.aadd_documents(documents=documents, ids=ids)

# delete documents
await vector_store.adelete(ids=["3"])

# search
results = vector_store.asimilarity_search(query="thud",k=1)

# search with score
results = await vector_store.asimilarity_search_with_score(query="qux",k=1)
for doc,score in results:
    print(f"* [SIM={score:3f}] {doc.page_content} [{doc.metadata}]")
```

```python
* [SIM=0.916092] foo [{'baz': 'bar'}]
```

Use as Retriever:

    ```bash
    pip install "elasticsearch[vectorstore_mmr]"
    ```

    ```python
    retriever = vector_store.as_retriever(
        search_type="mmr",
        search_kwargs={"k": 1, "fetch_k": 2, "lambda_mult": 0.5},
    )
    retriever.invoke("thud")
    ```

    ```python
    [Document(metadata={'bar': 'baz'}, page_content='thud')]
    ```

**Advanced Uses:**

ElasticsearchStore by default uses the ApproxRetrievalStrategy, which uses the
HNSW algorithm to perform approximate nearest neighbor search. This is the
fastest and most memory efficient algorithm.

If you want to use the Brute force / Exact strategy for searching vectors, you
can pass in the ExactRetrievalStrategy to the ElasticsearchStore constructor.

**Use ExactRetrievalStrategy:**

```python
from langchain_elasticsearch.vectorstores import ElasticsearchStore
from langchain_openai import OpenAIEmbeddings

store = ElasticsearchStore(
    embedding=OpenAIEmbeddings(),
    index_name="langchain-demo",
    es_url="http://localhost:9200",
    strategy=ElasticsearchStore.ExactRetrievalStrategy()
)
```

Both strategies require that you know the similarity metric you want to use
when creating the index. The default is cosine similarity, but you can also
use dot product or euclidean distance.

**Use dot product similarity:**

```python
from langchain_elasticsearch.vectorstores import ElasticsearchStore
from langchain_openai import OpenAIEmbeddings
from langchain_elasticsearch import DistanceStrategy

store = ElasticsearchStore(
    "langchain-demo",
    embedding=OpenAIEmbeddings(),
    es_url="http://localhost:9200",
    distance_strategy="DOT_PRODUCT"
)
```

## Extends

- `VectorStore`

## Constructors

```python
__init__(
    self,
    index_name: str,
    *,
    embedding: Optional[Embeddings] = None,
    client: Optional[AsyncElasticsearch] = None,
    es_url: Optional[str] = None,
    es_cloud_id: Optional[str] = None,
    es_user: Optional[str] = None,
    es_api_key: Optional[str] = None,
    es_password: Optional[str] = None,
    vector_query_field: str = 'vector',
    query_field: str = 'text',
    distance_strategy: Optional[Literal[DistanceStrategy.COSINE, DistanceStrategy.DOT_PRODUCT, DistanceStrategy.EUCLIDEAN_DISTANCE, DistanceStrategy.MAX_INNER_PRODUCT]] = None,
    strategy: Union[BaseRetrievalStrategy, AsyncRetrievalStrategy] = ApproxRetrievalStrategy(),
    es_params: Optional[Dict[str, Any]] = None,
    custom_index_settings: Optional[Dict[str, Any]] = None,
    num_dimensions: Optional[int] = None,
    metadata_mappings: Optional[Dict[str, Any]] = None,
)
```

| Name | Type |
|------|------|
| `index_name` | `str` |
| `embedding` | `Optional[Embeddings]` |
| `client` | `Optional[AsyncElasticsearch]` |
| `es_url` | `Optional[str]` |
| `es_cloud_id` | `Optional[str]` |
| `es_user` | `Optional[str]` |
| `es_api_key` | `Optional[str]` |
| `es_password` | `Optional[str]` |
| `vector_query_field` | `str` |
| `query_field` | `str` |
| `distance_strategy` | `Optional[Literal[DistanceStrategy.COSINE, DistanceStrategy.DOT_PRODUCT, DistanceStrategy.EUCLIDEAN_DISTANCE, DistanceStrategy.MAX_INNER_PRODUCT]]` |
| `strategy` | `Union[BaseRetrievalStrategy, AsyncRetrievalStrategy]` |
| `es_params` | `Optional[Dict[str, Any]]` |
| `custom_index_settings` | `Optional[Dict[str, Any]]` |
| `num_dimensions` | `Optional[int]` |
| `metadata_mappings` | `Optional[Dict[str, Any]]` |


## Properties

- `embedding`
- `client`
- `query_field`
- `vector_query_field`
- `embeddings`

## Methods

- [`aclose()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/aclose)
- [`asimilarity_search()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/asimilarity_search)
- [`amax_marginal_relevance_search()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/amax_marginal_relevance_search)
- [`asimilarity_search_with_score()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/asimilarity_search_with_score)
- [`asimilarity_search_by_vector_with_relevance_scores()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/asimilarity_search_by_vector_with_relevance_scores)
- [`adelete()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/adelete)
- [`aadd_texts()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/aadd_texts)
- [`aadd_embeddings()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/aadd_embeddings)
- [`afrom_texts()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/afrom_texts)
- [`afrom_documents()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/afrom_documents)
- [`ExactRetrievalStrategy()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/ExactRetrievalStrategy)
- [`ApproxRetrievalStrategy()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/ApproxRetrievalStrategy)
- [`SparseVectorRetrievalStrategy()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/SparseVectorRetrievalStrategy)
- [`BM25RetrievalStrategy()`](https://reference.langchain.com/python/langchain-elasticsearch/_async/vectorstores/AsyncElasticsearchStore/BM25RetrievalStrategy)

---

[View source on GitHub](https://github.com/langchain-ai/langchain-elastic/blob/c669a094f035939b26089ef05015d28a953a75b6/libs/elasticsearch/langchain_elasticsearch/_async/vectorstores.py#L72)