> ## 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 internal.NullableContents `json:"contents,omitempty"` // Optional payload (see note)
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` | `internal.NullableContents` | Optional payload (string or bytes). See note below. |
| `Metadata` | `map[string]interface{}` | Optional key-value pairs for filtering and retrieval |
`Contents` is a generated nullable wrapper from the internal OpenAPI models — the type is not re-exported on the public package, so most Go code leaves the field zero-valued and relies on JSON round-tripping. If you need to set it from Go, use the generated helpers on the underlying `internal.VectorItem`: `item.SetContents(internal.Contents{String: &s})` or `item.SetContents(internal.Contents{Bytes: &b})`. Contents read back from `Get` / `Query` responses are accessible via the same nullable accessors.
***
## CreateIndexParams
Parameters for creating a new encrypted DiskIVF index.
```go theme={null}
type CreateIndexParams struct {
IndexName string `json:"index_name"`
IndexKey []byte `json:"index_key,omitempty"` // SDK-supplied KEK
KmsName *string `json:"kms_name,omitempty"` // KMS-backed path
Dimension *int32 `json:"dimension,omitempty"`
Metric *string `json:"metric,omitempty"`
EmbeddingModel *string `json:"embedding_model,omitempty"`
StoragePrecision *string `json:"storage_precision,omitempty"` // "float32" | "float16"
}
```
### Fields
| Field | Type | Required | Description |
| ------------------ | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `IndexName` | `string` | Yes | Unique identifier for the index |
| `IndexKey` | `[]byte` | Conditional | 32-byte encryption key. Required when `KmsName` is nil; mutually exclusive with `KmsName` against a real-KMS slot. |
| `KmsName` | `*string` | Conditional | Name of a `kms.registry` entry in the service YAML. Required when `IndexKey` is nil. |
| `Dimension` | `*int32` | No | Vector dimensionality (auto-detected from first upsert if nil) |
| `Metric` | `*string` | No | Distance metric: `"euclidean"`, `"squared_euclidean"`, or `"cosine"`. Defaults to the server's default (`"euclidean"`). |
| `EmbeddingModel` | `*string` | No | Optional sentence-transformers model name for auto-embedding |
| `StoragePrecision` | `*string` | No | On-disk rerank-vector dtype: `"float32"` (default) or `"float16"`. Use `cyborgdb.StoragePrecisionFloat32` / `StoragePrecisionFloat16` constants. |
v0.17 introduces a single **DiskIVF** index type. The polymorphic `IndexIVFFlat` / `IndexIVFPQ` / `IndexIVFSQ` constructors and the `IndexModel` interface have been removed.
***
## 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"`
RerankMult *int32 `json:"rerank_mult,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 |
| `RerankMult` | `*int32` | No | Multiplier for stage 1 retrieval in reranking indexes. Stage 1 returns `TopK * RerankMult` candidates before reranking. Server default: `10`. Ignored by indexes that do not rerank. |
| `Filters` | `map[string]interface{}` | No | Metadata filters to apply |
| `Include` | `[]string` | No | Fields to include in results: `"metadata"`, `"distance"`, `"vector"`. Defaults to `[]` (only `id` is returned). `QueryResultItem` has no `Contents` field — fetch contents via `Get` if needed. |
***
## Constants
```go theme={null}
const KeySize = 32
```
| Constant | Value | Description |
| --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KeySize` | `32` | Required length, in bytes, of an SDK-supplied index encryption key (AES-256). `Client.GenerateKey()` returns a slice of this length; `LoadIndex` / `CreateIndex` reject any `IndexKey` whose length is not `KeySize`. |
## Error Variables
The package exports sentinel errors that callers can match against with `errors.Is`:
| Variable | Returned when |
| --------------------- | ------------------------------------------------------------------- |
| `ErrInvalidKeyLength` | An `IndexKey` is supplied with a length other than `KeySize` bytes. |
| `ErrKeyGeneration` | `GenerateKey` fails to read from the OS CSPRNG. |
| `ErrInvalidURL` | `NewClient` is called with a malformed base URL. |
| `ErrMissingKeyOrKMS` | `CreateIndex` is called with neither `IndexKey` nor `KmsName` set. |