Vector field

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:

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.
`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.
`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 or inside a localized parent.
`defaultValue`	`number[]` or `({ locale, req, user }) => value`	—	Value used when the field has no value. See default values.
`validate`	`Validate<number[]>`	—	Extra validation that runs after FrogBot checks the length and that every value is a finite number. See validation.
`hooks`	`{ beforeValidate, beforeChange, afterChange, afterRead, beforeDuplicate }`	—	Arrays of `FieldHook` functions for each phase. See field hooks.
`access`	`{ create, read, update }`	Allowed	`FieldAccess` functions for each operation. See field access control.
`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.
`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.
`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.
`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. 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, 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. This example explicitly bypasses collection access; for request-scoped operations, pass the request and use overrideAccess: false instead.

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.

Set vectors in a collection hook or in the vector field’s own hooks. 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 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.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Configure a vector field

Config options

Admin options

Write and read vectors

Storage

​Configure a vector field

​Config options

​Admin options

​Write and read vectors

​Storage

Configure a vector field

Config options

Admin options

Write and read vectors

Storage