Vector Store API

Complete API reference for AsyncCockroachDBVectorStore and CockroachDBVectorStore.

langchain_cockroachdb.async_vectorstore.AsyncCockroachDBVectorStore

Bases: VectorStore

Async vector store using CockroachDB native VECTOR type and C-SPANN indexes.

Every database call retries transient CockroachDB errors under retry_policy, which defaults to the engine's policy. Every write is an idempotent UPSERT or DELETE, so retrying after an ambiguous result is safe.

embeddings property

Get embeddings model.

retry_backoff_multiplier property

Shorthand for retry_policy.backoff_multiplier.

retry_initial_backoff property

Shorthand for retry_policy.initial_backoff.

retry_jitter property

True when retry_policy.jitter is above zero.

retry_max_attempts property

Shorthand for retry_policy.max_attempts.

retry_max_backoff property

Shorthand for retry_policy.max_backoff.

__init__(engine, embeddings, collection_name, *, schema='public', distance_strategy=DistanceStrategy.COSINE, content_column='content', embedding_column='embedding', metadata_column='metadata', id_column='id', namespace_column='namespace', namespace=None, hybrid_search_config=None, batch_size=100, retry_policy=None, retry_max_attempts=None, retry_initial_backoff=None, retry_max_backoff=None, retry_backoff_multiplier=None, retry_jitter=None)

Initialize async vector store.

Parameters:

