Types - CyborgDB Docs

JSON Type Definitions

CyborgDB provides strongly-typed JSON types for improved type safety when working with metadata and other JSON-serializable data.

JsonPrimitive

type JsonPrimitive = string | number | boolean | null;

Represents any valid JSON primitive value.

JsonValue

type JsonValue = JsonPrimitive | JsonObject | JsonArray;

Represents any valid JSON value. This is a recursive type definition used for metadata and other JSON-serializable data throughout the SDK.

JsonObject

interface JsonObject {
  [key: string]: JsonValue;
}

Represents a JSON object with string keys and JsonValue values.

JsonArray

type JsonArray = JsonValue[];

Represents a JSON array containing any valid JSON values.

VectorMetadata

type VectorMetadata = JsonObject;

Type alias for metadata associated with vector items. Metadata must be a valid JSON object.

Example Usage

import { VectorMetadata, JsonValue } from 'cyborgdb';

const metadata: VectorMetadata = {
    title: 'Document Title',
    author: 'John Doe',
    tags: ['ai', 'vectors', 'database'],
    published: true,
    score: 0.95,
    nested: {
        category: 'technology',
        subcategory: 'ai'
    }
};

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`	`Uint8Array`	Yes	32-byte encryption key
`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
    },
    indexKey: Client.generateKey(), // Uint8Array (32 bytes)
    indexName: 'my-vector-index',
    embeddingModel: 'text-embedding-3-small'
};

UpsertRequest

Interface for adding or updating vectors in an encrypted index.

Properties

Parameter	Type	Required	Description
`items`	`VectorItem[]`	Yes	Array of vector items to insert or update

Example Usage

import { UpsertRequest, VectorItem } from 'cyborgdb';

