Types

Index configuration

These fields of CreateIndexParams configure the index. There is no IndexConfig field and no IndexIVFFlat / IndexIVFPQ / IndexIVFSQ helpers.

Field	Type	Default	Description
`Dimension`	`*int32`	auto-detect	Vector dimensionality. Taken from the first upsert, or from `EmbeddingModel`, when `nil`.
`Metric`	`*string`	`"euclidean"`	`"euclidean"`, `"squared_euclidean"`, or `"cosine"`.
`EmbeddingModel`	`*string`	`nil`	Name of one of the service’s built-in embedding models (listed by `GET /v1/embedding-models`), used for automatic embedding generation.
`StoragePrecision`	`*string`	`"float32"`	One of the `StoragePrecision*` constants: `Float32`, `Float16`, or TurboQuant `TQ12`, `TQ8`, `TQ6`, `TQ4`. See Storage precision.
`MetadataSchema`	`map[string]MetadataFieldPolicy`	`nil`	Per-field indexing policy. See Metadata schema.
`TextFields`	`[]string`	`nil`	Fields to index for BM25 full-text search.
`Bm25K1`	`*float64`	`1.2`	BM25 term-frequency saturation.
`Bm25B`	`*float64`	`0.75`	BM25 length normalization.

MetadataFieldPolicy

type MetadataFieldPolicy struct {
    Filterable *bool // nil = true
    Pattern    *bool // nil = false
    FullText   *bool // nil = false
}

Key management

Field	Type	Notes
`IndexKey`	`[]byte`	32-byte key (`KeySize`) for the SDK-supplied-key path. Pass it again on every `LoadIndex`. The SDK sends it to the service as hex.
`KmsName`	`*string`	Name of a `kms.registry` entry in the service YAML. The service generates and wraps the key; later calls pass a `nil` key.

Set exactly one of the two in CreateIndexParams; setting both returns a *ValidationError.

VectorItem

The element type of VectorItems, the JSON form of Upsert:

item := cyborgdb.VectorItem{
    Id:     "unique_identifier",
    Vector: []float32{0.1, 0.2, 0.3, 0.4},
    Metadata: map[string]interface{}{
        "category":     "research",
        "author":       "Dr. Smith",
        "tags":         []string{"ai", "ml"},
        "published_ms": int64(1768435200000), // a date, as epoch milliseconds
    },
}
_ = item

Set VectorItem.Contents with item.SetContentsString(s), as shown in Upsert. The contents type is exported as cyborgdb.Contents.

Query result

Query returns a *QueryResponse. Its Results field is a union with exactly one side set:

Field	Type	Set for
`ArrayOfQueryResultItem`	`*[]QueryResultItem`	One query vector, in any form
`ArrayOfArrayOfQueryResultItem`	`*[][]QueryResultItem`	Two or more query vectors

QueryResultItem has Id string and Metadata map[string]interface{}, plus GetDistance() / HasDistance() (vector queries; lower is closer) and GetScore() / HasScore() (hybrid queries, instead of distance; higher is more relevant).

QueryMetadataResponse and MetadataResult

QueryMetadata returns:

type QueryMetadataResponse struct {
    Results []MetadataResult // Id, plus a score when Text is set
    Ids     []string
    Count   int32
}

type MetadataResult struct {
    Id    string
    Score *float32 // read with GetScore() / HasScore()
}

BM25Config

Returned by the BM25 getter:

type BM25Config struct {
    K1              float32
    B               float32
    AnalyzerVersion NullableString // read with GetAnalyzerVersion()
}

Field selection

Include picks the fields returned besides the ID:

Field	`Get`	`Query`
`vector`	Yes (default)	Not returned
`contents`	Yes (default)	Not returned
`metadata`	Yes (default)	Yes
`distance`	-	Yes

Get with a nil include returns vector, contents, and metadata; Query with a nil Include returns only the ID.

Metadata filtering

Filters on Query and QueryMetadata is a map[string]interface{} of MongoDB-style operators. Nested fields use dot-paths such as "loc.city".

Operators

Operator	Meaning	Example
`$eq`	Equal (also the meaning of a bare value)	`{"category": "research"}`
`$ne`	Not equal	`{"status": {"$ne": "draft"}}`
`$gt`, `$gte`	Greater than, or equal	`{"year": {"$gte": 2020}}`
`$lt`, `$lte`	Less than, or equal	`{"price": {"$lt": 100}}`
`$in`	Value is in the list	`{"tag": {"$in": ["ai", "ml"]}}`
`$nin`	Value is not in the list	`{"category": {"$nin": ["spam", "deleted"]}}`
`$exists`	Field is present (`true`) or absent (`false`)	`{"reviewer": {"$exists": true}}`
`$regex`	String matches a regular expression	`{"title": {"$regex": "^intro"}}`
`$contains`	String contains a substring	`{"title": {"$contains": "guide"}}`
`$and`	All sub-filters match	`{"$and": [{"a": 1}, {"b": 2}]}`
`$or`	Any sub-filter matches	`{"$or": [{"x": 1}, {"y": 2}]}`
`$nor`	No sub-filter matches	`{"$nor": [{"status": "draft"}, {"status": "deleted"}]}`
`$not`	The sub-filter doesn’t match. Takes one filter object, at the top level.	`{"$not": {"price": {"$gt": 100}}}`

