> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frogbot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vector field

> Store supplied numerical vectors on ordinary collection records.

A vector field stores a fixed-length array of numbers. You can create, read, replace, and delete its value through ordinary collection operations without configuring a search index or an AI provider. FrogBot does not generate the vector for you.

## Configure a vector field

Install `@frogbotai/db-sqlite`, set `FROGBOT_SECRET`, and add this `frogbot.config.ts`:

```ts theme={"theme":"tokyo-night"}
import { sqliteAdapter } from '@frogbotai/db-sqlite';
import { buildConfig } from 'frogbot';

export default buildConfig({
  secret: process.env.FROGBOT_SECRET!,
  db: sqliteAdapter({ client: { url: 'file:./frogbot.db' } }),
  collections: [
    {
      slug: 'articles',
      fields: [
        { name: 'title', type: 'text', required: true },
        { name: 'embedding', type: 'vector', dimensions: 3 },
      ],
    },
  ],
});
```

This configuration has **no `search` index** and can initialize with the SQLite adapter. The three-dimensional value keeps the example short; choose dimensions that match the vectors your application supplies.

## Config options

| Option | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | Required | Property name used in stored records and APIs. See [field names](https://docs.frogbot.ai/fields/overview.md#field-names). |
| `type` | `'vector'` | Required | Selects the Vector field. |
| `dimensions` | `number` | Required | Number of values in every vector. Must be a positive integer. |
| `label` | `string \| Record<string, string> \| (({ i18n, t }) => string) \| false` | Generated from `name` | Label shown in the admin panel. Use an object keyed by language code for translations, or `false` to hide the label. |
| `required` | `boolean` | `false` | Rejects a missing or `null` vector on normal writes. |
| `unique` | `boolean` | `false` | Creates a unique database index for the field path. See [indexes](https://docs.frogbot.ai/database/indexes.md). |
| `index` | `boolean` | `false` | Creates a database index for faster queries. `unique` already creates one. |
| `localized` | `boolean` | `false` | Stores one value per configured locale. Ignored without [localization](https://docs.frogbot.ai/configuration/localization.md) or inside a localized parent. |
| `defaultValue` | `number[]` or `({ locale, req, user }) => value` | — | Value used when the field has no value. See [default values](https://docs.frogbot.ai/fields/overview.md#default-values). |
| `validate` | `Validate<number[]>` | — | Extra validation that runs after FrogBot checks the length and that every value is a finite number. See [validation](https://docs.frogbot.ai/fields/overview.md#validation). |
| `hooks` | `{ beforeValidate, beforeChange, afterChange, afterRead, beforeDuplicate }` | — | Arrays of `FieldHook` functions for each phase. See [field hooks](https://docs.frogbot.ai/hooks/fields.md). |
| `access` | `{ create, read, update }` | Allowed | `FieldAccess` functions for each operation. See [field access control](https://docs.frogbot.ai/access-control/fields.md). |
| `hidden` | `boolean` | `false` | Removes the field from API responses and the admin panel while keeping stored data. |
| `saveToJWT` | `boolean \| string` | `false` | In an auth-enabled collection, copies the value into the user's token. A string sets the token key. See [token data](https://docs.frogbot.ai/authentication/token-data.md). |
| `virtual` | `boolean \| string` | `false` | `true` skips database storage; a string reads a value through a relationship path. Virtual fields are read-only in the admin panel unless `admin.readOnly` is `false`. See [virtual fields](https://docs.frogbot.ai/fields/overview.md#virtual-field-configuration). |
| `disableDuplicate` | `boolean` | `false` | Leaves the value out when a document is duplicated, so the copy uses `defaultValue`. |
| `admin` | `object` | — | Admin-panel options. See [Admin options](#admin-options). |
| `custom` | `Record<string, any>` | — | Server-only metadata for your own code and plugins. Use `admin.custom` for data the browser also needs. FrogBot adds the dimensions under `custom.frogbot.vector`. |
| `jsonSchema` | `Array<({ jsonSchema }) => JSONSchema4>` | — | Functions that modify the JSON Schema used by [type generation](https://docs.frogbot.ai/typescript/generating-types.md). FrogBot runs its own step last, so generated types are always `number[]`, plus `null` when the field is optional. |

## Admin options

Vector fields use the JSON editor and support the standard [field admin options](https://docs.frogbot.ai/fields/overview.md#admin-options), plus these options:

| Option | Type | Default | Description |
| - | - | - | - |
| `editorOptions` | `EditorProps['options']` | — | Monaco editor options for the JSON editor, such as `minimap` or `tabSize`. |
| `maxHeight` | `number` | — | Maximum editor height in pixels. The editor grows with its content up to this height. |

## Write and read vectors

In trusted server-side code, use the [Local API](https://docs.frogbot.ai/local-api/overview.md). This example explicitly bypasses collection access; for request-scoped operations, pass the request and use `overrideAccess: false` instead.

```ts theme={"theme":"tokyo-night"}
import { getFrogBot } from 'frogbot';

import config from './frogbot.config';

const frogbot = await getFrogBot({ config });

const created = await frogbot.create({
  collection: 'articles',
  data: { title: 'Account recovery', embedding: [0.5, -1, 0] },
  overrideAccess: true,
});

const updated = await frogbot.update({
  collection: 'articles',
  id: created.id,
  data: { embedding: [1, 2, 3] },
  overrideAccess: true,
});

const article = await frogbot.findByID({
  collection: 'articles',
  id: updated.id,
  overrideAccess: true,
});

await frogbot.delete({
  collection: 'articles',
  id: article.id,
  overrideAccess: true,
});

await frogbot.destroy();
```

`dimensions` must be a positive integer. A supplied value must be an array of exactly that many finite numbers; strings, `NaN`, and `Infinity` are rejected. Optional fields may be omitted or set to `null`; set `required: true` to require a value on normal writes. Generated collection types represent vector values as `number[]` with optional/null behavior according to the field configuration. The field uses the JSON editor in the admin panel; `admin.hidden` or `admin.readOnly` changes presentation, not API permissions.

> [!WARNING]
>
> Set vectors in a [collection hook](https://docs.frogbot.ai/hooks/collections.md) or in the vector field's own
> [hooks](https://docs.frogbot.ai/hooks/fields.md). FrogBot validates the vector after those hooks run. Hooks on other fields
> run at the same time as the vector's validation, so a vector they set after an `await` can be
> saved without validation, including in drafts.

Matching dimensions do not guarantee two embeddings use the same model or embedding space. Updating or deleting the record does not regenerate embeddings. See [Search](https://docs.frogbot.ai/search/overview.md) for the index and query API's current availability.

## Storage

Vectors are stored as JSON arrays by default. A database adapter can instead map each vector field, with its path and dimensions, to a native vector column through the adapter's `mapVectorField` option. None of the built-in adapters provides native vector storage yet, so every adapter uses the JSON default today.


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