const upsertRequest: UpsertRequest = {
    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
`queryVectors`	`number[] \| number[][] \| null`	No	-	Vector(s) for similarity search
`queryContents`	`string \| null`	No	-	Text content for semantic search (requires embedding model)
`topK`	`number`	No	`undefined` (server default: 100)	Number of nearest neighbors to return
`nProbes`	`number`	No	`undefined` (auto)	Number of lists to probe during query. Auto-determined when undefined for optimal performance.
`greedy`	`boolean`	No	`false`	Whether to use greedy search algorithm
`filters`	`object \| null`	No	`undefined`	JSON-like dictionary for metadata filtering (no filtering when undefined)
`include`	`string[]`	No	`undefined` (server default: `["distance", "metadata"]`)	Fields to include in response. Note: `id` is always included.

Example Usage

import { QueryRequest } from 'cyborgdb';

const queryRequest: QueryRequest = {
    queryVectors: [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
`queryVectors`	`number[][]`	Yes	-	Array of vectors for batch similarity search
`topK`	`number`	No	`undefined` (server default: 100)	Number of nearest neighbors to return per query
`nProbes`	`number`	No	`undefined` (auto)	Number of lists to probe during each query. Auto-determined when undefined.
`greedy`	`boolean`	No	`false`	Whether to use greedy search algorithm
`filters`	`object`	No	`undefined`	JSON-like dictionary for metadata filtering (no filtering when undefined)
`include`	`string[]`	No	`undefined` (server default: `["distance", "metadata"]`)	Fields to include in response. Note: `id` is always included.

Example Usage

import { BatchQueryRequest } from 'cyborgdb';

const batchQueryRequest: BatchQueryRequest = {
    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	Description
`nLists`	`number`	No	Number of inverted lists for indexing
`batchSize`	`number`	No	Size of each batch for training
`maxIters`	`number`	No	Maximum iterations for training
`tolerance`	`number`	No	Convergence tolerance for training

Example Usage

import { TrainRequest } from 'cyborgdb';

const trainRequest: TrainRequest = {
    nLists: 8192,
    batchSize: 4096,
    maxIters: 150,
    tolerance: 1e-8,
};

DeleteRequest

Interface for deleting vectors from the encrypted index.

Properties

Parameter	Type	Required	Description
`ids`	`string[]`	Yes	Array of vector IDs to delete

Example Usage

import { DeleteRequest } from 'cyborgdb';

const deleteRequest: DeleteRequest = {
    ids: ['doc1', 'doc2', 'doc3']
};

GetRequest

Interface for retrieving specific vectors from the index.

Properties

Parameter	Type	Required	Default	Description
`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 = {
    ids: ['doc1', 'doc2'],
    include: ['vector', 'metadata']
};

VectorItem

Class 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. *Required for upsert operations unless using embedding model
`contents`	`string \| null`	No	Original text or associated content
`metadata`	`VectorMetadata` \| `null`	No	Additional structured metadata (must be valid JSON)

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']
    }
};

Index Configuration 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
`type`	`'ivf'`	Yes	-	Index type identifier
`dimension`	`number \| null`	No	-	Dimensionality of vector embeddings

Example Usage

import { IndexIVF } from 'cyborgdb';

const indexConfig: IndexIVF = {
    type: 'ivf',
    dimension: 768
};

IndexIVFFlat

IVFFlat index configuration, suitable for highest accuracy requirements:

Speed	Accuracy	Memory Usage
Medium	Highest	High

Properties

Parameter	Type	Required	Default	Description
`type`	`'ivfflat'`	Yes	-	Index type identifier
`dimension`	`number \| null`	No	-	Dimensionality of vector embeddings

Example Usage

import { IndexIVFFlat } from 'cyborgdb';

const indexConfig: IndexIVFFlat = {
    type: 'ivfflat',
    dimension: 1536
};

IndexIVFPQ

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

Speed	Accuracy	Memory Usage
Fast	Good	Low

Properties

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

Example Usage

import { IndexIVFPQ } from 'cyborgdb';

const indexConfig: IndexIVFPQ = {
    type: 'ivfpq',
    pqDim: 64,
    pqBits: 8,
    dimension: 768
};

Response Types

UpsertResponse

Response interface for upsert operations.

Properties

Parameter	Type	Description
`status`	`string`	Status of the operation
`upsertedCount`	`number` (optional)	Number of vectors upserted
`message`	`string` (optional)	Additional message or details

Example Usage

import { UpsertResponse } from 'cyborgdb';

const response: UpsertResponse = await index.upsert({
    items: [
        { id: 'doc1', vector: [0.1, 0.2, 0.3], contents: 'Content 1' },
        { id: 'doc2', vector: [0.4, 0.5, 0.6], contents: 'Content 2' }
    ]
});

console.log(`Upserted ${response.upsertedCount} vectors`);

DeleteResponse

Response interface for delete operations.

Properties

Parameter	Type	Description
`status`	`string`	Status of the operation
`deletedCount`	`number` (optional)	Number of vectors deleted
`message`	`string` (optional)	Additional message or details

Example Usage

import { DeleteResponse } from 'cyborgdb';

const response: DeleteResponse = await index.delete({
    ids: ['doc1', 'doc2', 'doc3']
});

console.log(`Deleted ${response.deletedCount} vectors`);

TrainResponse

Response interface for training operations.

Properties

Parameter	Type	Description
`status`	`string`	Status of the training operation
`message`	`string` (optional)	Additional message or details

Example Usage

import { TrainResponse } from 'cyborgdb';

const response: TrainResponse = await index.train({
    nLists: 8192,
    batchSize: 4096
});

console.log(`Training status: ${response.status}`);

HealthResponse

Response interface for health check operations.

Properties

Parameter	Type	Description
`status`	`string`	Status of the service
`[key: string]`	`string`	Optional additional health information

Example Usage

import { HealthResponse } from 'cyborgdb';

const health: HealthResponse = await client.getHealth();
console.log(`Service status: ${health.status}`);

TrainingStatus

Response interface for training status queries.

Properties

Parameter	Type	Description
`training_indexes`	`string[]`	Array of index names currently being trained
`retrain_threshold`	`number`	The multiplier used for the retraining threshold

Example Usage

import { TrainingStatus } from 'cyborgdb';

const status: TrainingStatus = await client.isTraining();
console.log(`Training indexes: ${status.training_indexes.join(', ')}`);

GetResponseModel

Response class for vector retrieval operations.

Properties

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

GetResultItem

Enhanced type-safe result item for get operations. This type extends GetResultItemModel with proper typing for metadata and contents fields.

Properties

Parameter	Type	Description
`id`	`string`	Unique identifier for the vector item
`vector`	`number[]` (optional)	Vector data (if included in response)
`contents`	`Buffer \| Blob \| string` (optional)	The original content
`metadata`	`VectorMetadata` (optional)	Metadata associated with the vector

Example Usage

import { GetResultItem } from 'cyborgdb';

const response = await index.get({
    ids: ['doc1', 'doc2'],
    include: ['vector', 'metadata', 'contents']
});

// Use GetResultItem for type-safe access
response.results.forEach((item: GetResultItem) => {
    console.log(`ID: ${item.id}`);
    if (item.metadata) {
        console.log(`Title: ${item.metadata.title}`);
    }
    if (item.contents) {
        console.log(`Content: ${item.contents}`);
    }
});

QueryResponse

Response class for similarity search operations.

Properties

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

Example Usage

import { QueryResponse } from 'cyborgdb';

function processQueryResults(response: QueryResponse) {
    // Check if batch response by inspecting the structure
    if (Array.isArray(response.results) &&
        response.results.length > 0 &&
        Array.isArray(response.results[0])) {
        // 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);
    }
}

QueryResultItem

Class 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 class for API errors.

Properties

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

HTTPValidationError

Class 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.

Filter Types

FilterExpression

type FilterExpression = {
  [key: string]: FilterValue | FilterOperator;
};

Type for constructing MongoDB-style filter expressions for querying vectors. Supports nested logical operators and field comparisons.

FilterValue

type FilterValue = JsonPrimitive | JsonArray;

Represents possible filter values in filter expressions - can be any JSON primitive or array.

FilterOperator

interface FilterOperator {
  $eq?: FilterValue;
  $ne?: FilterValue;
  $gt?: number;
  $gte?: number;
  $lt?: number;
  $lte?: number;
  $in?: JsonArray;
  $nin?: JsonArray;
  $and?: FilterExpression[];
  $or?: FilterExpression[];
  $not?: FilterExpression;
  $exists?: boolean;
}

Interface defining MongoDB-style query operators for metadata filtering. See the Metadata Filtering section for detailed examples.

Example Usage

import { FilterExpression } from 'cyborgdb';

// Type-safe filter construction
const filter: FilterExpression = {
    category: "research",
    published_year: { $gte: 2020, $lte: 2024 },
    $and: [
        { confidence: { $gte: 0.9 } },
        { $or: [
            { language: "en" },
            { translated: true }
        ]}
    ]
};

const results = await index.query({
    queryVectors: [0.1, 0.2, 0.3],
    topK: 10,
    filters: filter
});

Utility Functions

The SDK provides type guard and utility functions for safer type checking and error handling.

isJsonValue

function isJsonValue(value: unknown, visited?: WeakSet<object>): value is JsonValue

Type guard function to check if a value is a valid JSON value. Handles circular references by tracking visited objects.

Parameters

Parameter	Type	Required	Description
`value`	`unknown`	Yes	The value to check
`visited`	`WeakSet<object>`	No	Internal parameter for tracking circular references

Returns

boolean: Returns true if the value is a valid JSON value, false otherwise.

Example Usage

import { isJsonValue } from 'cyborgdb';

const data = {
    name: "John",
    age: 30,
    tags: ["developer", "typescript"]
};

if (isJsonValue(data)) {
    // Safe to use as metadata
    const item = {
        id: 'user1',
        vector: [0.1, 0.2, 0.3],
        metadata: data
    };
}

// Detects invalid JSON (circular references, functions, etc.)
const circular: any = {};
circular.self = circular;
console.log(isJsonValue(circular)); // false

isError

function isError(error: unknown): error is Error

Type guard to check if an error is an Error instance.

Parameters

Parameter	Type	Required	Description
`error`	`unknown`	Yes	The value to check

Returns

boolean: Returns true if the value is an Error instance, false otherwise.

Example Usage

import { isError } from 'cyborgdb';

try {
    await index.query({ queryVectors: [0.1, 0.2] });
} catch (error) {
    if (isError(error)) {
        console.error(`Error message: ${error.message}`);
        console.error(`Stack trace: ${error.stack}`);
    } else {
        console.error('Unknown error type:', error);
    }
}

getErrorMessage

function getErrorMessage(error: unknown): string

Helper function to safely extract error messages from unknown error types.

Parameters

Parameter	Type	Required	Description
`error`	`unknown`	Yes	The error to extract a message from

Returns

string: A string message extracted from the error. Returns the error’s message property if it’s an Error, converts to string otherwise.

Example Usage

import { getErrorMessage } from 'cyborgdb';

try {
    await index.upsert({ items: [] });
} catch (error) {
    // Safely get error message regardless of error type
    const message = getErrorMessage(error);
    console.error(`Operation failed: ${message}`);

    // Log to monitoring service
    logger.error({
        operation: 'upsert',
        error: message
    });
}

Introduction

Client

Encrypted Index

Types & Helpers

​JSON Type Definitions

​JsonPrimitive

​JsonValue

​JsonObject

​JsonArray

​VectorMetadata

​Example Usage

​CreateIndexRequest

​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

​Index Configuration Types

​IndexIVF

​Properties

​Example Usage

​IndexIVFFlat

​Properties

​Example Usage

​IndexIVFPQ

​Properties

​Example Usage

​Response Types

​UpsertResponse

​Properties

​Example Usage

​DeleteResponse

​Properties

​Example Usage

​TrainResponse

​Properties

​Example Usage

​HealthResponse

​Properties

​Example Usage

​TrainingStatus

​Properties

​Example Usage

​GetResponseModel

​Properties

​GetResultItem

​Properties

​Example Usage

​QueryResponse

​Properties

​Example Usage

​QueryResultItem

​Properties

​Error Types

​ErrorResponseModel

​Properties

​HTTPValidationError

​Properties

​Metadata Filtering

​Supported Operators

​Filter Examples

​Field Selection

JSON Type Definitions

JsonPrimitive

JsonValue

JsonObject

JsonArray

VectorMetadata

Example Usage

CreateIndexRequest

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

Index Configuration Types

IndexIVF

Properties

Example Usage

IndexIVFFlat

Properties

Example Usage

IndexIVFPQ

Properties

Example Usage

Response Types

UpsertResponse

Properties

Example Usage

DeleteResponse

Properties

Example Usage

TrainResponse

Properties

Example Usage

HealthResponse

Properties

Example Usage

TrainingStatus

Properties

Example Usage

GetResponseModel

Properties

GetResultItem

Properties

Example Usage

QueryResponse

Properties

Example Usage

QueryResultItem

Properties

Error Types

ErrorResponseModel

Properties

HTTPValidationError

Properties

Metadata Filtering

Supported Operators

Filter Examples

Field Selection

Available Fields

Example Usage

Filter Types

FilterExpression