Types - CyborgDB Docs

CreateIndexRequest

The CreateIndexRequest interface defines the parameters for creating a new encrypted index.

Properties

Parameter	Type	Required	Description
`indexConfig`	`IndexConfig`	Yes	Configuration model specifying index type and parameters
`indexKey`	`string`	Yes	32-byte encryption key as hex string
`indexName`	`string`	Yes	Unique name/identifier for the index
`embeddingModel`	`string \| null`	No	Optional embedding model name for automatic vector generation

Example Usage

import { CreateIndexRequest, IndexIVF } from 'cyborgdb';

const createRequest: CreateIndexRequest = {
    indexConfig: {
        type: 'ivf',
        dimension: 768,
        nLists: 1024,
        metric: 'cosine'
    },
    indexKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef', // 64 hex chars (32 bytes)
    indexName: 'my-vector-index',
    embeddingModel: 'text-embedding-3-small'
};

IndexOperationRequest

Base interface for operations that require index identification and authentication.

Properties

Parameter	Type	Required	Description
`indexKey`	`string`	Yes	32-byte encryption key as hex string
`indexName`	`string`	Yes	Name/identifier of the target index

Example Usage

import { IndexOperationRequest } from 'cyborgdb';

const operationRequest: IndexOperationRequest = {
    indexKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    indexName: 'my-vector-index'
};

UpsertRequest

Interface for adding or updating vectors in an encrypted index.

Properties

Parameter	Type	Required	Description
`indexKey`	`string`	Yes	32-byte encryption key as hex string
`indexName`	`string`	Yes	Name/identifier of the target index
`items`	`VectorItem[]`	Yes	Array of vector items to insert or update

Example Usage

import { UpsertRequest, VectorItem } from 'cyborgdb';

const upsertRequest: UpsertRequest = {
    indexKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    indexName: 'my-vector-index',
    items: [
        {
            id: 'doc1',
            vector: [0.1, 0.2, 0.3, /* ... */],
            contents: 'Document content',
            metadata: { title: 'Document 1', category: 'research' }
        }
    ]
};

QueryRequest

Interface for performing similarity search in the encrypted index.

Properties

Parameter	Type	Required	Default	Description
`indexKey`	`string`	Yes	-	32-byte encryption key as hex string
`indexName`	`string`	Yes	-	Name/identifier of the target index
`queryVector`	`number[] \| number[][] \| null`	No	-	Vector(s) for similarity search
`queryContents`	`string \| null`	No	-	Text content for semantic search (requires embedding model)
`topK`	`number`	No	`100`	Number of nearest neighbors to return
`nProbes`	`number`	No	`1`	Number of lists to probe during query
`greedy`	`boolean`	No	`false`	Whether to use greedy search algorithm
`filters`	`object \| null`	No	-	JSON-like dictionary for metadata filtering
`include`	`string[]`	No	`["distances"]`	Fields to include in response

Example Usage

import { QueryRequest } from 'cyborgdb';

const queryRequest: QueryRequest = {
    indexKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    indexName: 'my-vector-index',
    queryVector: [0.1, 0.2, 0.3, /* ... */],
    topK: 10,
    nProbes: 5,
    greedy: false,
    filters: { category: 'research' },
    include: ['distance', 'metadata', 'vector']
};

BatchQueryRequest

Interface for performing batch similarity searches with multiple vectors.

Properties

Parameter	Type	Required	Default	Description
`indexKey`	`string`	Yes	-	32-byte encryption key as hex string
`indexName`	`string`	Yes	-	Name/identifier of the target index
`queryVectors`	`number[][]`	Yes	-	Array of vectors for batch similarity search
`topK`	`number`	No	`100`	Number of nearest neighbors to return per query
`nProbes`	`number`	No	`1`	Number of lists to probe during each query
`greedy`	`boolean`	No	`false`	Whether to use greedy search algorithm
`filters`	`object`	No	-	JSON-like dictionary for metadata filtering
`include`	`string[]`	No	`["distances"]`	Fields to include in response