Name	Type	Description	Default
engine	CockroachDBEngine	CockroachDBEngine instance	required
embeddings	Embeddings	Embeddings model	required
collection_name	str	Table name for this collection	required
schema	str	Database schema (default: public)	'public'
distance_strategy	DistanceStrategy	Distance metric for similarity (default: COSINE)	COSINE
content_column	str	Name of content column (default: content)	'content'
embedding_column	str	Name of embedding column (default: embedding)	'embedding'
metadata_column	str	Name of metadata column (default: metadata)	'metadata'
id_column	str	Name of ID column (default: id)	'id'
namespace_column	str	Name of namespace column (default: namespace)	'namespace'
namespace	str | None	Namespace for multi-tenancy isolation. When set, all operations are scoped to this namespace. Requires the table to have a namespace column (created with namespace_column param in ainit_vectorstore_table). Default: None (no namespace filtering, backward compatible).	None
hybrid_search_config	HybridSearchConfig | None	Optional hybrid search configuration	None
batch_size	int	Rows per insert statement; CockroachDB works best with smaller VECTOR batches (default: 100)	100
retry_policy	RetryPolicy | None	How operations retry (default: the engine's policy)	None
retry_max_attempts	int | None	Override for retry_policy.max_attempts	None
retry_initial_backoff	float | None	Override for retry_policy.initial_backoff	None
retry_max_backoff	float | None	Override for retry_policy.max_backoff	None
retry_backoff_multiplier	float | None	Override for retry_policy.backoff_multiplier	None
retry_jitter	bool | None	Override for retry_policy.jitter (True means 0.5)	None

aadd_embeddings(texts, embeddings, metadatas=None, ids=None, **kwargs) async

Add texts with precomputed embeddings.

Parameters:

Name	Type	Description	Default
texts	Iterable[str]	Texts to add	required
embeddings	list[list[float]]	One embedding per text	required
metadatas	list[dict] | None	Optional metadata for each text	None
ids	list[str] | None	Optional IDs for texts	None
**kwargs	Any	Additional arguments (batch_size override supported)	{}

Returns:

Type	Description
list[str]	List of IDs for added texts

Raises:

Type	Description
ValueError	When using a namespace, if any caller-supplied id already belongs to a different namespace. This check writes nothing. If a concurrent writer claims an id in another namespace between the check and the write, the write also raises. Earlier batches and the batch's other rows (same-namespace updates and new rows) are already committed when this error is raised.

aadd_texts(texts, metadatas=None, ids=None, **kwargs) async

Embed and add texts, retrying transient errors per batch.

Parameters:

Name	Type	Description	Default
texts	Iterable[str]	Texts to add	required
metadatas	list[dict] | None	Optional metadata for each text	None
ids	list[str] | None	Optional IDs for texts	None
**kwargs	Any	Additional arguments (batch_size override supported)	{}

Returns:

Type	Description
list[str]	List of IDs for added texts

Raises:

Type	Description
ValueError	When using a namespace, if any caller-supplied id already belongs to a different namespace. This check writes nothing. If a concurrent writer claims an id in another namespace between the check and the write, the write also raises. Earlier batches and the batch's other rows (same-namespace updates and new rows) are already committed when this error is raised.

aapply_vector_index(index, prefix_columns=None) async

Apply a C-SPANN vector index.

When an index with the same name exists, it is left alone. A WARNING names each difference from the requested index: the operator class, the prefix columns (order and count) and any partition size you set. Applying the same index again logs nothing.

Parameters:

Name	Type	Description	Default
index	CSPANNIndex	Index configuration	required
prefix_columns	list[str] | None	Optional prefix columns for multi-tenant indexes	None

add_texts(texts, metadatas=None, **kwargs)

Sync wrapper - not implemented for async-only store.

adelete(ids=None, **kwargs) async

Delete documents by IDs.

Parameters:

Name	Type	Description	Default
ids	list[str] | None	Document IDs to delete	None
**kwargs	Any	Additional arguments	{}

Returns:

Type	Description
bool | None	True if successful

adrop_vector_index(index=None) async

Drop a vector index.

Parameters:

Name	Type	Description	Default
index	CSPANNIndex | None	Index configuration (defaults to CSPANNIndex() to drop the default-named index)	None

afrom_texts(texts, embedding, metadatas=None, *, ids=None, engine=None, connection_string=None, collection_name='langchain_vectors', **kwargs) async classmethod

Create the table if needed, then add texts.

Table arguments (id_type, create_tsvector, fts_language, drop_if_exists and the schema and column names) go to ainit_vectorstore_table; the rest configure the store.

Parameters:

Name	Type	Description	Default
texts	list[str]	Texts to add	required
embedding	Embeddings	Embeddings model	required
metadatas	list[dict] | None	Optional metadata	None
ids	list[str] | None	Optional IDs	None
engine	CockroachDBEngine | None	CockroachDBEngine instance	None
connection_string	str | None	Connection string (if engine not provided)	None
collection_name	str	Table name	'langchain_vectors'
**kwargs	Any	Table and store arguments	{}

Returns:

Type	Description
AsyncCockroachDBVectorStore	AsyncCockroachDBVectorStore instance

aget_by_ids(ids) async

Get documents by their IDs (order not guaranteed).

amax_marginal_relevance_search(query, k=4, fetch_k=20, lambda_mult=0.5, filter=None, **kwargs) async

Max marginal relevance search using the stored embeddings of the candidates.

Parameters:

Name	Type	Description	Default
query	str	Query text	required
k	int	Number of results	4
fetch_k	int	Number of candidates to fetch	20
lambda_mult	float	Diversity parameter (0=max diversity, 1=max relevance)	0.5
filter	dict | None	Metadata filter	None
**kwargs	Any	Additional arguments (query_options supported)	{}

Returns:

Type	Description
list[Document]	List of documents

amax_marginal_relevance_search_by_vector(embedding, k=4, fetch_k=20, lambda_mult=0.5, filter=None, **kwargs) async

Max marginal relevance search from a query embedding.

asimilarity_search(query, k=4, filter=None, **kwargs) async

Search for similar documents.

asimilarity_search_by_vector(embedding, k=4, filter=None, **kwargs) async

Return docs most similar to embedding vector.

asimilarity_search_with_score(query, k=4, filter=None, query_options=None, **kwargs) async

Search for similar documents with scores.

When a hybrid_search_config is set, this runs full-text and vector searches in parallel and returns fused scores. Otherwise scores are plain vector distances.

Parameters:

Name	Type	Description	Default
query	str	Query text	required
k	int	Number of results	4
filter	dict | None	Metadata filter	None
query_options	CSPANNQueryOptions | None	C-SPANN query options	None
**kwargs	Any	Additional arguments (fetch_k sets the hybrid candidate pool size, default max(k * 4, 20))	{}

Returns:

Type	Description
list[tuple[Document, float]]	List of (document, score) tuples

asimilarity_search_with_score_by_vector(embedding, k=4, filter=None, query_options=None, **kwargs) async

Search for similar documents by embedding vector.

Parameters:

Name	Type	Description	Default
embedding	list[float]	Query embedding vector	required
k	int	Number of results	4
filter	dict | None	Metadata filter	None
query_options	CSPANNQueryOptions | None	C-SPANN query options	None
**kwargs	Any	Additional arguments	{}

Returns:

Type	Description
list[tuple[Document, float]]	List of (document, distance) tuples

from_texts(texts, embedding, metadatas=None, **kwargs) classmethod

Sync wrapper - not implemented for async-only store.

get_by_ids(ids)

Get documents by their IDs (sync).

similarity_search(query, k=4, **kwargs)

Sync wrapper - not implemented for async-only store.

langchain_cockroachdb.vectorstores.CockroachDBVectorStore

Bases: AsyncCockroachDBVectorStore

Vector store with sync and async methods.

Sync methods compute embeddings on the calling thread and run their database work on the engine's background event loop, so they are safe to call from any number of threads and from inside a running event loop.

add_embeddings(texts, embeddings, metadatas=None, ids=None, **kwargs)

Add texts with precomputed embeddings (sync).

Raises:

Type	Description
ValueError	When using a namespace, if any caller-supplied id already belongs to a different namespace. This check writes nothing. If a concurrent writer claims an id in another namespace between the check and the write, the write also raises. Earlier batches and the batch's other rows (same-namespace updates and new rows) are already committed when this error is raised.

add_texts(texts, metadatas=None, ids=None, **kwargs)

Add texts to vector store (sync).

Parameters:

Name	Type	Description	Default
texts	Iterable[str]	Texts to add	required
metadatas	list[dict] | None	Optional metadata	None
ids	list[str] | None	Optional IDs	None
**kwargs	Any	Additional arguments (batch_size override supported)	{}

Returns:

Type	Description
list[str]	List of IDs

Raises:

Type	Description
ValueError	When using a namespace, if any caller-supplied id already belongs to a different namespace. This check writes nothing. If a concurrent writer claims an id in another namespace between the check and the write, the write also raises. Earlier batches and the batch's other rows (same-namespace updates and new rows) are already committed when this error is raised.

apply_vector_index(index, prefix_columns=None)

Apply a vector index (sync); warns if an existing index of that name differs.

delete(ids=None, **kwargs)

Delete documents (sync).

drop_vector_index(index=None)

Drop a vector index (sync).

Parameters:

Name	Type	Description	Default
index	CSPANNIndex | None	Index configuration (defaults to CSPANNIndex() to drop the default-named index)	None

from_texts(texts, embedding, metadatas=None, *, ids=None, engine=None, connection_string=None, collection_name='langchain_vectors', **kwargs) classmethod

Create the table if needed, then add texts (sync).

Parameters:

Name	Type	Description	Default
texts	list[str]	Texts to add	required
embedding	Embeddings	Embeddings model	required
metadatas	list[dict] | None	Optional metadata	None
ids	list[str] | None	Optional IDs	None
engine	CockroachDBEngine | None	CockroachDBEngine instance	None
connection_string	str | None	Connection string (if engine not provided)	None
collection_name	str	Table name	'langchain_vectors'
**kwargs	Any	Table arguments for init_vectorstore_table and store arguments	{}

Returns:

Type	Description
CockroachDBVectorStore	CockroachDBVectorStore instance

max_marginal_relevance_search(query, k=4, fetch_k=20, lambda_mult=0.5, filter=None, **kwargs)

MMR search (sync), using the candidates' stored embeddings.

max_marginal_relevance_search_by_vector(embedding, k=4, fetch_k=20, lambda_mult=0.5, filter=None, **kwargs)

MMR search from a query embedding (sync).

similarity_search(query, k=4, filter=None, **kwargs)

Search for similar documents (sync).

similarity_search_by_vector(embedding, k=4, filter=None, **kwargs)

Return docs most similar to embedding vector (sync).

similarity_search_with_score(query, k=4, filter=None, query_options=None, **kwargs)

Search with scores (sync); fused scores when hybrid search is configured.

similarity_search_with_score_by_vector(embedding, k=4, filter=None, query_options=None, **kwargs)

Search by embedding with distances (sync).

Key Methods

Adding Documents

Method	Async	Description
aadd_texts()	✓	Add text documents
add_texts()	-	Sync wrapper
aadd_documents()	✓	Add Document objects
add_documents()	-	Sync wrapper

Searching

Method	Async	Description
asimilarity_search()	✓	Search by text
similarity_search()	-	Sync wrapper
asimilarity_search_with_score()	✓	Search with scores
asimilarity_search_by_vector()	✓	Search by vector
amax_marginal_relevance_search()	✓	MMR search

Index Management

Method	Async	Description
aapply_vector_index()	✓	Create C-SPANN index
apply_vector_index()	-	Sync wrapper
adrop_vector_index()	✓	Drop index
drop_vector_index()	-	Sync wrapper

Deleting

Method	Async	Description
adelete()	✓	Delete documents
delete()	-	Sync wrapper

Examples

See Vector Store Guide for comprehensive examples.