AstraDBVectorStore(
self,
*,
collection_name: str,
| Name | Type | Description |
|---|---|---|
embedding | Embeddings | None | Default: Nonethe embeddings function or service to use.
This enables client-side embedding functions or calls to external
embedding providers. If |
collection_name* | str | name of the Astra DB collection to create/use. |
token | str | TokenProvider | None | Default: NoneAPI token for Astra DB usage, either in the form of a string
or a subclass of |
api_endpoint | str | None | Default: None |
environment | str | None | Default: None |
namespace | str | None | Default: None |
metric | str | None | Default: None |
batch_size | int | None | Default: None |
bulk_insert_batch_concurrency | int | None | Default: None |
bulk_insert_overwrite_concurrency | int | None | Default: None |
bulk_delete_concurrency | int | None | Default: None |
setup_mode | SetupMode | None | Default: None |
pre_delete_collection | bool | Default: False |
metadata_indexing_include | Iterable[str] | None | Default: None |
metadata_indexing_exclude | Iterable[str] | None | Default: None |
collection_indexing_policy | dict[str, Any] | None | Default: None |
collection_vector_service_options | VectorServiceOptions | None | Default: None |
collection_embedding_api_key | str | EmbeddingHeadersProvider | None | Default: None |
content_field | str | None | Default: None |
ignore_invalid_documents | bool | Default: False |
autodetect_collection | bool | Default: False |
ext_callers | list[tuple[str | None, str | None] | str | None] | None | Default: None |
component_name | str | Default: COMPONENT_NAME_VECTORSTORE |
api_options | APIOptions | None | Default: None |
collection_rerank | CollectionRerankOptions | RerankServiceOptions | None | Default: None |
collection_reranking_api_key | str | RerankingHeadersProvider | None | Default: None |
collection_lexical | str | dict[str, Any] | CollectionLexicalOptions | None | Default: None |
hybrid_search | HybridSearchMode | None | Default: None |
hybrid_limit_factor | float | dict[str, float] | HybridLimitFactorPrescription | None | Default: None |
| Name | Type |
|---|---|
| collection_name | str |
| embedding | Embeddings | None |
| token | str | TokenProvider | None |
| api_endpoint | str | None |
| environment | str | None |
| namespace | str | None |
| metric | str | None |
| batch_size | int | None |
| bulk_insert_batch_concurrency | int | None |
| bulk_insert_overwrite_concurrency | int | None |
| bulk_delete_concurrency | int | None |
| setup_mode | SetupMode | None |
| pre_delete_collection | bool |
| metadata_indexing_include | Iterable[str] | None |
| metadata_indexing_exclude | Iterable[str] | None |
| collection_indexing_policy | dict[str, Any] | None |
| collection_vector_service_options | VectorServiceOptions | None |
| collection_embedding_api_key | str | EmbeddingHeadersProvider | None |
| content_field | str | None |
| ignore_invalid_documents | bool |
| autodetect_collection | bool |
| ext_callers | list[tuple[str | None, str | None] | str | None] | None |
| component_name | str |
| api_options | APIOptions | None |
| collection_rerank | CollectionRerankOptions | RerankServiceOptions | None |
| collection_reranking_api_key | str | RerankingHeadersProvider | None |
| collection_lexical | str | dict[str, Any] | CollectionLexicalOptions | None |
| hybrid_search | HybridSearchMode | None |
| hybrid_limit_factor | float | dict[str, float] | HybridLimitFactorPrescription | None |
Completely delete the collection from the database.
Completely delete the collection from the database (as opposed
to clear, which empties it
only). Stored data is lost and unrecoverable, resources are freed.
Use with caution.
Completely delete the collection from the database.
Completely delete the collection from the database (as opposed to
aclear,
which empties it only).
Stored data is lost and unrecoverable, resources are freed.
Use with caution.
Return docs most similar to embedding vector with score.
Create an Astra DB vectorstore from a document list.
Utility method that defers to
from_texts.
Create an Astra DB vectorstore from a document list.
Utility method that defers to
afrom_texts.
A vector store which uses DataStax Astra DB as backend.
Setup:
Install the langchain-astradb package and head to the
AstraDB website, create an account, create a
new database and
create an application token.
pip install -qU langchain-astradbInstantiate:
Get your API endpoint and application token from the dashboard of your database.
Create a vector store and provide a LangChain embedding object for working with it:
import getpass
from langchain_astradb import AstraDBVectorStore
from langchain_openai import OpenAIEmbeddings
ASTRA_DB_API_ENDPOINT = getpass.getpass("ASTRA_DB_API_ENDPOINT = ")
ASTRA_DB_APPLICATION_TOKEN = getpass.getpass("ASTRA_DB_APPLICATION_TOKEN = ")
vector_store = AstraDBVectorStore(
collection_name="astra_vector_langchain",
embedding=OpenAIEmbeddings(),
api_endpoint=ASTRA_DB_API_ENDPOINT,
token=ASTRA_DB_APPLICATION_TOKEN,
)(Vectorize) Create a vector store where the embedding vector computation happens entirely on the server-side, using the vectorize feature:
import getpass
from astrapy.info import VectorServiceOptions
from langchain_astradb import AstraDBVectorStore
ASTRA_DB_API_ENDPOINT = getpass.getpass("ASTRA_DB_API_ENDPOINT = ")
ASTRA_DB_APPLICATION_TOKEN = getpass.getpass("ASTRA_DB_APPLICATION_TOKEN = ")
vector_store = AstraDBVectorStore(
collection_name="astra_vectorize_langchain",
api_endpoint=ASTRA_DB_API_ENDPOINT,
token=ASTRA_DB_APPLICATION_TOKEN,
collection_vector_service_options=VectorServiceOptions(
provider="nvidia",
model_name="NV-Embed-QA",
# authentication=..., # needed by some providers/models
),
)(Hybrid) The underlying Astra DB typically supports hybrid search
(i.e. lexical + vector ANN) to boost the results' accuracy.
This is provisioned and used automatically when available. For manual control,
use the collection_rerank and collection_lexical constructor parameters:
import getpass
from astrapy.info import (
CollectionLexicalOptions,
CollectionRerankOptions,
RerankServiceOptions,
VectorServiceOptions,
)
from langchain_astradb import AstraDBVectorStore
ASTRA_DB_API_ENDPOINT = getpass.getpass("ASTRA_DB_API_ENDPOINT = ")
ASTRA_DB_APPLICATION_TOKEN = getpass.getpass("ASTRA_DB_APPLICATION_TOKEN = ")
vector_store = AstraDBVectorStore(
collection_name="astra_vectorize_langchain",
# embedding=..., # needed unless using 'vectorize'
api_endpoint=ASTRA_DB_API_ENDPOINT,
token=ASTRA_DB_APPLICATION_TOKEN,
collection_vector_service_options=VectorServiceOptions(...), # see above
collection_lexical=CollectionLexicalOptions(analyzer="standard"),
collection_rerank=CollectionRerankOptions(
service=RerankServiceOptions(
provider="nvidia",
model_name="nvidia/llama-3.2-nv-rerankqa-1b-v2",
),
),
collection_reranking_api_key=..., # if needed by the model/setup
)Hybrid-related server upgrades may introduce a mismatch between the store
defaults and a pre-existing collection: in case one such mismatch is
reported (as a Data API "EXISTING_COLLECTION_DIFFERENT_SETTINGS" error),
the options to resolve are:
(1) use autodetect mode, (2) switch to setup_mode "OFF", or
(3) explicitly specify lexical and/or rerank settings in the vector
store constructor, to match the existing collection configuration. See
here
for more details.
(Autodetect) Let the vector store figure out the configuration (including vectorize and document encoding scheme on DB), by inspection of an existing collection:
import getpass
from langchain_astradb import AstraDBVectorStore
ASTRA_DB_API_ENDPOINT = getpass.getpass("ASTRA_DB_API_ENDPOINT = ")
ASTRA_DB_APPLICATION_TOKEN = getpass.getpass("ASTRA_DB_APPLICATION_TOKEN = ")
vector_store = AstraDBVectorStore(
collection_name="astra_existing_collection",
# embedding=..., # needed unless using 'vectorize'
api_endpoint=ASTRA_DB_API_ENDPOINT,
token=ASTRA_DB_APPLICATION_TOKEN,
autodetect_collection=True,
)(Non-Astra DB) This class can also target a non-Astra DB database, such as a self-deployed HCD, through the Data API:
import getpass
from astrapy.authentication import UsernamePasswordTokenProvider
from langchain_astradb import AstraDBVectorStore
vector_store = AstraDBVectorStore(
collection_name="astra_existing_collection",
# embedding=..., # needed unless using 'vectorize'
api_endpoint="http://localhost:8181",
token=UsernamePasswordTokenProvider(
username="user",
password="pwd",
),
collection_vector_service_options=..., # if 'vectorize'
)Add Documents:
Add one or more documents to the vector store. IDs are optional: if provided, and matching existing documents, an overwrite is performed.
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:
Delete one or more documents from the vector store by their IDs.
vector_store.delete(ids=["3"])Search:
Run a similarity search with a provided query string.
results = vector_store.similarity_search(query="thud", k=1)
for doc in results:
print(f"{doc.page_content}[{doc.metadata}]")thud[{"bar": "baz"}]
Search with filter:
Specify metadata filters for a search. Simple key: value syntax
for the filter means equality (with implied 'and').
More complex syntax is available, following the Data API specifications, see
(docs)[https://docs.datastax.com/en/astra-db-serverless/api-reference/filter-operator-collections.html].
results = vector_store.similarity_search(
query="thud", k=1, filter={"bar": "baz"}
)
for doc in results:
print(f"{doc.page_content}[{doc.metadata}]")thud[{"bar": "baz"}]
Search with score:
Search results are returned with their similarity score.
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}]")[SIM=0.916135] foo [{'baz': 'bar'}]
Async:
All methods come with their async counterpart (method name prepended with a).
# 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}]")[SIM=0.916135] foo [{'baz': 'bar'}]
Use as Retriever:
A Retriever can be spawned from the vector store for further usage.
retriever = vector_store.as_retriever(
search_type="similarity_score_threshold",
search_kwargs={"k": 1, "score_threshold": 0.5},
)
retriever.invoke("thud")[Document(metadata={"bar": "baz"}, page_content="thud")]
full URL to the API endpoint, such as
https://<DB-ID>-us-east1.apps.astra.datastax.com. If not provided,
the environment variable ASTRA_DB_API_ENDPOINT is inspected.
a string specifying the environment of the target Data API.
If omitted, defaults to "prod" (Astra DB production).
Other values are in astrapy.constants.Environment enum class.
namespace (aka keyspace) where the collection is created. If not provided, the environment variable ASTRA_DB_KEYSPACE is inspected. Defaults to the database's "default namespace".
similarity function to use out of those available in Astra DB. If left out, it will use Astra DB API's defaults (i.e. "cosine" - but, for performance reasons, "dot_product" is suggested if embeddings are normalized to one).
Size of document chunks for each individual insertion API request. If not provided, astrapy defaults are applied.
Number of threads or coroutines to insert batches concurrently.
Number of threads or coroutines in a batch to insert pre-existing entries.
Number of threads or coroutines for multiple-entry deletes.
mode used to create the collection (SYNC, ASYNC or OFF).
whether to delete the collection before creating it. If False and the collection already exists, the collection will be used as is.
an allowlist of the specific metadata subfields that should be indexed for later filtering in searches.
a denylist of the specific metadata subfields that should not be indexed for later filtering in searches.
a full "indexing" specification for what fields should be indexed for later filtering in searches. This dict must conform to to the API specifications (see https://docs.datastax.com/en/astra-db-serverless/api-reference/collection-indexes.html)
specifies the use of server-side
embeddings within Astra DB. If passing this parameter, embedding
cannot be provided.
for usage of server-side embeddings
within Astra DB. With this parameter one can supply an API Key
that will be passed to Astra DB with each data request.
This parameter can be either a string or a subclass of
astrapy.authentication.EmbeddingHeadersProvider.
This is useful when the service is configured for the collection,
but no corresponding secret is stored within
Astra's key management system.
name of the field containing the textual content
in the documents when saved on Astra DB. For vectorize collections,
this cannot be specified; for non-vectorize collection, defaults
to "content".
The special value "*" can be passed only if autodetect_collection=True.
In this case, the actual name of the key for the textual content is
guessed by inspection of a few documents from the collection, under the
assumption that the longer strings are the most likely candidates.
Please understand the limitations of this method and get some
understanding of your data before passing "*" for this parameter.
if False (default), exceptions are raised
when a document is found on the Astra DB collection that does
not have the expected shape. If set to True, such results
from the database are ignored and a warning is issued. Note
that in this case a similarity search may end up returning fewer
results than the required k.
if True, turns on autodetect behavior.
The store will look for an existing collection of the provided name
and infer the store settings from it. Default is False.
In autodetect mode, content_field can be given as "*", meaning
that an attempt will be made to determine it by inspection (unless
vectorize is enabled, in which case content_field is ignored).
In autodetect mode, the store not only determines whether embeddings
are client- or server-side, but - most importantly - switches
automatically between "nested" and "flat" representations of documents
on DB (i.e. having the metadata key-value pairs grouped in a
metadata field or spread at the documents' top-level). The former
scheme is the native mode of the AstraDBVectorStore; the store resorts
to the latter in case of vector collections populated with external
means (such as a third-party data import tool) before applying
an AstraDBVectorStore to them.
Note that the following parameters cannot be used if this is True:
metric, setup_mode, metadata_indexing_include,
metadata_indexing_exclude, collection_indexing_policy,
collection_vector_service_options.
one or more caller identities to identify Data API calls in the User-Agent header. This is a list of (name, version) pairs, or just strings if no version info is provided, which, if supplied, becomes the leading part of the User-Agent string in all API requests related to this component.
the string identifying this specific component in the
stack of usage info passed as the User-Agent string to the Data API.
Defaults to "langchain_vectorstore", but can be overridden if this
component actually serves as the building block for another component
(such as when the vector store is used within a GraphRetriever).
an instance of astrapy.utils.api_options.APIOptions that
can be supplied to customize the interaction with the Data API
regarding serialization/deserialization, timeouts, custom headers
and so on. The provided options are applied on top of settings already
tailored to this library, and if specified will take precedence.
Passing None (default) means no customization is requested.
Refer to the astrapy documentation for details.
providing reranking settings is necessary to run
hybrid searches for similarity. This parameter can be an instance
of the astrapy classes CollectionRerankOptions or
RerankServiceOptions.
for usage of server-side reranking services
within Astra DB. With this parameter one can supply an API Key
that will be passed to Astra DB with each data request.
This parameter can be either a string or a subclass of
astrapy.authentication.RerankingHeadersProvider.
This is useful when the service is configured for the collection,
but no corresponding secret is stored within
Astra's key management system.
configuring a lexical analyzer is necessary to run
lexical and hybrid searches. This parameter can be a string or dict,
which is then passed as-is for the "analyzer" field of a
createCollection's "$lexical.analyzer" value, or a ready-made
astrapy CollectionLexicalOptions object.
whether similarity searches should be run as Hybrid searches or not. Values are DEFAULT, ON or OFF. In case of DEFAULT, searches are performed as permitted by the collection configuration, with a preference for hybrid search. Forcing this setting to ON for a non-hybrid-enabled collection would result in a server error when running searches.
subsearch "limit" specification for hybrid searches.
If omitted, hybrid searches do not specify it and leave the Data API
to use its defaults.
If a floating-point positive number is provided: each subsearch
participating in the hybrid search (i.e. both the vector-based ANN
and the lexical-based) will be requested to fecth up to
int(k*hybrid_limit_factor) items, where k is the desired result
count from the whole search.
If a HybridLimitFactorPrescription is provided (see the class
docstring for details), separate factors are applied to the vector
and the lexical subsearches. Alternatively, a simple dictionary
with keys "$lexical" and "$vector" achieves the same effect.