Example Usage

import { BatchQueryRequest } from 'cyborgdb';

const batchQueryRequest: BatchQueryRequest = {
    indexKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    indexName: 'my-vector-index',
    queryVectors: [
        [0.1, 0.2, 0.3, /* ... */],
        [0.4, 0.5, 0.6, /* ... */],
        [0.7, 0.8, 0.9, /* ... */]
    ],
    topK: 5,
    nProbes: 3,
    filters: { status: 'published' },
    include: ['distance', 'metadata']
};

TrainRequest

Interface for training an index to optimize query performance.

Properties

Parameter	Type	Required	Default	Description
`indexKey`	`string`	Yes	-	32-byte encryption key as hex string
`indexName`	`string`	Yes	-	Name/identifier of the target index
`batchSize`	`number`	No	`2048`	Size of each batch for training
`maxIters`	`number`	No	`100`	Maximum iterations for training
`tolerance`	`number`	No	`1e-6`	Convergence tolerance for training
`maxMemory`	`number`	No	`0`	Maximum memory usage in MB (0 = no limit)

Example Usage

import { TrainRequest } from 'cyborgdb';

const trainRequest: TrainRequest = {
    indexKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    indexName: 'my-vector-index',
    batchSize: 4096,
    maxIters: 150,
    tolerance: 1e-8,
    maxMemory: 8192
};

DeleteRequest

Interface for deleting vectors from the encrypted index.

Properties

Parameter	Type	Required	Description
`indexKey`	`string`	Yes	32-byte encryption key as hex string
`indexName`	`string`	Yes	Name/identifier of the target index
`ids`	`string[]`	Yes	Array of vector IDs to delete

Example Usage

import { DeleteRequest } from 'cyborgdb';

const deleteRequest: DeleteRequest = {
    indexKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    indexName: 'my-vector-index',
    ids: ['doc1', 'doc2', 'doc3']
};

GetRequest

Interface for retrieving specific vectors from the index.

Properties

Parameter	Type	Required	Default	Description
`indexKey`	`string`	Yes	-	32-byte encryption key as hex string
`indexName`	`string`	Yes	-	Name/identifier of the target index
`ids`	`string[]`	Yes	-	Array of vector IDs to retrieve
`include`	`string[]`	No	`["vector", "contents", "metadata"]`	Fields to include in response

Example Usage

import { GetRequest } from 'cyborgdb';

const getRequest: GetRequest = {
    indexKey: '0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
    indexName: 'my-vector-index',
    ids: ['doc1', 'doc2'],
    include: ['vector', 'metadata']
};

VectorItem

Interface representing a vectorized item for storage in the encrypted index.

Properties

Parameter	Type	Required	Description
`id`	`string`	Yes	Unique identifier for the vector item
`vector`	`number[] \| null`	No	Vector representation of the item
`contents`	`string \| null`	No	Original text or associated content
`metadata`	`object \| null`	No	Additional structured metadata

Example Usage

import { VectorItem } from 'cyborgdb';

const vectorItem: VectorItem = {
    id: 'article_123',
    vector: [0.1, 0.2, 0.3, /* ... 768 dimensions */],
    contents: 'This is the content of the article...',
    metadata: {
        title: 'Introduction to Vector Databases',
        author: 'Dr. Smith',
        published_date: '2024-01-15',
        category: 'technology',
        tags: ['vectors', 'database', 'ai']
    }
};

IndexConfig

Base type for index configuration. Use one of the specific index types:

IndexIVF

Standard IVF (Inverted File) index configuration, ideal for balanced performance:

Speed	Accuracy	Memory Usage
Fast	Good	Medium

Properties

Parameter	Type	Required	Default	Description
`dimension`	`number \| null`	No	-	Dimensionality of vector embeddings
`nLists`	`number`	Yes	-	Number of inverted lists
`metric`	`string \| null`	No	-	Distance metric (`'cosine'`, `'euclidean'`, etc.)
`type`	`string`	No	`'ivf'`	Index type identifier

