Types - CyborgDB Docs

Embedded
Python SDK
JS/TS

StorageConfig

The StorageConfig class specifies where the index data is stored. Build it with one of the static factories:

Factory	Description
`StorageConfig.disk(path, *, cache_vectors=False, cache_metadata=False, cache_ids=False, cache_metadata_index=False)`	Persistent local storage at `path` (recommended for embedded/local deployments).
`StorageConfig.s3(bucket, *, region=None, endpoint=None, prefix="", credentials=None)`	AWS S3 or any S3-compatible object store (MinIO, Cloudflare R2). Uses the AWS default credential chain unless `credentials` is set.

Example Usage

from cyborgdb_core import StorageConfig, S3Credentials

# Local disk (persistent local storage)
disk_storage = StorageConfig.disk("/path/to/data")

# S3 (cloud-native)
s3_storage = StorageConfig.s3("my-bucket", region="us-east-1")

# S3-compatible store with explicit credentials
minio_storage = StorageConfig.s3(
    "my-bucket",
    endpoint="http://localhost:9000",
    credentials=S3Credentials(access_key="minioadmin", secret_key="minioadmin"),
)

Embeddings

The Embedded LangChain integration accepts any LangChain Embeddings implementation:

Supported Embedding Types

Type	Description	Example
`str`	Name of a built-in embedding model	`"all-MiniLM-L6-v2"`
`Embeddings`	Any LangChain Embeddings implementation	`OpenAIEmbeddings()`, `HuggingFaceEmbeddings()`

Example Usage

from langchain_openai import OpenAIEmbeddings
from cyborgdb_core.integrations.langchain import CyborgVectorStore
from cyborgdb_core import StorageConfig

# Using LangChain Embeddings
store = CyborgVectorStore(
    index_name="docs",
    index_key=key,
    api_key="your-api-key",
    embedding=OpenAIEmbeddings(),
    storage_config=StorageConfig.disk("/tmp/cyborgdb-langchain")
)

DistanceMetric

DistanceMetric is a string representing the distance metric used for the index. Options include:

"cosine": Cosine similarity (recommended for normalized embeddings)
"euclidean": Euclidean distance
"squared_euclidean": Squared Euclidean distance

Metric Characteristics

Metric	Range	Use Case
`cosine`	[0, 2]	Text embeddings, normalized vectors
`euclidean`	[0, ∞)	Raw feature vectors
`squared_euclidean`	[0, ∞)	When avoiding sqrt computation

Document

LangChain Document object used for storing text with metadata.

Attributes

Attribute	Type	Description
`page_content`	`str`	The text content of the document
`metadata`	`dict`	Optional metadata associated with the document

Example Usage

from langchain_core.documents import Document

# Create a document
doc = Document(
    page_content="This is the content of my document",
    metadata={
        "source": "manual",
        "author": "John Doe",
        "timestamp": "2024-01-01"
    }
)

# Add to vector store
store.add_documents([doc])

Filter Format

Metadata filters use a dictionary format for querying documents.

Simple Filters

# Exact match
filter = {"category": "technology"}

# Multiple conditions (AND)
filter = {
    "category": "technology",
    "year": 2024
}

Advanced Filters

# Range queries
filter = {
    "price": {"$gte": 100, "$lte": 500}
}

# IN queries
filter = {
    "tags": {"$in": ["python", "machine-learning"]}
}

# Nested fields
filter = {
    "metadata.author": "John Doe"
}

Supported Operators

Operator	Description	Example
`$eq`	Equal to	`{"age": {"$eq": 25}}`
`$ne`	Not equal to	`{"status": {"$ne": "archived"}}`
`$gt`	Greater than	`{"price": {"$gt": 100}}`
`$gte`	Greater than or equal	`{"score": {"$gte": 0.8}}`
`$lt`	Less than	`{"quantity": {"$lt": 10}}`
`$lte`	Less than or equal	`{"rating": {"$lte": 5}}`
`$in`	In array	`{"tags": {"$in": ["ai", "ml"]}}`
`$nin`	Not in array	`{"category": {"$nin": ["draft", "deleted"]}}`

