> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

## CreateIndexRequest

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

### Properties

| Parameter        | Type                          | Required | Description                                                   |
| ---------------- | ----------------------------- | -------- | ------------------------------------------------------------- |
| `indexConfig`    | [`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

```typescript theme={null}
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

```typescript theme={null}
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[]`](#vectoritem) | Yes      | Array of vector items to insert or update |

### Example Usage

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
// 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](../guides/data-operations/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

```typescript theme={null}
// 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.