Example Usage

import { IndexIVF } from 'cyborgdb';

const ivfConfig: IndexIVF = {
    type: 'ivf',
    dimension: 768,
    nLists: 1024,
    metric: 'cosine'
};

IndexIVFFlat

IVFFlat index configuration, suitable for highest accuracy requirements:

Speed	Accuracy	Memory Usage
Medium	Highest	High

Properties

Parameter	Type	Required	Default	Description
`dimension`	`number \| null`	No	-	Dimensionality of vector embeddings
`nLists`	`number`	Yes	-	Number of inverted lists
`metric`	`string \| null`	No	-	Distance metric
`type`	`string`	No	`'ivfflat'`	Index type identifier

Example Usage

import { IndexIVFFlat } from 'cyborgdb';

const flatConfig: IndexIVFFlat = {
    type: 'ivfflat',
    dimension: 512,
    nLists: 256,
    metric: 'euclidean'
};

IndexIVFPQ

IVFPQ (Product Quantization) index configuration, optimized for memory efficiency:

Speed	Accuracy	Memory Usage
Fast	Good	Low

Properties

Parameter	Type	Required	Default	Description
`dimension`	`number \| null`	No	-	Dimensionality of vector embeddings
`nLists`	`number`	Yes	-	Number of inverted lists
`metric`	`string \| null`	No	-	Distance metric
`type`	`string`	No	`'ivfpq'`	Index type identifier
`pqDim`	`number`	Yes	-	Dimensionality after quantization
`pqBits`	`number`	Yes	-	Number of bits per quantizer (1-16)

Example Usage

import { IndexIVFPQ } from 'cyborgdb';

const pqConfig: IndexIVFPQ = {
    type: 'ivfpq',
    dimension: 1536,
    nLists: 2048,
    metric: 'cosine',
    pqDim: 64,
    pqBits: 8
};

Response Types

GetResponseModel

Response interface for vector retrieval operations.

Properties

Parameter	Type	Description
`results`	`GetResultItemModel[]`	Array of retrieved items with requested fields

QueryResponse

Response interface for similarity search operations with helper methods.

Properties

Parameter	Type	Description
`results`	`QueryResultItem[] \| QueryResultItem[][]`	Search results (flat for single queries, nested for batch)

Helper Methods

isBatchResponse(): boolean: Determines if response contains batch results
getFirstResultSet(): QueryResultItem[]: Returns first result set from response

Example Usage

import { QueryResponse } from 'cyborgdb';

function processQueryResults(response: QueryResponse) {
    if (response.isBatchResponse()) {
        // Handle batch results
        const batchResults = response.results as QueryResultItem[][];
        batchResults.forEach((batch, index) => {
            console.log(`Batch ${index}:`, batch);
        });
    } else {
        // Handle single query results
        const singleResults = response.results as QueryResultItem[];
        console.log('Results:', singleResults);
    }
    
    // Always get first result set
    const firstResults = response.getFirstResultSet();
    console.log('First result:', firstResults[0]);
}

QueryResultItem

Interface representing a single result from similarity search.

Properties

Parameter	Type	Description
`id`	`string`	Identifier of the retrieved item
`distance`	`number \| null`	Distance from query vector (lower = more similar)
`metadata`	`object \| null`	Additional metadata for the result
`vector`	`number[] \| null`	Retrieved vector (if included in response)

Error Types

ErrorResponseModel

Standard error response interface for API errors.

Properties

Parameter	Type	Description
`statusCode`	`number`	HTTP status code of the error
`detail`	`string`	Detailed message describing the error

HTTPValidationError

Interface for validation errors with detailed field information.

Properties

Parameter	Type	Description
`detail`	`ValidationError[]`	Array of validation errors with field details

Metadata Filtering