Return Types

Query Results

Query operations return documents with optional scores:

# similarity_search returns List[Document]
docs = store.similarity_search("query", k=5)
# Returns: [Document(...), Document(...), ...]

# similarity_search_with_score returns List[Tuple[Document, float]]
results = store.similarity_search_with_score("query", k=5)
# Returns: [(Document(...), 0.95), (Document(...), 0.87), ...]

Score Normalization

Scores are normalized to [0, 1] range where:

1.0 = Perfect match
0.0 = Worst match

The normalization depends on the distance metric used.

Async Support

All methods have async variants prefixed with a:

Sync Method	Async Method
`add_texts`	`aadd_texts`
`add_documents`	`aadd_documents`
`similarity_search`	`asimilarity_search`
`similarity_search_with_score`	`asimilarity_search_with_score`
`similarity_search_by_vector`	`asimilarity_search_by_vector`
`max_marginal_relevance_search`	`amax_marginal_relevance_search`
`delete`	`adelete`

Example Usage

import asyncio

async def main():
    # Async text addition
    ids = await store.aadd_texts(["async text 1", "async text 2"])

    # Async search
    docs = await store.asimilarity_search("query", k=5)

    # Async deletion
    success = await store.adelete(ids)

asyncio.run(main())

Connection Configuration

The Python SDK connects to a running CyborgDB service instead of using a StorageConfig.

Parameter	Type	Default	Description
`base_url`	`str`	-	Base URL of the CyborgDB microservice endpoint
`api_key`	`str`	-	API key for authentication with the microservice
`verify_ssl`	`bool`	`None`	(Optional) SSL verification. When `None`, automatically disabled for `localhost` and `http://` URLs

StorageConfig and GPUConfig are not applicable to the Python SDK. Storage configuration is managed by the CyborgDB service.

Example Usage

from cyborgdb.integrations.langchain import CyborgVectorStore

store = CyborgVectorStore(
    index_name="my_documents",
    index_key=key,
    api_key="your-api-key",
    embedding="all-MiniLM-L6-v2",
    base_url="http://localhost:8000"
)

Embeddings

The Python SDK supports the same embedding types as the Embedded library:

Type	Description	Example
`str`	Model name string for SentenceTransformers	`"sentence-transformers/all-MiniLM-L6-v2"`
`SentenceTransformer`	SentenceTransformer model instance	`SentenceTransformer("all-MiniLM-L6-v2")`
`Embeddings`	Any LangChain Embeddings implementation	`OpenAIEmbeddings()`, `HuggingFaceEmbeddings()`

DistanceMetric

Same as Embedded:

"cosine": Cosine similarity (recommended for normalized embeddings)
"euclidean": Euclidean distance
"squared_euclidean": Squared Euclidean distance

Metric	Range	Use Case
`cosine`	[0, 2]	Text embeddings, normalized vectors
`euclidean`	[0, ∞)	Raw feature vectors
`squared_euclidean`	[0, ∞)	When avoiding sqrt computation

Document

LangChain Document object used for storing text with metadata.

Attribute	Type	Description
`page_content`	`str`	The text content of the document
`metadata`	`dict`	Optional metadata associated with the document

from langchain_core.documents import Document

doc = Document(
    page_content="This is the content of my document",
    metadata={"source": "manual", "author": "John Doe"}
)

Filter Format

Same filter format as Embedded. Metadata filters use a dictionary format:

# Exact match
filter = {"category": "technology"}

# Range queries
filter = {"price": {"$gte": 100, "$lte": 500}}

# IN queries
filter = {"tags": {"$in": ["python", "machine-learning"]}}

Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

Return Types

Same as Embedded:

# similarity_search returns List[Document]
docs = store.similarity_search("query", k=5)

# similarity_search_with_score returns List[Tuple[Document, float]]
results = store.similarity_search_with_score("query", k=5)

Async Support

Same async variants as Embedded, prefixed with a:

Sync Method	Async Method
`add_texts`	`aadd_texts`
`add_documents`	`aadd_documents`
`similarity_search`	`asimilarity_search`
`similarity_search_with_score`	`asimilarity_search_with_score`
`similarity_search_by_vector`	`asimilarity_search_by_vector`
`delete`	`adelete`

