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

## Index configuration

These fields of [`CreateIndexParams`](./client/create-index#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](./client/create-index#storage-precision). |
| `MetadataSchema` | `map[string]MetadataFieldPolicy` | `nil` | Per-field indexing policy. See [Metadata schema](./client/create-index#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

```go theme={null}
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`](./encrypted-index/upsert):

```go theme={null}
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](./encrypted-index/upsert#set-contents-on-a-vectoritem). The contents type is exported as `cyborgdb.Contents`.

## Query result

[`Query`](./encrypted-index/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`](./encrypted-index/query-metadata) returns:

```go theme={null}
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`](./getters#bm25) getter:

```go theme={null}
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`](./encrypted-index/query) and [`QueryMetadata`](./encrypted-index/query-metadata) 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

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

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

```go theme={null}
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`](./encrypted-index/upsert) |
| `QueryInput` | Interface implemented by `QueryParams` and `BinaryQueryParams` | [`Query`](./encrypted-index/query) |
| `QueryMetadataParams` | `Filters`, `TopK`, `OrderBy`, `Ascending *bool`, and the text-search fields | [`QueryMetadata`](./encrypted-index/query-metadata) |
| `TrainParams` | `NLists`, `BatchSize`, `MaxIters`, `MaxMemory` (`*int32`), `Tolerance` (`*float64`) | [`Train`](./encrypted-index/train) |
| `GetResponse` | `Results []GetResultItemModel`: `Id`, `Vector`, `Metadata`, `GetContents()` | [`Get`](./encrypted-index/get) |
| `ListIDsResponse` | `Ids []string`, `Count int32` | [`ListIDs`](./encrypted-index/list-ids) |
| `CreatedUser` | `UserID`, `APIKey` (`string`) | [`CreateUser`](./encrypted-index/users) |
| `UserInfo` | `UserID string`, `Permissions []string` | [`ListUsers`](./encrypted-index/users) |
| `SampleDataset`, `SampleFilter`, `LoadSampleDatasetOptions` | See [Load Sample Dataset](./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](./errors).


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