The filters parameter in query operations supports a subset of MongoDB query operators for flexible metadata filtering:

Supported Operators

$eq: Equality ({ "category": "research" })
$ne: Not equal ({ "status": { "$ne": "draft" } })
$gt: Greater than ({ "score": { "$gt": 0.8 } })
$gte: Greater than or equal ({ "year": { "$gte": 2020 } })
$lt: Less than ({ "price": { "$lt": 100 } })
$lte: Less than or equal ({ "rating": { "$lte": 4.5 } })
$in: In array ({ "tag": { "$in": ["ai", "ml"] } })
$nin: Not in array ({ "category": { "$nin": ["spam", "deleted"] } })
$and: Logical AND ({ "$and": [{"a": 1}, {"b": 2}] })
$or: Logical OR ({ "$or": [{"x": 1}, {"y": 2}] })

Filter Examples

// Simple equality filter
const simpleFilter = { "category": "research" };

// Range filter
const rangeFilter = { 
    "published_year": { "$gte": 2020, "$lte": 2024 } 
};

// Complex compound filter
const complexFilter = {
    "$and": [
        { "category": "research" },
        { "confidence": { "$gte": 0.9 } },
        { "$or": [
            { "language": "en" },
            { "translated": true }
        ]}
    ]
};

For more information on metadata filtering, see Metadata Filtering.

Field Selection

Many operations support field selection through the include parameter:

Available Fields

vector: The vector data itself
contents: Text or binary content associated with the vector
metadata: Structured metadata object
distance: Similarity distance (query operations only)

Example Usage

// Include only metadata (efficient for existence checks)
const metadataOnly = { include: ['metadata'] };

// Include vectors and distances (for similarity analysis)
const vectorsAndDistances = { include: ['vector', 'distance'] };

// Include all available fields
const allFields = { include: ['vector', 'contents', 'metadata', 'distance'] };

Selecting only necessary fields improves performance by reducing data transfer and processing overhead.

Introduction

Client

Encrypted Index

Types & Getters

​CreateIndexRequest

​Properties

​Example Usage

​IndexOperationRequest

​Properties

​Example Usage

​UpsertRequest

​Properties

​Example Usage

​QueryRequest

​Properties

​Example Usage

​BatchQueryRequest

​Properties

​Example Usage

​TrainRequest

​Properties

​Example Usage

​DeleteRequest

​Properties

​Example Usage

​GetRequest

​Properties

​Example Usage

​VectorItem

​Properties

​Example Usage

​IndexConfig

​IndexIVF

​Properties

​Example Usage

​IndexIVFFlat

​Properties

​Example Usage

​IndexIVFPQ

​Properties

​Example Usage

​Response Types

​GetResponseModel

​Properties

​QueryResponse

​Properties

​Helper Methods

​Example Usage

​QueryResultItem

​Properties

​Error Types

​ErrorResponseModel

​Properties

​HTTPValidationError

​Properties

​Metadata Filtering

​Supported Operators

​Filter Examples

​Field Selection

​Available Fields

​Example Usage

CreateIndexRequest

Properties

Example Usage

IndexOperationRequest

Properties

Example Usage

UpsertRequest

Properties

Example Usage

QueryRequest

Properties

Example Usage

BatchQueryRequest

Properties

Example Usage

TrainRequest

Properties

Example Usage

DeleteRequest

Properties

Example Usage

GetRequest

Properties

Example Usage

VectorItem

Properties

Example Usage

IndexConfig

IndexIVF

Properties

Example Usage

IndexIVFFlat

Properties

Example Usage

IndexIVFPQ

Properties

Example Usage

Response Types

GetResponseModel

Properties

QueryResponse

Properties

Helper Methods

Example Usage

QueryResultItem

Properties

Error Types

ErrorResponseModel

Properties

HTTPValidationError

Properties

Metadata Filtering

Supported Operators

Filter Examples

Field Selection

Available Fields

Example Usage