CyborgVectorStoreConfig

Configuration interface for constructing a CyborgVectorStore in JavaScript/TypeScript.

interface CyborgVectorStoreConfig {
    baseUrl: string;
    apiKey: string;
    indexName: string;
    indexKey: Uint8Array;
    dimension?: number;
    metric?: "cosine" | "euclidean" | "squared_euclidean";
    verifySsl?: boolean;
}

Parameter	Type	Default	Description
`baseUrl`	`string`	-	Base URL of the CyborgDB microservice endpoint
`apiKey`	`string`	-	API key for authentication
`indexName`	`string`	-	Name of the index
`indexKey`	`Uint8Array`	-	32-byte encryption key
`dimension`	`number`	-	(Optional) Embedding dimension (auto-inferred if not provided)
`metric`	`string`	`"cosine"`	(Optional) Distance metric
`verifySsl`	`boolean`	`true`	(Optional) SSL verification

All parameters use camelCase convention, consistent with JavaScript/TypeScript standards.

EmbeddingsInterface

The JS/TS SDK accepts any LangChain EmbeddingsInterface implementation:

import { OpenAIEmbeddings } from '@langchain/openai';
import { HuggingFaceTransformersEmbeddings } from '@langchain/community/embeddings/hf_transformers';

// OpenAI embeddings
const embeddings = new OpenAIEmbeddings();

// HuggingFace embeddings
const embeddings = new HuggingFaceTransformersEmbeddings({
    model: "all-MiniLM-L6-v2"
});

Unlike the Python SDKs, the JS/TS SDK does not accept raw model name strings. You must pass a LangChain EmbeddingsInterface instance.

DistanceMetric

Same options as Python SDKs:

"cosine": Cosine similarity (recommended for normalized embeddings)
"euclidean": Euclidean distance
"squared_euclidean": Squared Euclidean distance

Document

LangChain Document object:

import { Document } from '@langchain/core/documents';

const doc = new Document({
    pageContent: "This is the content of my document",
    metadata: { source: "manual", author: "John Doe" }
});

Attribute	Type	Description
`pageContent`	`string`	The text content of the document
`metadata`	`Record<string, any>`	Optional metadata associated with the document

FilterType

Metadata filters use an object format:

// Exact match
const filter = { category: "technology" };

// Multiple conditions (AND)
const filter = {
    category: "technology",
    year: 2024
};

Supports the same operators as the Python SDKs: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin.

Return Types

// similaritySearch returns Promise<Document[]>
const docs = await store.similaritySearch("query", 5);

// similaritySearchWithScore returns Promise<[Document, number][]>
const results = await store.similaritySearchWithScore("query", 5);

Async

All JS/TS methods are natively async and return Promise<...>. There are no separate sync/async variants — every method uses await.

​StorageConfig

​Example Usage

​Embeddings

​Supported Embedding Types

​Example Usage

​DistanceMetric

​Metric Characteristics

​Document

​Attributes

​Example Usage

​Filter Format

​Simple Filters

​Advanced Filters

​Supported Operators

​Return Types

​Query Results

​Score Normalization

​Async Support

​Example Usage

​Connection Configuration

​Example Usage

​Embeddings

​DistanceMetric

​Document

​Filter Format

​Return Types

​Async Support

​CyborgVectorStoreConfig

​EmbeddingsInterface

​DistanceMetric

​Document

​FilterType

​Return Types

​Async

StorageConfig

Example Usage

Embeddings

Supported Embedding Types

Example Usage

DistanceMetric

Metric Characteristics

Document

Attributes

Example Usage

Filter Format

Simple Filters

Advanced Filters

Supported Operators

Return Types

Query Results

Score Normalization

Async Support

Example Usage

Connection Configuration

Example Usage

Embeddings

DistanceMetric

Document

Filter Format

Return Types

Async Support

CyborgVectorStoreConfig

EmbeddingsInterface

DistanceMetric

Document

FilterType

Return Types

Async