The examples are shown as JSON; in Go, each object is a map[string]interface{} and each array a []interface{}. $gt, $gte, $lt, and $lte require a number; any other value returns a *ValidationError. $not can’t be nested inside a field. $regex and $contains resolve from the index only on fields created with Pattern true: Query falls back to a slower post-filter otherwise, and QueryMetadata rejects the filter.

Example

filter := map[string]interface{}{
    "$and": []interface{}{
        map[string]interface{}{"category": "research"},
        map[string]interface{}{"confidence": map[string]interface{}{"$gte": 0.9}},
        map[string]interface{}{"$or": []interface{}{
            map[string]interface{}{"language": "en"},
            map[string]interface{}{"translated": true},
        }},
    },
}
_ = filter

Dates

CyborgDB has no date type. Store dates in metadata as integer milliseconds since the Unix epoch (UTC), so range operators work on them. Don’t store time.Time values: the SDK sends them as RFC 3339 strings, which only support equality filters.

published := time.Date(2026, 1, 15, 0, 0, 0, 0, time.UTC)

err := index.Upsert(ctx, cyborgdb.VectorItems{
    {Id: "doc1", Vector: []float32{0.1, 0.2, 0.3, 0.4}, Metadata: map[string]interface{}{"published_ms": published.UnixMilli()}},
})
if err != nil {
    log.Fatal(err)
}

// Everything published on or after 2026-01-01
start := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC).UnixMilli()
res, err := index.QueryMetadata(ctx, cyborgdb.QueryMetadataParams{
    Filters: map[string]interface{}{"published_ms": map[string]interface{}{"$gte": start}},
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(res.Ids)
// Output: [doc1]

Values come back as float64 after JSON decoding. Convert one back to a time.Time with:

res, err := index.Get(ctx, []string{"doc1"}, []string{"metadata"})
if err != nil {
    log.Fatal(err)
}
ms := int64(res.Results[0].Metadata["published_ms"].(float64))
fmt.Println(time.UnixMilli(ms).UTC())
// Output: 2026-01-15 00:00:00 +0000 UTC

Distance metrics

Metric	Description
`cosine`	Cosine distance. Suited to normalized embeddings.
`euclidean`	Euclidean (L2) distance.
`squared_euclidean`	Squared Euclidean distance. Same ranking as `euclidean`, without the square root.

Other types

Type	Fields	Used by
`UpsertInput`	Interface implemented by `VectorItems` and `BinaryUpsertParams`	`Upsert`
`QueryInput`	Interface implemented by `QueryParams` and `BinaryQueryParams`	`Query`
`QueryMetadataParams`	`Filters`, `TopK`, `OrderBy`, `Ascending *bool`, and the text-search fields	`QueryMetadata`
`TrainParams`	`NLists`, `BatchSize`, `MaxIters`, `MaxMemory` (`int32`), `Tolerance` (`float64`)	`Train`
`GetResponse`	`Results []GetResultItemModel`: `Id`, `Vector`, `Metadata`, `GetContents()`	`Get`
`ListIDsResponse`	`Ids []string`, `Count int32`	`ListIDs`
`CreatedUser`	`UserID`, `APIKey` (`string`)	`CreateUser`
`UserInfo`	`UserID string`, `Permissions []string`	`ListUsers`
`SampleDataset`, `SampleFilter`, `LoadSampleDatasetOptions`	See Load Sample Dataset	`LoadSampleDataset`

Constants

Constant	Value
`KeySize`	`32`
`StoragePrecisionFloat32`, `StoragePrecisionFloat16`, `StoragePrecisionTQ12`, `StoragePrecisionTQ8`, `StoragePrecisionTQ6`, `StoragePrecisionTQ4`	`"float32"`, `"float16"`, `"tq12"`, `"tq8"`, `"tq6"`, `"tq4"`
`DefaultSampleDataset`	`"quickstart-75k"`
`SampleDatasetsBaseURL`	`"https://cyborgdb-sample-datasets.s3.amazonaws.com"`

Pointer fields can be set with the helpers cyborgdb.Bool, cyborgdb.Int32, cyborgdb.String, and cyborgdb.Float64, e.g. Dimension: cyborgdb.Int32(384). Error types and sentinel errors are listed in Errors.

Introduction

Client

Encrypted Index

Types & Helpers

Index configuration

MetadataFieldPolicy

Key management

VectorItem

Query result

QueryMetadataResponse and MetadataResult

BM25Config

Field selection

Metadata filtering

Operators

Example

Dates

Distance metrics

Other types

Constants

​Index configuration

​MetadataFieldPolicy

​Key management

​VectorItem

​Query result

​QueryMetadataResponse and MetadataResult

​BM25Config

​Field selection

​Metadata filtering

​Operators

​Example

​Dates

​Distance metrics

​Other types

​Constants

Index configuration

MetadataFieldPolicy

Key management

VectorItem

Query result

QueryMetadataResponse and MetadataResult

BM25Config

Field selection

Metadata filtering

Operators

Example

Dates

Distance metrics

Other types

Constants