> ## 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

## VectorItem

Represents a single vector with its associated data.

```go theme={null}
type VectorItem struct {
    Id       string                 `json:"id"`                // Unique identifier
    Vector   []float32              `json:"vector,omitempty"`  // Vector data
    Contents NullableContents       `json:"contents,omitempty"` // Optional text content  
    Metadata map[string]interface{} `json:"metadata,omitempty"` // Optional metadata
}
```

### Fields

| Field | Type | Description |
| - | - | - |
| `Id` | `string` | Unique identifier for the vector (required) |
| `Vector` | `[]float32` | The vector data as float32 slice |
| `Contents` | `NullableContents` | Optional text content associated with the vector |
| `Metadata` | `map[string]interface{}` | Optional key-value pairs for filtering and retrieval |

***

## CreateIndexParams

Parameters for creating a new encrypted vector index.

```go theme={null}
type CreateIndexParams struct {
    IndexName      string     `json:"index_name"`            // Unique identifier for the index
    IndexKey       []byte     `json:"index_key"`             // 32-byte encryption key
    IndexConfig    IndexModel `json:"index_config,omitempty"` // Index configuration
    Metric         *string    `json:"metric,omitempty"`       // Distance metric
    EmbeddingModel *string    `json:"embedding_model,omitempty"` // Associated embedding model
}
```

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `IndexName` | `string` | Yes | Unique identifier for the index |
| `IndexKey` | `[]byte` | Yes | 32-byte encryption key (use GenerateKey() to create) |
| `IndexConfig` | `IndexModel` | No | Index configuration (IVFFlat, IVFPQ, or IVFSQ) |
| `Metric` | `*string` | No | Distance metric ("euclidean", "squared\_euclidean", "cosine") |
| `EmbeddingModel` | `*string` | No | Name of embedding model to associate |

***

## Index Configuration Types

### IndexModel Interface

All index configuration types implement this interface.

```go theme={null}
type IndexModel interface {
    ToIndexConfig() *internal.IndexConfig
}
```

### IVFSQ Configuration

Create an IVFSQ (Scalar Quantization) index configuration that compresses each dimension independently.

```go theme={null}
func IndexIVFSQ(dimension int32, sqBits int32) *indexIVFSQ
```

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `dimension` | `int32` | The dimensionality of vectors that will be stored |
| `sqBits` | `int32` | Number of bits per dimension for scalar quantization (default: 16) |

### IVFFlat Configuration

Create an IVFFlat (Inverted File Flat) index configuration for higher accuracy.

```go theme={null}
func IndexIVFFlat(dimension int32) *indexIVFFlat
```

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `dimension` | `int32` | The dimensionality of vectors that will be stored |

### IVFPQ Configuration

Create an IVFPQ (Inverted File with Product Quantization) index configuration for memory efficiency.

```go theme={null}
func IndexIVFPQ(dimension int32, pqDim int32, pqBits int32) *indexIVFPQ
```

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `dimension` | `int32` | The dimensionality of vectors that will be stored |
| `pqDim` | `int32` | Product quantization dimension (typically dimension/8 or dimension/16) |
| `pqBits` | `int32` | Bits per PQ code (typically 8, higher = more accurate but larger) |

***

## Response Types

### QueryResponse

Response from similarity search operations.

```go theme={null}
type QueryResponse = internal.QueryResponse
```

Contains search results with similar vectors and their metadata.

### QueryResultItem

A single result from a similarity search query.

```go theme={null}
type QueryResultItem = internal.QueryResultItem
```

Represents one matching vector with its similarity score and metadata.

### GetResponse

Response from Get operations containing retrieved vectors.

```go theme={null}
type GetResponse = internal.GetResponseModel
```

### ListIDsResponse

Response from ListIDs operations.

```go theme={null}
type ListIDsResponse = internal.ListIDsResponse
```

Contains the list of vector IDs in the index.

#### Fields

| Field | Type | Description |
| - | - | - |
| `Ids` | `[]string` | List of all vector ID strings in the index |
| `Count` | `int32` | Total number of IDs in the index |

***

## TrainParams

Parameters for training an encrypted vector index.

```go theme={null}
type TrainParams struct {
    BatchSize  *int32   `json:"batch_size,omitempty"`  // Number of vectors per training batch
    MaxIters   *int32   `json:"max_iters,omitempty"`   // Maximum training iterations  
    Tolerance  *float64 `json:"tolerance,omitempty"`   // Convergence tolerance
    MaxMemory  *int32   `json:"max_memory,omitempty"`  // Maximum memory usage in MB
    NLists     *int32   `json:"n_lists,omitempty"`     // Number of IVF clusters
}
```

