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.910 runs
installs and imports cleanly · install 0.0s · import 2.802s · 238MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 16.0s · import 2.648s · 244MB
240MB installed
● package 240MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AstraDBVectorStore
✓ from langchain_astradb import AstraDBVectorStore
AstraDBChatMessageHistory
✓ from langchain_astradb import AstraDBChatMessageHistory
AstraDBCache
✓ from langchain_astradb import AstraDBCache
AstraDBSemanticCache
✓ from langchain_astradb import AstraDBSemanticCache
AstraDBLoader
✓ from langchain_astradb import AstraDBLoader
This quickstart demonstrates how to initialize `AstraDBVectorStore` with OpenAI embeddings, add documents to a collection, and perform a similarity search. Ensure `ASTRA_DB_API_ENDPOINT`, `ASTRA_DB_APPLICATION_TOKEN`, and `OPENAI_API_KEY` are set as environment variables.
import os
from langchain_astradb import AstraDBVectorStore
from langchain_openai import OpenAIEmbeddings
from langchain_core.documents import Document
# Ensure you have your Astra DB credentials and OpenAI API key set as environment variables
ASTRA_DB_API_ENDPOINT = os.environ.get('ASTRA_DB_API_ENDPOINT', 'https://your.api.endpoint')
ASTRA_DB_APPLICATION_TOKEN = os.environ.get('ASTRA_DB_APPLICATION_TOKEN', 'AstraCS:...')
OPENAI_API_KEY = os.environ.get('OPENAI_API_KEY', 'sk-...')
if not all([ASTRA_DB_API_ENDPOINT, ASTRA_DB_APPLICATION_TOKEN, OPENAI_API_KEY]):
print("Please set ASTRA_DB_API_ENDPOINT, ASTRA_DB_APPLICATION_TOKEN, and OPENAI_API_KEY environment variables.")
else:
print("Connecting to Astra DB Vector Store...")
embeddings = OpenAIEmbeddings(api_key=OPENAI_API_KEY)
# Initialize the vector store
vector_store = AstraDBVectorStore(
embedding=embeddings,
collection_name="my_documents_collection",
api_endpoint=ASTRA_DB_API_ENDPOINT,
token=ASTRA_DB_APPLICATION_TOKEN,
)
# Add documents
docs = [
Document(page_content="LangChain provides tools for building LLM applications.", metadata={"source": "langchain"}),
Document(page_content="Astra DB is a serverless vector-capable database.", metadata={"source": "astradb"})
]
vector_store.add_documents(docs)
print(f"Added {len(docs)} documents to the collection.")
# Perform a similarity search
query = "What is Astra DB?"
results = vector_store.similarity_search(query, k=1)
print(f"\nSimilarity search results for '{query}':")
for doc in results:
print(f"- Content: {doc.page_content}, Source: {doc.metadata.get('source')}")
Debug
Known issues
breakingThe `langchain-astradb` package replaces deprecated Astra DB classes previously found under `langchain_community.*`. Migrating to the dedicated `langchain-astradb` package is strongly advised for the latest features, fixes, and compatibility with modern `astrapy` versions.fixUpdate `langchain` to `0.1.x` or higher, and replace imports like `from langchain_community.vectorstores import AstraDBVectorStore` with `from langchain_astradb import AstraDBVectorStore`. Refer to the official migration guides.
affects: <1.0.0 of langchain-astradb; older versions of langchain
gotchaInitializing an `AstraDBVectorStore` on an existing collection may fail if the collection's configuration (e.g., indexing settings, hybrid search enablement) differs from the default or requested settings. The Data API returns an `EXISTING_COLLECTION_DIFFERENT_SETTINGS` error.fixEnsure the collection is created with compatible settings, or explicitly instruct the vector store not to create the collection if it exists. For example, `AstraDBVectorStore(..., setup_mode=langchain_astradb.utils.astradb.SetupMode.OFF)` will prevent collection creation, using it as-is.
affects: All versions of `langchain-astradb`
gotchaIncorrect or invalid credentials (`ASTRA_DB_API_ENDPOINT`, `ASTRA_DB_APPLICATION_TOKEN`) or issues with the secure bundle path for self-managed Cassandra can lead to connection errors.fixDouble-check that all connection parameters are correct and have sufficient permissions. If using an application token, ensure it's correctly provided and not confused with client ID/secret from older `cassandra-driver` setups.
affects: All versions of `langchain-astradb`
Upgrade
Version history
1.0.0latest on PyPI · released Oct 23, 2025
Audit
Dependencies
langchainrequiredCore LangChain framework, required for building LLM applications.
langchain-corerequiredBase abstractions for the LangChain ecosystem, a dependency of LangChain.
astrapyrequiredPythonic client for DataStax Astra DB, used by langchain-astradb for database interactions.
langchain-openaioptionalOpenAI embeddings or chat models, commonly used with vector stores.