Types

type JsonPrimitive = string | number | boolean | null;

type JsonValue = JsonPrimitive | JsonObject | JsonArray;

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

type JsonArray = JsonValue[];

type VectorMetadata = JsonObject;

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

import { CreateIndexRequest } from 'cyborgdb';

const createRequest: CreateIndexRequest = {
    indexName: 'my-vector-index',
    indexKey: 'a1b2c3...', // hex-encoded 32-byte key
    dimension: 768,
    metric: 'cosine',
    embeddingModel: 'text-embedding-3-small',
    storagePrecision: 'float32',
};

// KMS-backed alternative:
const kmsRequest: CreateIndexRequest = {
    indexName: 'kms-index',
    kmsName: 'prod-aws',
    dimension: 768,
};

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

import { QueryRequest } from 'cyborgdb';

const queryRequest: QueryRequest = {
    queryVectors: [0.1, 0.2, 0.3, /* ... */],
    topK: 10,
    nProbes: 5,
    greedy: false,
    rerankMult: 20,
    filters: { category: 'research' },
    include: ['distance', 'metadata', 'vector']
};

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

import { TrainRequest } from 'cyborgdb';

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

import { DeleteRequest } from 'cyborgdb';

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

import { GetRequest } from 'cyborgdb';

const getRequest: GetRequest = {
    ids: ['doc1', 'doc2'],
    include: ['vector', 'metadata']
};

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

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`);

import { DeleteResponse } from 'cyborgdb';

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

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

import { TrainResponse } from 'cyborgdb';

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

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

import { HealthResponse } from 'cyborgdb';

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

if (await index.isTraining()) {
    console.log('Training in progress for this index');
}

import { GetResultItem } from 'cyborgdb';

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

// `get()` returns a bare GetResultItem[] — the SDK unwraps the server's
// `{ results: [...] }` envelope for you. Iterate the array directly.
items.forEach((item) => {
    console.log(`ID: ${item.id}`);
    if (item.metadata) {
        console.log(`Title: ${item.metadata.title}`);
    }
    if (item.contents) {
        console.log(`Content: ${item.contents}`);
    }
});

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);
    }
}

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

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

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

type FilterValue = JsonPrimitive | JsonArray;

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

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
});

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

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

function isError(error: unknown): error is Error

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);
    }
}

function getErrorMessage(error: unknown): string

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
    });
}