#### Fields

| Field | Type | Description |
| - | - | - |
| `BatchSize` | `*int32` | Number of vectors processed per training batch (default: 2048) |
| `MaxIters` | `*int32` | Maximum training iterations (default: 100) |
| `Tolerance` | `*float64` | Convergence tolerance for training (default: 1e-6) |
| `MaxMemory` | `*int32` | Maximum memory usage in MB, 0 = no limit (default: 0) |
| `NLists` | `*int32` | Number of IVF clusters, 0 = auto-determine (default: 0) |

***

## UpsertInput Interface

Sealed interface implemented by types that can be passed to `Upsert`.

```go theme={null}
type UpsertInput interface {
    isUpsertInput()
}
```

Valid implementations: [`VectorItems`](#vectoritems), [`BinaryUpsertParams`](#binaryupsertparams)

***

## QueryInput Interface

Sealed interface implemented by types that can be passed to `Query`.

```go theme={null}
type QueryInput interface {
    isQueryInput()
}
```

Valid implementations: [`QueryParams`](#queryparams), [`BinaryQueryParams`](#binaryqueryparams)

***

## VectorItems

A slice of `VectorItem` that implements `UpsertInput` for type-safe upsert operations.

```go theme={null}
type VectorItems []VectorItem
```

***

## BinaryUpsertParams

Parameters for binary format vector upserts. More efficient than `VectorItems` for large batches.

```go theme={null}
type BinaryUpsertParams struct {
    IDs      []string
    Vectors  [][]float32
    Metadata []map[string]interface{}
    Contents []string
}
```

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `IDs` | `[]string` | Yes | Unique identifiers for each vector |
| `Vectors` | `[][]float32` | Yes | Vector data, shape \[n\_vectors]\[dimension] |
| `Metadata` | `[]map[string]interface{}` | No | Optional metadata for each vector (length must match IDs if provided) |
| `Contents` | `[]string` | No | Optional content strings for each vector (length must match IDs if provided) |

***

## BinaryQueryParams

Parameters for binary format similarity search. More efficient than `QueryParams` for large batch queries.

```go theme={null}
type BinaryQueryParams struct {
    QueryVectors [][]float32
    TopK         int32
    NProbes      *int32
    Greedy       *bool
    Filters      map[string]interface{}
    Include      []string
}
```

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `QueryVectors` | `[][]float32` | Yes | Query vectors, shape \[n\_queries]\[dimension] |
| `TopK` | `int32` | No | Number of nearest neighbors to return (default: 100) |
| `NProbes` | `*int32` | No | Number of IVF lists to probe |
| `Greedy` | `*bool` | No | Enable greedy search mode |
| `Filters` | `map[string]interface{}` | No | Metadata filters to apply |
| `Include` | `[]string` | No | Fields to include in response. Defaults to `[]` (only `id` is returned) |

***

## QueryParams

Parameters for similarity search queries. Supports single vector, batch, and content-based queries.

```go theme={null}
type QueryParams struct {
    QueryVector       []float32              `json:"query_vector,omitempty"`
    BatchQueryVectors [][]float32            `json:"query_vectors,omitempty"`
    QueryContents     *string                `json:"query_contents,omitempty"`
    TopK              int32                  `json:"top_k"`
    NProbes           *int32                 `json:"n_probes,omitempty"`
    Greedy            *bool                  `json:"greedy,omitempty"`
    Filters           map[string]interface{} `json:"filters,omitempty"`
    Include           []string               `json:"include"`
}
```

### Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `QueryVector` | `[]float32` | No | Single query vector for similarity search |
| `BatchQueryVectors` | `[][]float32` | No | Multiple query vectors for batch search |
| `QueryContents` | `*string` | No | Text content for semantic search |
| `TopK` | `int32` | No | Number of nearest neighbors to return |
| `NProbes` | `*int32` | No | Number of clusters to probe for search |
| `Greedy` | `*bool` | No | Use greedy search algorithm |
| `Filters` | `map[string]interface{}` | No | Metadata filters to apply |
| `Include` | `[]string` | No | Fields to include in results: `"metadata"`, `"distance"`, `"vector"`, `"contents"`. Defaults to `[]` (only `id` is returned) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.