Registry /
llm-agents / langchain-elasticsearch
Install & Compatibility
Where this runs
tested against v1.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 2.775s · 176.1MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 11.8s · import 2.576s · 180MB
182MB installed
● package 182MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ElasticsearchStore
✓ from langchain_elasticsearch import ElasticsearchStore
✗ from langchain.vectorstores.elasticsearch import ElasticsearchStore
The Elasticsearch vectorstore was moved to its own dedicated package in LangChain 0.1.0+.
ElasticsearchChatMessageHistory
✓ from langchain_elasticsearch import ElasticsearchChatMessageHistory
ElasticsearchEmbeddingsCache
✓ from langchain_elasticsearch import ElasticsearchEmbeddingsCache
This quickstart demonstrates how to initialize `ElasticsearchStore` with OpenAI embeddings, add documents, and perform a similarity search. Ensure you have Elasticsearch running and the `ELASTICSEARCH_URL` and `OPENAI_API_KEY` environment variables set. Install `langchain-openai` for OpenAI embeddings.
import os
from langchain_elasticsearch import ElasticsearchStore
from langchain_openai import OpenAIEmbeddings # Or any other Embedding class
from langchain_core.documents import Document
# Set up Elasticsearch client URL and OpenAI API Key
ELASTICSEARCH_URL = os.environ.get("ELASTICSEARCH_URL", "http://localhost:9200")
OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", "")
if not OPENAI_API_KEY:
print("Warning: OPENAI_API_KEY not set. Using a placeholder for demonstration.")
# In a real application, you would ensure this is set or use a mock.
embeddings = None # Prevent actual API calls
else:
embeddings = OpenAIEmbeddings(openai_api_key=OPENAI_API_KEY)
if embeddings:
# Initialize ElasticsearchStore
# Ensure Elasticsearch is running and accessible at ELASTICSEARCH_URL
vectorstore = ElasticsearchStore(
es_url=ELASTICSEARCH_URL,
index_name="langchain-test-index",
embedding=embeddings,
# num_dimensions is crucial for correct vector mapping
num_dimensions=1536 # For OpenAI embeddings
)
# Add documents
docs = [
Document(page_content="The quick brown fox jumps over the lazy dog", metadata={"source": "lorem"}),
Document(page_content="A dog barks at the moon", metadata={"source": "nature"}),
]
vectorstore.add_documents(docs)
# Perform a similarity search
query = "What is a fox?"
results = vectorstore.similarity_search(query, k=1)
print(f"\nSimilarity search results for '{query}':")
for doc in results:
print(f"- Content: {doc.page_content}, Metadata: {doc.metadata}")
else:
print("Embeddings not initialized due to missing API key. Skipping vector store example.")
Debug
Known issues
breakingThe Elasticsearch integration was extracted from the main `langchain` package into `langchain-elasticsearch`. This changes import paths.fixUpdate your imports from `from langchain.vectorstores.elasticsearch import ElasticsearchStore` to `from langchain_elasticsearch import ElasticsearchStore` (and similar for other components).
affects: langchain<0.1.0 to langchain-elasticsearch>=0.1.0
gotchaWhen creating a new vector index in Elasticsearch, it is highly recommended to explicitly provide the `num_dimensions` parameter for your embeddings to `ElasticsearchStore` to ensure correct vector field mapping.fixInitialize `ElasticsearchStore(..., num_dimensions=YOUR_EMBEDDING_DIMENSIONS)`.
affects: >=0.4.0
gotchaAsynchronous methods (e.g., `aadd_documents`, `asimilarity_search`) were introduced in version `0.3.1`. Attempting to use them on earlier versions will result in an `AttributeError`.fixUpgrade `langchain-elasticsearch` to version `0.3.1` or higher to use asynchronous functionalities.
affects: <0.3.1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'langchain.vectorstores.elasticsearch'
You are trying to import the Elasticsearch vectorstore from the old `langchain` path, but the integration has moved to its own package.
fixInstall `langchain-elasticsearch` and update your import to `from langchain_elasticsearch import ElasticsearchStore`.
elasticsearch.exceptions.ConnectionError: Connection refused
The Elasticsearch client cannot connect to the specified URL, likely because Elasticsearch is not running, is on a different port, or behind a firewall.
fixEnsure your Elasticsearch instance is running and accessible from where your Python code is executed. Verify `ELASTICSEARCH_URL` is correct (e.g., `http://localhost:9200`).
TypeError: 'NoneType' object is not subscriptable
This often occurs during vector search if embeddings are not properly initialized or `num_dimensions` was not set, leading to issues with vector processing in Elasticsearch.
fixEnsure your embedding model is correctly instantiated and provides valid embeddings. If creating a new index, specify `num_dimensions` in `ElasticsearchStore` initialization.
Upgrade
Version history
1.0.0latest on PyPI · released Dec 16, 2025
Audit
Dependencies
elasticsearchrequiredRequired for connecting to Elasticsearch.
langchain-corerequiredUnderpins all LangChain integrations.
langchain-openaioptionalOptional, for using OpenAI embeddings. Substitute with any other embedding provider.