Types - CyborgDB Docs

VectorItem

Represents a single vector with its associated data.

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.

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.

type QueryResponse = internal.QueryResponse

Contains search results with similar vectors and their metadata.

QueryResultItem

A single result from a similarity search query.

type QueryResultItem = internal.QueryResultItem

Represents one matching vector with its similarity score and metadata.

GetResponse

Response from Get operations containing retrieved vectors.

type GetResponse = internal.GetResponseModel

ListIDsResponse

Response from ListIDs operations.

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.

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.

type UpsertInput interface {
    isUpsertInput()
}

Valid implementations: VectorItems, BinaryUpsertParams

QueryInput Interface

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

type QueryInput interface {
    isQueryInput()
}

Valid implementations: QueryParams, BinaryQueryParams

VectorItems

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

type VectorItems []VectorItem

BinaryUpsertParams

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

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.

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.

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

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.

​VectorItem

​Fields

​CreateIndexParams

​Fields

​Response Types

​QueryResponse

​QueryResultItem

​GetResponse

​ListIDsResponse

​Fields

​TrainParams

​Fields

​UpsertInput Interface

​QueryInput Interface

​VectorItems

​BinaryUpsertParams

​Fields

​BinaryQueryParams

​Fields

​QueryParams

​Fields

​Constants

​Error Variables

VectorItem

Fields

CreateIndexParams

Fields

Response Types

QueryResponse

QueryResultItem

GetResponse

ListIDsResponse

Fields

TrainParams

Fields

UpsertInput Interface

QueryInput Interface

VectorItems

BinaryUpsertParams

Fields

BinaryQueryParams

Fields

QueryParams

Fields

Constants

Error Variables